keywords only exhibit the behaviors they're defined with

[gregsdennis]

What kind of change does this PR introduce?

clarification

Issue & Discussion References

• Closes ✨ Proposal: Not all keywords need to produce a validation result. #1540
• Closes Applicator, Assertion, and Annotation as behaviors not categories #1447

Summary

The previous language could imply that all keywords needed to have an assertion result, e.g. annotations would always produce a "true" assertion result.

For min/maxContains, I added explicit text that they do not produce an assertion result, emphasizing that the assertion comes from contains and that these keywords are informative.

This change clarifies that keywords only exhibit the behaviors they're defined with.

Does this PR introduce a breaking change?

No.

[karenetheridge]

So, what is the result of:

allOf: [
  { maxContains: 1 },
  { maxContains: 1 },
]

and

anyOf: [
  { maxContains: 1 },
  { maxContains: 1 },
]

and

oneOf: [
  { maxContains: 1 },
  { maxContains: 1 },
]

?

[gregsdennis]

Good point. The keywords produce no assertions, but the subschemas still need to.

Granted, this is true with 2020-12, too. The validation spec doesn't actually define assertion results for any of the annotations, yet it's still considered a pass because there are no constraints.

I think this could be stated explicitly.

[jdesrosiers]

I've always thought of all keywords having an assertion. Annotation-only keywords just always assert true. $defs is another example of a keyword always returns true although it's not an annotation.

I think the way this is worded is great because it allows for implementations to ignore non-assertions or just make them true. They can implement it however makes most sense for their implementation.

[jdesrosiers]

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?

[gregsdennis]

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.

[gregsdennis]

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

[jdesrosiers]

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.

[gregsdennis]

I've added a footnote and changes this to SHOULD NOT.

[notEthan]

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.

[gregsdennis]

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.

[jdesrosiers]

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.

[gregsdennis]

I've added a footnote. Let me know.

I tend to agree with @jdesrosiers on this. The $* keywords are more of directives than anything else, and I don't think we should be listing "directive" as a behavior. It would encourage people to try to make more.

[jdesrosiers]

Suggested change

	- Annotations attach information that applications may use in any way they see
	fit.
	- Annotations attach information to instance locations that applications may use in any way they see
	fit.

[jdesrosiers]

I don't understand what you mean by "interfering with schema processing".

The way I see it, people should avoid creating these kinds of keywords because it's unlikely that an implementation will be able to support them using typical extension mechanisms. At least my implementation wouldn't.

[jdesrosiers]

I'm not sure what this means. It sounds like it's saying that if you say it doesn't have an assertion behavior, then it shouldn't have an assertion behavior. Is there some nuance that I'm missing?