Skip to content

unevaluated* updates (and some annotation dependency cleanup) #1541

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.

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 10 commits into from
Nov 7, 2024
Next Next commit
update unevaluated* dependency sections to remove notions of annotati…
…on control
  • Loading branch information
gregsdennis committed Oct 12, 2024
commit f1422a02e216afcd60b87c68c58e077d266cdfe5
64 changes: 27 additions & 37 deletions jsonschema-core.md
Original file line number Diff line number Diff line change
Expand Up @@ -1645,27 +1645,23 @@ and the instance value are affected by this keyword.
This keyword produces an annotation value which is the largest index to which
this keyword applied a subschema. The value MAY be a boolean true if a subschema
was applied to every index of the instance, such as is produced by the `items`
keyword. This annotation affects the behavior of `items` and `unevaluatedItems`.
keyword.

The presence of this keyword affects the behaviors of [`items`](#items) and
[`unevaluatedItems`](#unevaluateditems).

##### `items` {#items}

The value of `items` MUST be a valid JSON Schema.

This keyword applies its subschema to all instance elements at indexes greater
than the length of the `prefixItems` array in the same schema object, as
reported by the annotation result of that `prefixItems` keyword. If no such
annotation result exists, `items` applies its subschema to all instance array
elements.[^11]

[^11]: Note that the behavior of `items` without `prefixItems` is identical to
that of the schema form of `items` in prior drafts. When `prefixItems` is
present, the behavior of `items` is identical to the former `additionalItems`
keyword.
This keyword applies its subschema to all instance elements at indices greater
than the length of the `prefixItems` array in the same schema object. If
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
This keyword applies its subschema to all instance elements at indices greater
than the length of the `prefixItems` array in the same schema object. If
This keyword applies its subschema to all instance elements at indices greater
than or equal to the length of the `prefixItems` array in the same schema object. If

Given that json arrays are indexed from 0: If prefixItems had 3 items, then the items keyword applies to all elements at index 3 and greater, not those greater than 3.

Copy link
Member Author

Choose a reason for hiding this comment

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

json arrays are indexed from 0

JSON 8259 doesn't specify and indexing base. Seems more like a programming language thing to me.

I'll see if I can fix this so that it doesn't mention indices at all.

Copy link

@mwadams mwadams Oct 23, 2024

Choose a reason for hiding this comment

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

Maybe

This keyword ignores instance elements in the array, up to and including the number of items found in the prefixItems array in the same schema object. It then applies its subschema to all subsequent instance elements.

Copy link
Member

Choose a reason for hiding this comment

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

https://www.rfc-editor.org/rfc/rfc6901.html#section-4 specifies that JSON pointer indexes are zero-based.

I don't see how we can avoid indexes because that's a necessary part of the annotation content for these keywords (and contains contains a list of indexes, not just the number of evaluated/validated elements), and we also use array indexes in any JSON pointer in a $ref, and in keywordLocations and absoluteKeywordLocations in error objects.

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's a very good point. I think it's important to state that we're using zero-based indexing and reference that section.

I'll work that in. Thanks for the... pointer 😏

Copy link
Member Author

Choose a reason for hiding this comment

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

I've left this in as-is (without references to indexing), but I've also added a section specifically about array indices.

`prefixItems` does not exist within the same schema object, `items` applies its
subschema to all instance array elements.

If the `items` subschema is applied to any positions within the instance array,
it produces an annotation result of boolean true, indicating that all remaining
array elements have been evaluated against this keyword's subschema. This
annotation affects the behavior of `unevaluatedItems`.
array elements have been evaluated against this keyword's subschema.

Omitting this keyword has the same assertion behavior as an empty schema.

Expand All @@ -1674,6 +1670,9 @@ that produces the same effect, such as by directly checking for the presence and
size of a `prefixItems` array. Implementations that do not support annotation
collection MUST do so.

The presence of this keyword affects the behavior of
[`unevaluatedItems`](#unevaluateditems).

#### Keywords for Applying Subschemas to Objects

##### `properties`
Expand All @@ -1685,11 +1684,13 @@ Validation succeeds if, for each name that appears in both the instance and as a
name within this keyword's value, the child instance for that name successfully
validates against the corresponding schema.

Omitting this keyword has the same assertion behavior as an empty object.

The annotation result of this keyword is the set of instance property names
which are also present under this keyword. This annotation affects the behavior
of `additionalProperties` and `unevaluatedProperties`.
which are also present under this keyword.

Omitting this keyword has the same assertion behavior as an empty object.
The presence of this keyword affects the behavior of
[`additionalProperties`(#additionalProperties) and [`unevaluatedProperties`](#unevaluatedproperties).

##### `patternProperties`

Expand All @@ -1704,11 +1705,13 @@ instance for that name successfully validates against each schema that
corresponds to a matching regular expression. Recall: regular expressions are
not implicitly anchored.

Omitting this keyword has the same assertion behavior as an empty object.

The annotation result of this keyword is the set of instance property names
matched by at least one property under this keyword. This annotation affects the
behavior of `additionalProperties` and `unevaluatedProperties`.
matched by at least one property under this keyword.

Omitting this keyword has the same assertion behavior as an empty object.
The presence of this keyword affects the behavior of
[`additionalProperties`(#additionalproperties) and [`unevaluatedProperties`](#unevaluatedproperties).

##### `additionalProperties` {#additionalproperties}

Expand All @@ -1723,26 +1726,13 @@ that do not appear in the annotation results of either `properties` or
For all such properties, validation succeeds if the child instance validates
against the `additionalProperties` schema.

The annotation result of this keyword is the set of instance property names
validated by this keyword's subschema. This annotation affects the behavior of
`unevaluatedProperties`.

Omitting this keyword has the same assertion behavior as an empty schema.

Implementations MAY choose to implement or optimize this keyword in another way
that produces the same effect, such as by directly checking the names in
`properties` and the patterns in `patternProperties` against the instance
property set. Implementations that do not support annotation collection MUST do
so.[^12]

[^12]: In defining this option, it seems there is the potential for ambiguity in
the output format. The ambiguity does not affect validation results, but it does
affect the resulting output format. The ambiguity allows for multiple valid
output results depending on whether annotations are used or a solution that
"produces the same effect" as draft-07. It is understood that annotations from
failing schemas are dropped. See our [Decision
Record](https://github.com/json-schema-org/json-schema-spec/tree/HEAD/adr/2022-04-08-cref-for-ambiguity-and-fix-later-gh-spec-issue-1172.md)
for further details.
The annotation result of this keyword is the set of instance property names
validated by this keyword's subschema.

The presence of this keyword affects the behavior of
[`unevaluatedProperties`](#unevaluatedproperties).

##### `propertyNames`

Expand Down
Loading