What are Vocab Meta-Schemas?

[gregsdennis]

Resolution

We decided in the OCWM call that $vocabulary could be removed from the vocab meta-schemas. The PRs are linked in a thread below.

---

This came up while I was writing #510, but it was a sufficiently separate topic that I figured a new discussion was warranted. Please have a read of at least the opening comment there as some of that context will likely apply here.

To be honest, I never thought about the 2020-12 vocab meta-schemas only having their own vocab URI in the $vocabulary keyword. I'm not sure I even noticed it when I was writing my own vocabs.

I'm not sure how that works, though, because as a meta-schema, it's allowing keywords defined by vocabs in $vocabulary (which is only its own keywords) to be used in a schema described by it... but a vocab meta-schema isn't actually describing a schema. It's only used to build a dialect.

As a result I'm not sure that the vocab meta-schemas really needs a $vocabulary keyword. Is it even really a meta-schema? Or is it just a regular schema? (I'm leaning toward regular schema.)

[jdesrosiers]

This has come up a few times before. I think we eventually all agreed that including those $vocabulary keywords (1) has no effect and (2) doesn't make sense. When used as a vocabulary schema, it's simply not used. If you try to use the schema as a dialect schema, it's missing the required "core" vocabulary.

I'm not sure that the vocab meta-schemas really needs a $vocabulary keyword.

Agreed. $vocabulary is only used when the schema is being used as a dialect schema, so $vocabulary doesn't belong in vocabulary schemas.

Is it even really a meta-schema? Or is it just a regular schema?

I would still consider it a meta-schema. Even if it isn't intended to validate a full dialect, it's still validating a schema.

[jdesrosiers]

I'm not sure that we need to update the date marker in the URI, but we can. We'd end up with a 2020-12 spec that uses a 2023-11 meta-schema. Personally I think that would just add more confusion than making what would otherwise be a transparent change.

This has come up a few times before. We decided that changing it would be too confusing for users, but came up with a sort of compromise where the 2020-12 URI would remain and always point to the latest version, but also have an alternative URI that can be used if users want something guaranteed not to change. For example, new versions could be released as /draft/2020-12/schema/{version}. This makes it clear that the version is still 2020-12. And, having /draft/2020-12/schema be an alias for /draft/2020-12/schema/{latest-version} means people don't need to keep up with the latest version whenever we change it.

Iirc, this plan had support, but slipped through the cracks and never got implemented. IMO, it's unnecessary and changing it in place is fine for the very few times we need to do it, especially because we're quite conservative about when we make meta-schema changes.

Are you saying that you want us to retroactively fix 2019-09 and 2020-12 (can we?), or just fix draft-next?

Generally our policy has been to only update meta-schemas to fix bugs. This is more unused code than a bug. I'd prefer not to change old meta-schema because if they aren't causing problems and just fix this going forward, but I'm not against cleaning this up retroactively.

[gregsdennis]

I lean more toward retroactive updates; it's just cleaning out the attic.

Also, it would be beneficial for @jviotti's work, in which he's describing how to build vocabs, and he's using the 2020-12 meta-schemas as a template.

[jviotti]

When is this expected to change? There is a hard deadline for delivering every chapter this Friday, so I only have until then to change things, otherwise it'd have to wait for a second edition.

[gregsdennis]

@jviotti there are three PRs linked above. Generally we wait two weeks to merge spec-repo changes, but we might be able to fast track this if people are on board.

[jviotti]

Thanks for merging them so quickly! I addressed this on the book drafts too.