"Applicability", annotations, & hyper-schema

[handrews]

While JSON Schema validation is fundamentally built on the idea that each pairing of a (sub-)schema and (sub-)instance can be evaluated in isolation, this idea breaks down for features built on the idea of associating information with the (sub-)instance as a result of validation outcomes.

In JSON Hyper-Schema, the links keyword attaches Link Description Objects (LDOs) to each (sub-)instance from every (sub-)schema against which it successfully validates in the process of validating the complete instance against the complete schema document.

---

For the purpose of this issue, a (sub-)schema is said to be applicable to a (sub-)instance if it validates in this way. When processing a particular application of a (sub-)schema to a (sub-)instance, the particular (sub-)instance is said to be the point or location of attachment, and may be identified by a JSON Pointer (other identifiers may be possible or even more appropriate, for this issue we will assume JSON Pointers). Applicable (sub-)schemas may be identified either by their $id or a JSON Pointer within a given schema document.

Calculating applicability and attachment can be thought of as a function taking an instance document and a schema document and producing the many-to-many map of schemas to their attachment points and instances to their applicable schemas. Of course, it is possible to generate only specific portions of the mapping as needed rather than producing it all at once.

---

It seems clear to me that implementing the concept of applicability is a MUST requirement for a JSON Hyper-Schema implementation. Fundamentally, you can only do anything in hyper-schema if you can find all of the links that apply to a given location.

It also seems clear that it is a requirement for properly implementing the annotation keywords as well (title, description, examples, default, readOnly, and whatever we do for deprecation). To make use of any of these, you start from a (sub-)instance and need to know what value(s) of whichever keyword you are considering apply.

Some of the usage challenges of the annotation keywords come from this requirement. The semantics of finding multiple applicable links in hyper-schema are clear: just put all of their LDOs in a set together, it doesn't matter which (sub-)schema provided a given LDO.

A similar approach should work for examples.

For readOnly, it seems logical that if it is true in any applicable schema, then it is true overall. Deprecation would probably work something like this, although depending on how much information is involved in the concept it may be more complex (see #74 for extensive discussion).

title and description are less clear. One could reasonably just use all descriptions, although the result might be somewhat incoherent to read. Applying multiple titles is less reasonable; generally a title is supposed to be concise and to the point.

And of course it's a train wreck for default, which confuses people more than enough when it's just a single schema being applied to a single attached instance.

---

I'm not quite sure what sort of resolution I want here. Some feedback on the terminology would be helpful, as I am writing it up in the Hyper-Schema spec as part of the rewrite mentioned in #377

The question part of this is more about whether this helps us reason about the annotation keywords. In the debate over deprecation in #74, I complained that I did not want to have to figure out this sort of applicability in order to decide whether something is deprecated or not. But now I think that it is something that any system querying annotations would have to implement anyway. Am I missing something?

This shows up a bit in #364 as well, about changing readOnly from a boolean to an array like required. In this framework, the question is about which point of attachment is the most convenient for querying and processing this information. Note that making readOnly an array would make it's multiple-applicable-schema semantics like links and examples: just treat the array values as sets and take a union.

---

As a final, only slightly related note: definitions, which is currently in the "Metadata keywords" section with the annotation keywords, is not involved in this. Neither applicability or attachment matter at all for definitions. I'd almost say it belongs in the Core spec, as the typical target of $ref. But that's a discussion for another issue.

For now, do these concepts make sense to anyone else? Do they seem at all helpful, particularly for the challenge of designing how to structure and use keywords like readOnly, deprecated, default, etc.?

@awwright @epoberezkin @Julian @Relequestual @dlax @adamvoss

[dlax]

Some feedback on the terminology would be helpful

I think the "applicability" and "attachment" terminology makes sense and is a useful clarification.

[Relequestual]

I'm not quite sure what sort of resolution I want here.

I'm not really sure I understand what question you're asking.

The phrasing you've used is helpful and understandable (to me at least). It's not clear to me which parts of your issue post are quotes from your re-write and which are not. I'm not really sure what this issue trying to address.

[handrews]

@Relequestual I sorted it out. See PR #424.

[handrews]

Merged #424.