[mini-rfc] YAML schema validation

[alicewriteswrongs]

I wanted to open a (not very urgent) conversation about our approach to validating site configs here in Studio. Right now we are using a library called Yamale to validate site configs against a schema. This works pretty well for ensuring that a WebsiteStarter can't be saved with an invalid configuration and whatnot, but I think there are a few limitations /drawbacks to this approach:

• the Yamale schema is specific (afaict) to Yamale, and is not an open standard like JSON Schema, locking us into Python and Yamale somewhat (for JSON Schema, by contrast, there are a very large number of different implementations that could be used)
• the schema file is checked in to ocw-studio, which prevents us from validating schemas that are stored elsewhere (see add yaml formatter, CI checks for validity, etc ocw-hugo-projects#112 for a relevant discussion)

I'm wondering if we might want to explore two separate things, 1) converting to use a standardized data schema format like JSON Schema (or one specific to yaml if it exists) and 2) pulling the schema validation out into a library or something so that we could have github actions checking the validity of our site configs in ocw-hugo-projects (and possibly elsewhere in the future).

Anyhow, just something I was thinking about, interested to hear what you all think!

[gumaerc]

I think moving to use JSON would be a fine idea, especially if it gives us better and more portable validation like you describe. It's always bugged me a bit that we have starter configs checked into the ocw-studio repo, when really the source of truth is ocw-hugo-projects. Even the name of that repo was sort of chosen out of necessity, I think it would make more sense to call in ocw-hugo-config or something like that. Either way, when we run unit tests in studio that consume the starters, they should probably be using the release branch version of the starters in ocw-hugo-projects. Hugo doesn't consume the starter files, only ocw-studio does, so changing the format shouldn't have any consequences outside of how they are consumed in `ocw-studio.

[ChristopherChudzicki]

I've used JSON schema a bit in the past and was was very happy with it... Most of my experience is using it is through OpenAPI specs and with the js ajv.

Definitely appealing that it's not language-specific... Then there's more tooling around it, e.g., linters. And this always looked intriguing to me, though I've never used it: https://www.npmjs.com/package/json-schema-to-typescript

[alicewriteswrongs]

We don’t even need to necessarily use JSON as a storage format, we could continue to use Yaml for writing the configuration, and then convert the Yaml to JSON in order to validate it. I’m fine either way, I’m not attached to either one, but we do have some options. `json-schema-to-typescript` sounds very interesting…I’ve used an OpenAPI to typescript library before which enabled automated backend-frontend type sharing, I think that could let us do something similar (right now our configuration types are basically declared in two places, in the Yamale thing and in typescript). I also agree about the checked-in configs, it would be good to just automate using the configs from the repo and delete the checked-in ones I think.

[ChristopherChudzicki]

If we ever revisit this, I think we should consider JSON Type Definition (JTD), too. AJV has a nice comparison between JTD and JSON Schema.

JTD is newer and probably not as widely supported, which is definitely a con.

But JTD "describes the shape of the data" whereas Json Schema describes "a collection of constraints on the data". Consequently, JTD integrates more smoothly with Typescript (and probably other typed languages). As an example, I believe one consequence of this is

• with Json Schema, we would have to compile the schemas into Typescript types (or types for other languages). That's an extra build step
• with JTD, Typescript can infer the types from the schema itself