Skip to content
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

keywords only exhibit the behaviors they're defined with #1577

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

keywords only exhibit the behaviors they're defined with #1577

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
969dc42
keywords only exhibit the behaviors they're defined with
gregsdennis Jan 19, 2025
6c0c64e
Update specs/jsonschema-core.md
gregsdennis Feb 2, 2025
c47bcd7
Apply suggestions from code review
gregsdennis Feb 2, 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
66 changes: 42 additions & 24 deletions specs/jsonschema-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -410,20 +410,37 @@ keywords MUST NOT begin with this prefix.
Implementations MUST refuse to evaluate schemas which contain keywords which
they do not know how to process or explicitly choose not to process.

## Keyword Behaviors
## Keyword Behaviors {#keyword-behaviors}

JSON Schema keywords fall into several general behavior categories. Assertions
validate that an instance satisfies constraints, producing a boolean result.
Annotations attach information that applications may use in any way they see
fit. Applicators apply subschemas to parts of the instance and combine their
results.
JSON Schema keywords may exhibit one or more behaviors. This specification
defines three such behaviors:
Copy link
Contributor

Choose a reason for hiding this comment

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

This seems to say that all keyword behaviors in the specification are in these three categories, but the spec defines other behaviors for e.g. $id and $anchor/$dynamicAnchor. And $schema ... exists.

Copy link
Member Author

Choose a reason for hiding this comment

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

That is an interesting point. I was thinking that these keywords don't exhibit a behavior so much as they are merely informative, like maxContains would be to contains.

Copy link
Member

Choose a reason for hiding this comment

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

This is a great point! My implementation doesn't even treat those as keywords. They're meta-data used to process the schema, but they're not directly part of the validation/annotation process. So, I wouldn't consider them similar to maxContains that is involved in validation.

I'm not sure what I'd suggest, but I think something needs to be called that these aren't normal keywords.


- Assertions validate that an instance satisfies constraints, producing a
boolean result: `true` if the constraints are satisfied; `false` otherwise.
- Annotations attach information that applications may use in any way they see
fit.
- Applicators apply subschemas to parts of the instance and combine their
results.

Extension keywords SHOULD stay within these categories, keeping in mind that
Extension keywords SHOULD be defined using these behaviors, keeping in mind that
annotations in particular are extremely flexible. Complex behavior is usually
better delegated to applications on the basis of annotation data than
implemented directly as schema keywords. However, extension keywords MAY define
other behaviors for specialized purposes.

Keywords which are not defined to exhibit a particular behavior MUST NOT affect
that aspect of evalution. For example, a keyword which does not act as an
assertion MUST NOT affect the validation result.

For the purposes of this document, an instance "validating against a keyword"
means that the keyword produces an assertion result of `true` if the instance
satisfies the given constraint; otherwise an assertion result of `false` is
produced.

<!-- The next two paragraphs and the following section seem to have to more to
do with schema evaluation than keywords specifically. I'd like to move them out
of the "keyword behaviors" h2, but will do so separately. [TODO: GD] -->

