Move "definitions" to core (as "$defs"?)

[handrews]

In #505 I commented that definitions fits better into core than validation (and @Anthropic agreed).

The point of definitions is simply to reserve a keyword under which you can safely collect named schemas, without worrying that they will get accidentally interpreted by an extended vocabulary.

definitions also allows packaging multiple schemas in a file for re-use as $ref targets without having to explicitly assign $ids. In that sense, it is most closely associated with $ref and $id, both of which are part of core.

Furthermore, having a designated re-use location has nothing to do with validation or any other particular JSON Schema use case. Reading through the validation spec it seems quite out of place. For the last several drafts, there has even been a specific note in its description that it does not affect validation.

When you have to explain how the keyword has nothing to do with the purpose of the specification, that's probably a sign that the keyword is in the wrong place.

Anyone seriously object to moving this?

[erayd]

Moving this into core sounds like a good idea. Core makes much more sense as a logical home for the definitions keyword, as the keyword itself doesn't actually imply any action - it's simply a well-known location where schema definitions may be stored.

In order to maintain consistency with other core keywords, it seems sensible to rename it to $definitions. Doing so will improve obviousness going forward, and seems unlikely to adversely impact users.

[handrews]

@erayd I suppose there wouldn't be any harm in officially reserving $definitions and perhaps deprecating definitions but noting that extension vocabularies MUST NOT give it different behavior. It's not like references to #/definitions/... would stop working :-P

[erayd]

@handrews That sounds like a good idea.

[erayd]

On a related note, would it also be possible to specify that arbitrary schema fragments SHOULD NOT appear outside of [$]definitions (other than locations already defined by the spec obviously, e.g. under properties), and that implementations MAY treat any schema that is defined in a nonstandard location as equivalent to {}?

The particular use-case I'm thinking of is a validation implementation which compiles a schema definition into procedural logic for direct execution against a document. Any circumstance which results in an inbound remote reference to a nonstandard location would necessarily imply lazy compilation, which adds significant implementation complexity and may be highly undesirable - in such cases, this would allow the implementation to ignore inbound references to a nonstandard location.

[handrews]

@erayd I don't think we should forbid it (although the thought has actually crossed my mind before, so I get your point here). But there's nothing preventing an implementation from saying "if you only put $ref targets under $definitions, your schema will be pre-compiled and fast, and otherwise it may be slow."

I definitely think that reaching into sub-pieces of other schemas (like referencing a particular property schema) is bad form- factor the subschema out to definitions and have both locations reference it. But that's a linter/best practices thing, not a specification thing.

Also, someone writing an extension vocabulary may come up with a good reason to have another location for schemas.

[awwright]

"definitions" is basically the same thing as a comment. I don't see a problem with this.

[Anthropic]

@handrews funny how similar this thread is to what I was discussing with you earlier and I hadn't seen this at that point :)

[handrews]

Sounds like the main question is whether to add the $ prefix or not. @json-schema-org/spec-team ?

I had thought not, but am warming to the idea. It would place $definitions, $id, $ref, and $schema clearly in the same category (while #513 which would move keywords like properties over almost certainly does not need the $ prefix as they are a different sort of keyword and, while important, slightly less fundamental)