Creating Third-Party Vocabs

[gregsdennis]

Hey everyone. @jviotti and I have been discussing the proper way to make a third-party vocab. It seems that we've found two approaches, and we wanted to get others' opinions.

(In the process of writing this, I had some additional questions fall out. I've opened #511 for that so the topics don't get too muddled.)

Option 1

This option is based on the 2020-12 meta-schemas. Each vocabulary has its own meta-schema, then they're all combined into a 2020-12 dialect meta-schema.

A vocab spec - This is a document that defines the keywords both syntactically, semantically, and behaviorally. It includes the vocab identifier URI and a vocab meta-schema URI. It can also give a reason why they're needed, use cases, etc. The definition is the important part, though.

Vocab meta-schema - This is a meta-schema that only describes the vocab itself. It contains a $vocabulary keyword that only contains the vocab URI, and it doesn't directly reference the main (e.g. 2020-12) meta-schema (unless one of the other keywords is an applicator). Keywords are defined here with subschemas that it can enforce syntax.

Dialect meta-schema - This meta-schema actually extends another meta-schema (e.g. 2020-12) by incorporating all of its vocabularies plus the custom vocab. It then references (via $ref) the base meta-schema and the vocab meta-schema so that validation of all of the keywords can occur. Lastly, it defines $dynamicAnchor: meta so that dynamic references come back to this meta-schema.

Option 2

The same as the above, except the vocab and dialect meta-schemas are combined. There's a single meta-schema that both extends the base meta-schema (2020-12 in this case) and defines syntax for the added keywords.

This is how I've done my data (link) and uniqueKeys (link) vocabs. The distinction isn't that huge, but I feel that doing it this way saves having to write another document.

---

I wrote mine a couple years ago, and to my knowledge the only other third-party vocab is OpenAPI's, and they didn't publish a meta-schema (I don't think).

It seems to me that Option 1 has an advantage over Option 2 in that the vocab meta-schema can be reused across multiple dialects (even across JSON Schema versions). That makes a lot of sense, except that the meta-schema itself still needs a meta-schema, which inevitably ends up being the current main JSON Schema meta-schema (e.g. 2020-12). Maybe that's not really a problem, though.

[jviotti]

I might be missing something, but I can't tell of any advantage of Option 1 over Option 2, and vocabulary meta-schemas defining $vocabulary without even core in there is confusing. Maybe there is a way to simplify how official meta-schemas are declared?

[jdesrosiers]

vocabulary meta-schemas defining $vocabulary without even core in there is confusing.

Agreed, but that's getting into #511

[jdesrosiers]

to my knowledge the only other third-party vocab is OpenAPI's, and they didn't publish a meta-schema (I don't think).

I exists. I wrote it back in March 2021.

• Dialect Schema - https://spec.openapis.org/oas/3.1/dialect/base
• Vocabulary Schema - https://spec.openapis.org/oas/3.1/meta/base
• Repo - https://github.com/OAI/OpenAPI-Specification/tree/main/schemas/v3.1

[jdesrosiers]

I think either approach is fine depending on the dialect author's intended use. If your custom vocabulary is only intended to be used by your custom dialect, then putting them in the same schema is fine. However, the intention of a vocabulary is often for it to be shared and combined with other vocabularies. For that to work, you need a separate vocabulary schema.

Let's assume I created a vocab with keyword foo and Greg created a vocab with keyword bar. We each make combined dialect/vocab schemas for our keywords. Now Juan wants to create a dialect that includes both foo and bar. Juan wouldn't be able to use our schemas to construct his dialect. He would need to manually merge the schemas Greg and I provided along with whatever else he was including in his dialect. If we had provided standalone vocabulary schemas, all Juan would need to do is reference those schemas.

So, the default should definitely be Option 1, but if the vocabulary is entirely private and used only in one dialect, Option 2 is fine too.

[Relequestual]

This was pretty much the note I was going to make. I agree, either way is fine, but you should understand the tradeoffs being made with picking either approach.

In addition, it's possible to bundle the vocabulary meta-schema into the dialect meta-schema, where you then retain the best of both ideas. Or, at least it becomes easy to swap between the different tradeoffs.

[gregsdennis]

I don't think that we should adopt an "either is fine" policy, though. Vocabs are confusing enough. As it is, we have no recommended way to build them. Having multiple recommended ways to build them doesn't help.

I think we need to have a single recommended approach to building a vocab. That's not to say it can't work if it's built another way, just that we recommend a particular way.

I'm working on building a new version of my data vocab now, so I'm happy to update it to whatever we decide.

[jdesrosiers]

I would teach (and have taught) Option 1 to anyone learning these concepts. While Option 2 works, it's limited in it's reusability and composability. I wouldn't recommend Option 2, but I wouldn't have a problem with someone using it if they know and accept the trade-offs.

[gregsdennis]

From this discussion, I also think Option 1 should be the preferred way. I'll need to update my vocabs (which I've already started working on) and the associated docs.