can "definitions" (instead of $defs) be used with meta-schema 2019-09/2020-12?

[bill-okara]

Hi,

just want to confirm, when using meta schema 2019-09 or 2020-12, can "definitions" still be used? or can only use "$defs"?

Asking because some mentioned that "definitions" can still be used,

In drafts 06 and 07 $defs keyword was named definitions, this has changed starting with draft 2019-09. Don’t worry, definitions can still be used (you can use any name, it doesn’t really matter).

But some validators ONLY recognize "$defs" with 2019-09 / 2020-12, like

• jschon.dev
• networknt/json-schema-validator

and gave error or not validating properly if "definitions" was used, e.g.,

while other validator recognizes the "definitions", like

• JSON Schema Validator

thanks!

[gregsdennis]

definitions is still valid, though not preferred. If you have the ability to change $schema why not also change definitions to $defs?

Better yet, use alterschema to do the upgrade for you.

[bill-okara]

thanks! regarding

If you have the ability to change $schema why not also change definitions to $defs?

was actually testing some editor's schema bundling feature, and that seemed to always use "definitons" and not really recognize "$defs", even with 2020-12 meta schema. thus trying to use "definitions", then encountered some validators only recognized "$defs"... thus a bit confused / frustrating...

[gregsdennis]

That is strange. I would consider those that claim to process 2019-09/2020-12 schemas but don't recongnize $defs to be non-compliant.

[karenetheridge]

I agree with Greg. $defs MUST be recognized as a source of subschemas.

The problem with using definitions in a draft2020-12 schema is that any identifiers ($id, $anchor, $dynamicAnchor keywords) therein will not be recognized, and therefore $refs elsewhere that use those identifiers will fail to resolve. To draft2020-12, definitions is an unknown keyword. I would argue that the evaluator MUST NOT detect identifiers therein (a vocabulary would need to be formally defined to contain this keyword and its semantics), but would accept that the spec is silent on that point at present.

[handrews]

@bill-okara in terms of the spec, there are two issues:

1. 2019-09 is the first draft to formally defined bundling, and it (like 2020-12) uses $defs and not definitions. Prior to that, bundling was informal. So, really, tools should update. But if they're more reference and less JSON Schema, it's all a bit ambiguous.
   There's a big discussion about this happening over at AsyncAPI right now, actually (reference tooling in general).

2. There's an "implementation-defined" behavior here, which is specification-ese for "we couldn't agree on what should happen so we punted." The details are kind of obscure, but the upshot is that there are two valid ways for JSON Schema tooling to look at things:

   • one is that something is only a schema if it is a root object or a child of a recognized keyword that is known to have a subschema at that location. For 2020-12, by default this includes $defs but not definitions. This favors predictability over flexibility. Some implementations will let you also enable definitions.
   • the other is that you can try to resolve any JSON Pointer fragment, and just attempt to use whatever is there. Which favors flexibility over predictability, as sometimes you'll reference a bunch of garbage.

Non-JSON Schema reference tooling doesn't care whether something is a schema or not, so it tends to use the second approach.

[bill-okara]

thank you for the info! I guess another challenge I encountered was trying to build some common/shareable schema libraries that could be used in both OpenAPI bundling (JSON reference) and JSON schema bundling to achieve what's said in this post

Bundling SHOULD be done in such a way that all URIs (used for referencing) in the base document and any referenced/ embedded documents do not require altering."