Skip to content

clarify that contentSchema holds a subschema and when/how it applies #1564

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Feb 14, 2025
Merged

clarify that contentSchema holds a subschema and when/how it applies #1564

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
11216df
clarify that contentSchema holds a subschema and when/how it applies
gregsdennis Nov 21, 2024
8e0466f
apply text wrap
gregsdennis Nov 21, 2024
6342ec3
update note about processing contentSchema subschema in context
gregsdennis Nov 23, 2024
a90049e
Update specs/jsonschema-validation.md
gregsdennis Nov 28, 2024
f6276dc
contentSchema should not produce an annotation
gregsdennis Nov 28, 2024
87f6201
Update specs/jsonschema-validation.md
gregsdennis Jan 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
update note about processing contentSchema subschema in context
  • Loading branch information
@gregsdennis
gregsdennis committed Jan 17, 2025
commit 6342ec3754eed4ba4dfbf8585e71a70dba034cb6
16 changes: 12 additions & 4 deletions specs/jsonschema-validation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -547,10 +547,18 @@ 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.

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
resource with both `$schema` and an absolute IRI `$id`.
Note that evaluating the `contentSchema` subschema in-place (i.e. as part of its
parent schema) will ensure that it is correctly processed. Independent use of
Comment on lines +550 to +551
Copy link
Member

@jdesrosiers jdesrosiers Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My initial reaction was that this doesn't make sense. The annotation is just the subschema. It's no longer in-place. It doesn't include the context of where it came from. So, how can it be evaluated in-place? Then it occurred to me that an annotation includes not just it's value, but also the schema location it came from and that location can be used to evaluate the contentSchema in-place. I don't think most readers are going to be knowledgeable enough to make that leap. This could use some clarification.

Copy link
Member Author

@gregsdennis gregsdennis Jan 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the footnote ([^7]) that follows not provide that clarity?

Copy link
Member

@jdesrosiers jdesrosiers Jan 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, that's not the thing I'm saying needs to be clarified. We say that the annotation is the subschema. We say that the subschema shouldn't be evaluated out of context from where it appeared in the schema and we explain why in footnote 7. What we don't explain is given a subschema without its parent context, how is it even possible to evaluate it in context. The value of the annotation is just the subschema, not the context. We can't evaluate the subschema in context because we don't know the context in which it needs to be evaluated. I hope that makes sense this time.

Of course the solution is that the location of the annotation keyword in the schema is how you know the context, but that's not intuitive. This is the only annotation where the location of the keyword in the schema is useful or necessary to know. Usually, we only care about the value of the annotation. In this case, we need to know the value and the schema location of the annotation. Actually, when used correctly (in context), the value of the annotation is useless and it's the schema location that the user actually uses.

Copy link
Member Author

@gregsdennis gregsdennis Jan 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the only annotation where the location of the keyword in the schema is useful or necessary to know. Usually, we only care about the value of the annotation.

This is incorrect. Annotation location has always been useful, especially in cases where you receive annotations from the same keyword in different locations, e.g. from title. The location allows the consumer to decide which (or both/all) it wants to use. This is Core, where annotations are defined.

We can't evaluate the subschema in context because we don't know the context in which it needs to be evaluated.

How would we not know the context? It's conveyed by the annotation location, which has always been defined to be a part of an annotation.

It's still not clear why you think that the existing text (including the lines following these) is insufficient. It's saying, "Don't just evaluate this annotation value as a schema because it may rely on things that exist externally to it. You probably need to evaluate it where it came from."

It's actually saying all of that, and then the footnote expands on that warning using an example.

Copy link
Member

@jdesrosiers jdesrosiers Jan 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can't evaluate the subschema in context because we don't know the context in which it needs to be evaluated.

How would we not know the context? It's conveyed by the annotation location, which has always been defined to be a part of an annotation.

Yes, you're right. I acknowledged that in next paragraph. I was walking you through my thought process when I first read it and what I believe the vast majority of readers will be thinking when they read this section. If it took me a minute to make that connection, most readers won't make it at all. Yes, the concept is unambiguously documented elsewhere, but most readers won't have every detail of JSON Schema memorized and I think this is a pretty esoteric detail.

the extracted subschema (as returned in an annotation) is only safe if the
subschema is an embedded reource which defines both a `$schema` and an absolute
IRI `$id`.[^7]

[^7] Processing a non-resource subschema in place will ensure that any
references (e.g. `$ref`) are always resolved properly. This isn't a problem when
the subschema is itself a resource. See
https://github.com/json-schema-org/json-schema-spec/issues/1381 for several
examples where processing this subschema independently can cause `$ref`
resolution failure.

### Example

Expand Down