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.

[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.

[notEthan]

That footnote works for me. 'behavior' and 'directive' are implemented the same way in mine, the difference just being whether the behavior/directive takes an instance.

[jdesrosiers]

I'm finding this sentence difficult to follow. I'm not sure what "referenced" means in this context. Also, I don't think it's necessary to say subschema "or" boolean schema because boolean schemas are subschemas. I'm also unsure what "modified" means in this context. What does it mean for an applicator to modify the result of a subschema?

[notEthan]

'referenced' seems okay to me; $ref has a referenced schema that isn't a subschema - although maybe that is better mentioned above in the initial description of applicator keyword behavior.

The 'boolean' refers to an assertion result, not type of subschema, though the words/phrases run together a bit and it's difficult to parse how they are grouped (even knowing all the terms, much less while learning them).

Suggested change

	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
	Applicator keywords also behave as assertions, using the assertion results of
	each subschema or referenced schema of the keyword. These boolean results are
	modified (e.g. the `not` keyword negates its subschema's assertion) and/or
	combined (e.g. `allOf` takes the conjunction of its subschemas' assertions)
	to produce the boolean result of the applicator.

Not quite polished - not suggesting that be put in as is, just thinking through what I might find to read better. (The spec is always very light on examples, I assume intentionally so maybe those don't go in, but I do always find they make the more generalized spec language much easier to connect to what it is describing).

[jdesrosiers]

'referenced' seems okay to me; $ref has a referenced schema that isn't a subschema

$ref is just a keyword in a subschema. It's sufficient to call { "$ref": "..." } a subschema. It's not something different because it happens to contain a reference.

(I wouldn't say the same thing before 2019-09. Back then I would call it something different than a schema.)

[notEthan]

sure, a schema containing a $ref isn't different than any other, but taking $ref as an applicator keyword, the schema it is doing application of is its referenced schema, not a subschema (I think I recall that your implementation does make it a subschema, but in the original document it isn't)

[jdesrosiers]

Oh, I see what you mean. $ref is an applicator but its value isn't a subschema, it's a reference. Good point!

[jdesrosiers]

I prefer to stick with the "behavior" terminology for these things. What does it even mean to "produce an assertion result"? Is it a statement about output? (Those are rhetorical questions.) I think sticking to "behavior" terminology avoids that confusion. What matters is that the keyword has no affect on the validation result.

Suggested change

	This keyword produces no assertion result. The value of this keyword is used as
	its annotation result.
	This keyword has no assertion behavior. The value of this keyword is used as
	its annotation result.

[notEthan]

I'm not sure what this is aiming to prevent.

Behaviors outside the three above? I'm not sure what that would be. That also seems more the concern of the definition of an extension keyword rather than an implementation.

Or behaviors within the three, but that aren't in a specification? If so, that seems just the nature of a specification, that an implementation of it sticks to its specified behaviors.

[jdesrosiers]

See, this thread.

[notEthan]

This references Core Spec Keyword Behaviors but then also repeats, or is redundant with, a significant amount of that section.

[gregsdennis]

The validation spec uses the phrase "an instance validates against this keyword if...", or some variant of it, quite a lot. I just wanted to define what that means. The phrasing is different than "this keyword exhibits assertion behavior by...", which feels more clunky to me (and I'd have to change a lot of places).