Interaction of "$ref" with "definitions"

[handrews]

As discussed in json-schema-org/JSON-Schema-Test-Suite#197 and earlier in json-schema-org/JSON-Schema-Test-Suite#113 and json-schema-org/JSON-Schema-Test-Suite#129, definitions is not like validation keywords and there is a fairly compelling argument that it should not be ignored.

This fits in with the refinements to the theoretical model and processing order that we started to introduce in draft-07: classifying keywords as working with applicability, assertions, and/or annotations. definitions is in its own category, existing solely as a way to organize re-usable schemas as $ref targets.

Arguably, definitions also belongs in core with $ref. It has nothing to do with validation or even annotations (which live in the validation spec, at least for now).

[Anthropic]

Totally agree it belongs in the core.

[Julian]

Just to elaborate on what I said elsewhere -- if the stance we want to take is the one I've been going with, it's pretty important to point out but not to make definitions special, because the same behavior should apply to somerandomproperty that you put in the schema that isn't part of the core JSON Schema specifications -- whatever extension somerandomproperty is from will not (should not) use it for validation, but if you reference subelements in it, they'd be acceptably reference-able.

(Not sure ^ contradicts anything in this issue, but pointing it out since I don't think I've mentioned that case on any of the previous issues)

[handrews]

@Julian I'm glad you posted because while that's not quite how I was thinking of it, it's not incompatible either. It really gets down to the question of what $ref is and how it works, which I am going to file separately and link to this issue as there are several aspects of that question. This issue will focus just on the case of definitions and keywords that we want to treat similarly (whatever that ends up meaning).

[semanino]

IMHO, as far as definitions and $ref are concerned, the discussion on how it should be modelled comes down to the point that they try to meet two different aspects:

• aspect one: a kind of "library" of schema building blocks, just like e.g. in programming a library of string functions. This is what definitions implements.
• aspect two: schemas for real-world applications, which arbitrarily use schema building blocks from said libraries. This is what $ref iplements.

Current $ref does not differentiate between these two aspects, nor does $schema.

Now what makes things a little difficult in terms of modelling is the fact that a library of schemas will have many possible $ref targets whitin root level, whereas a "normal" schema requires exactly one such at its root level. Currently, to keep "normal" schema definitions concise, this single root element is not denoted explicitly; instead, its members are directly put into root scope, which i deem as fine.

As a result I'd like to suggest the following for consideration:

• specification of attribute $schema-library which is only allowed on a file's root level
• this file can not be a direct target of a $ref; instead, only its elements can be referenced
• attributes $schema-library and $schema are mutually exclusive
• contents of $schema-library: like definitions
• generally deny $ref to a $schema file

Pros:

• each part which is to be used as a building block within multiple schemas must be put into a library, which drives reuseability
• schemas still can define "local-only" reusable parts to keep them concise, but these can not be addressed from outside

Cons:

• the number of schema definition files will increase

[Relequestual]

@semanino Please file a new issue outlining your problem statement and resolution. Please do not bring new requests into existing issues.

[handrews]

Given that we've decided on delegation as the $ref behavior in #514, I think this will become a moot point. With $ref being delegation, there's no longer any reason to prohibit adjacent keywords- they simply behave like any other keyword (the validation results of all keywords in a schema object are AND-ed, and any collected annotations are combined per the rules for each annotation keyword).

So while we need to wait until we've nailed down that behavior in a PR, if it goes that way then we won't need to make any special case out of definitions or any other keyword with $ref.

[handrews]

This is now made moot by the combination of #514 and #523, both of which have been accepted for draft-08. Closing.