clarify that contentSchema holds a subschema and when/how it applies #1564
Conversation
specs/jsonschema-validation.md
Outdated
| Since `contentMediaType` is required to provide instruction on how to interpret | ||
| string content, the annotation schema produced by this keyword has no meaning if | ||
| `contentMediaType` is not present. |
There was a problem hiding this comment.
I think I would prefer that no annotation is produced at all if contentMediaType is missing -- in order to discourage structuring schemas in this way.
There was a problem hiding this comment.
Does that then also mean that identifiers are not to be processed in that case?
There was a problem hiding this comment.
Does that then also mean that identifiers are not to be processed in that case?
IMO, it should always be treated as a normal schema location and therefore always respect identifiers. But, I agree that it shouldn't produce an annotation if it isn't valid.
There was a problem hiding this comment.
Are we happy with it saying that an annotation SHOULD not be produced (etc.)?
There was a problem hiding this comment.
I think it should be a "MUST".
specs/jsonschema-validation.md
Outdated
|
|
||
| Accessing the schema through the schema location IRI included as part of the | ||
| annotation will ensure that it is correctly processed as a subschema. Using the | ||
| extracted annotation value directly is only safe if the subschema is an embedded |
There was a problem hiding this comment.
"safe" and "correctly processed as a subschema" is vague -- can we say something else? I think this is trying to say that the evaluation behaviour won't be reproducable because the schema is evaluated in isolation, rather than in the context of the surrounding dialect and location identifier (from the containing schema's $schema and $id keywords). So how about instead saying something like:
Because this subschema is intended to be processed in isolation, outside of the context of its containing schema, usage of both the
$schemaand$idkeywords is recommended to ensure predictable and reproducable results.
There was a problem hiding this comment.
This text was already present. I just put it in a new paragraph. I did think it was a bit convoluted. Happy to update it.
There was a problem hiding this comment.
I do think it could be okay to use the subschema in its original context, so that should still be addressed. This is what the original discussion was about.
specs/jsonschema-validation.md
Outdated
|
|
||
| Accessing the schema through the schema location IRI included as part of the | ||
| annotation will ensure that it is correctly processed as a subschema. Using the | ||
| extracted annotation value directly is only safe if the subschema is an embedded |
There was a problem hiding this comment.
Maybe we should make this a SHOULD?
There was a problem hiding this comment.
I'm not sure what you're suggesting. This is informative, not a requirement.
There was a problem hiding this comment.
So from what I'm reading here, there are edge cases in contentSchema if the schema doesn't have $id and $schema. If that's the case, shouldn't we highlight in more of a "SHOULD" manner, which from what I understand, it something you should do rather than a MUST (something you HAVE to do)? Or maybe "RECOMMENDED" is the right one similar to this case: https://json-schema.org/draft/2020-12/json-schema-validation#section-7.2.2-5?
There was a problem hiding this comment.
It's not an edge case. It just means that if you intend to use the contentSchema subschema solely in its own context, as you would if you received it as an annotation, then any relative $refs will only be resolvable if the subschema has both $schema and $id.
This goes back to my comment here where I show a contentSchema subschema attempting to reference a definition in its parent schema. If you extract the subschema (again, because you've received it as an annotation), then that reference fails.
There's not a best practice here. Both approaches have valid use cases, and schema authors are free to do what makes sense for them. This is merely a caution to schema authors to understand the implications of their approach.
There was a problem hiding this comment.
It's obvious to me from @karenetheridge's and your comments that this paragraph isn't clear, so I'll reword it.
|
@karenetheridge / @jviotti I've rewritten the last paragraph note and added another "editor" footnote that points back to the subject issue linked above. Let me know what you think. |
|
Reads much better now! |
specs/jsonschema-validation.md
Outdated
| Since `contentMediaType` is required to provide instruction on how to interpret | ||
| string content, the annotation schema produced by this keyword has no meaning if | ||
| `contentMediaType` is not present. |
There was a problem hiding this comment.
Does that then also mean that identifiers are not to be processed in that case?
IMO, it should always be treated as a normal schema location and therefore always respect identifiers. But, I agree that it shouldn't produce an annotation if it isn't valid.
Co-authored-by: Jason Desrosiers <[email protected]>
|
@karenetheridge @jdesrosiers @jviotti I believe I've addressed your concerns here. |
What kind of change does this PR introduce?
clarification
Issue & Discussion References
Summary
Updates the text for
contentSchemato indicate that its value is indeed a subschema (and therefore should be treated as such when scanning for identifiers). Also cleans up language around its dependency oncontentMediaType.I didn't include any explicit text about it containing identifiers. Instead I declare that the value is a subschema and removed the "SHOULD ignore" text discussed in the issue.
Also pertinent to the issue discussion is the final couple sentences (already present), which I
broke out into a new paragraphrewrote to make it more apparent that it is a note of guidance rather than a requirement.Does this PR introduce a breaking change?
No.