Evaluating an instance against a schema involves processing all of the keywords
in the schema against the appropriate locations within the instance. Typically,
applicator keywords are processed until a schema object with no applicators (and
Expand Down Expand Up @@ -564,11 +581,11 @@ the keyword's value. Alternatively, an applicator may refer to a schema
elsewhere in the same schema document, or in a different one. The mechanism for
identifying such referenced schemas is defined by the keyword.

Applicator keywords also define how subschema or referenced schema boolean
[assertion](#assertions) results are modified and/or combined to produce the
boolean result of the applicator. Applicators may apply any boolean logic
operation to the assertion results of subschemas, but MUST NOT introduce new
assertion conditions of their own.
Applicator keywords also behave as assertions by defining how subschema or
referenced schema boolean [assertion](#assertions) results are modified and/or
combined to produce the boolean result of the applicator. Applicators may apply
any boolean logic operation to the assertion results of subschemas, but MUST NOT
introduce new assertion conditions of their own.
Comment on lines +587 to +588
Copy link
Member

Choose a reason for hiding this comment

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

but MUST NOT introduce new assertion conditions of their own.

I'm not following this. What is this trying to say? What are we protecting against be forbidding it?

Copy link
Member Author

Choose a reason for hiding this comment

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

That text was already there.

It's just saying that applicator assertions can only be combinatorial on their subschemas. For instance anyOf only ORs the results of its subschemas without asserting anything else.

I think this is a simplicity guard, kind of a JSON Schema version of SRP. I suppose this means something like requiredProperties would be in violation of the spec since it's combining subschema results and asserting that all of the properties are there.

Copy link
Member Author

Choose a reason for hiding this comment

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

@jdesrosiers what do you think of relaxing this to a SHOULD, or maybe even an informative note suggesting simplicity over complexity?

Copy link
Member

Choose a reason for hiding this comment

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

I don't think it's unnecessary for that to be a constraint. Your requiredProperties example is great. Although I'm not a fan of that keyword, I don't think there should be any spec reason why it shouldn't be allowed.

or maybe even an informative note suggesting simplicity over complexity?

Yes. I think that's a great idea.


[Annotation](#annotations) results from subschemas are preserved in accordance
with {{collect}} so that applications can decide how to interpret multiple
Expand Down Expand Up @@ -993,21 +1010,22 @@ identified schema. Its results are the results of the referenced schema.[^5]
[^5]: Note that this definition of how the results are determined means that
other keywords can appear alongside of `$ref` in the same schema object.

The value of the `$ref` keyword MUST be a string which is a IRI reference.
The value of the `$ref` keyword MUST be a string which is an IRI reference.
Resolved against the current IRI base, it produces the IRI of the schema to
apply. This resolution is safe to perform on schema load, as the process of
evaluating an instance cannot change how the reference resolves.

The resolved IRI produced by `$ref` is not necessarily a network
locator, only an identifier. A schema need not be downloadable from the address
if it is a network-addressable URL. Implementations which can access the network
SHOULD default to operating offline.
The resolved IRI produced by `$ref` is not necessarily a network locator, only
an identifier. A schema need not be downloadable from the address if it is a
network-addressable URL. Implementations which can access the network SHOULD
default to operating offline.

##### Dynamic References with `$dynamicRef` {#dynamic-ref}

The `$dynamicRef` keyword is an applicator that allows for deferring the full
resolution until runtime, at which point it is resolved each time it is
encountered while evaluating an instance.
encountered while evaluating an instance. Its results are the results of the
referenced schema.

Together with `$dynamicAnchor`, `$dynamicRef` implements a cooperative extension
mechanism that is primarily useful to to create open schemas, where
Expand Down Expand Up @@ -1465,8 +1483,8 @@ operators can contact the owner of a potentially misbehaving script.

## Keywords for Applying Subschemas

This section defines a set of keywords that enable schema combinations and
composition.
This section defines a set of applicator keywords that enable schema
combinations and composition.

### Keywords for Applying Subschemas in Place {#in-place}

Expand Down Expand Up @@ -1727,8 +1745,8 @@ The value of this keyword MUST be a non-negative integer.
This keyword modifies the behavior of `contains` within the same schema object,
as described below in the section for that keyword.

Validation MUST always succeed against this keyword. The value of this keyword
is used as its annotation result.
This keyword produces no assertion result. The value of this keyword is used as
its annotation result.

##### `minContains`

Expand All @@ -1737,8 +1755,8 @@ The value of this keyword MUST be a non-negative integer.
This keyword modifies the behavior of `contains` within the same schema object,
as described below in the section for that keyword.

Validation MUST always succeed against this keyword. The value of this keyword
is used as its annotation result.
This keyword produces no assertion result. The value of this keyword is used as
its annotation result.

Per {{default-behaviors}}, omitted keywords MUST NOT produce annotation results.
However, as described in {{contains}}, the absence of this keyword's annotation
Expand Down
17 changes: 16 additions & 1 deletion specs/jsonschema-validation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,21 @@ information. The {{format}} keyword is intended primarily as an annotation, but
can optionally be used as an assertion. The {{content}} keywords are annotations
for working with documents embedded as JSON strings.

## Keyword Behaviors

The keywords defined by this document exhibit one or more behaviors as defined by
the [JSON Schema Core Specification](./jsonschema-core.md#keyword-behaviors).

Keywords which are not defined to exhibit a particular behavior MUST NOT affect
that aspect of the evalution outcome. In particular, the keywords defined in
{{annotations}} produce no assertion result and therefore are not considered
during validation.

For the purposes of this document, an instance "validating against a keyword"
means that the keyword produces an assertion result of `true` if the instance
satisfies the given constraint; otherwise an assertion result of `false` is
produced.

## Interoperability Considerations

### Validation of String Instances
Expand Down Expand Up @@ -614,7 +629,7 @@ structures: first the header, and then the payload. Since the JWT media type
ensures that the JWT can be represented in a JSON string, there is no need for
further encoding or decoding.

## Keywords for Basic Meta-Data Annotations
## Keywords for Basic Meta-Data Annotations {#annotations}

These general-purpose annotation keywords provide commonly used information for
documentation and user interface display purposes. They are not intended to form
Expand Down
Loading