Create an Applicators section, group into a Keyword Behaviors section #595
Conversation
Move the general description of applicators from the applicator vocabulary to a section alongside the Assertion and Annotation sections. Rework the text a bit, and also clarify an aspect of annotation collection related to applicators.
This is purely a reformatting plus the new section tags, no text has been changed. Group the Annotation, Assertion, and Application sections. This new section will get an intro paragraph in the next commit. Arguably, this has overgrown the "Overview" section, but since the "Vocabulary" part of the overview is also about to be expanded, let's wait until then to figure out how to refactor it.
This attempts to explain the general framework for keywords and provide guidance on creating new keywords with respect to that framework.
jsonschema-core.xml
Outdated
| either passes or fails the assertions. This approach can be used to validate | ||
| conformance with the constraints, or document what is needed to satisfy them. | ||
| JSON Schema keywords fall into several general behavior categories. | ||
| Assertions validate that an instance satisfies constraints, annotations |
There was a problem hiding this comment.
I'd break this into three sentences.
There was a problem hiding this comment.
OK. Do you think sentences work well for it, or should I make a little bullet-point list? I've gone back and forth on it.
There was a problem hiding this comment.
Updated- I went with sentences for now.
jsonschema-core.xml
Outdated
| JSON Schema keywords fall into several general behavior categories. | ||
| Assertions validate that an instance satisfies constraints, annotations | ||
| attach information that applications may use in any way they see fit, | ||
| and applicators allow for building more complex schemas than a single |
There was a problem hiding this comment.
Would it be accurate to say something like "Applicators allow a sub-schema to be applied recursively to some part of the instance, or the entire instance." ?
The current description wasn't clear to me.
There was a problem hiding this comment.
I don't think so? Applicators are not inherently recursive. I mean, you can do that by using $ref in particular, but just applying properties or items for one level does not fit that description.
"allow for building more complex schemas" is definitely vague, but the rest of the section is supposed to explain it in more detail.
There was a problem hiding this comment.
Throughout these PRs (and earlier changes) I classify applicators as "in-place" or "child" applicators. I would not say "the entire instance" because people will take that to mean the whole instance document, which may be a much larger chunk of JSON than the current location.
Just saying "Applicators allow a sub-schema to be applied to some part of the instance." might be fine, though? We'd just leave the enumeration of the different locations to the more detailed explanation.
jsonschema-core.xml
Outdated
| primitive type. When the type of the instance is not of the type | ||
| targeted by the keyword, the instance is considered to conform | ||
| to the assertion. | ||
| Evaluation of an instance against a |
There was a problem hiding this comment.
Is there a difference between "evaluation" and "application"?
There was a problem hiding this comment.
Hmm... yes that's unclear. There is a difference, I'll add some text in the Keyword Behaviors intro section about it.
|
Also, you can now change the diff settings within GitHub to ignore whitespace \o/ |
|
Also this section would be a good place to remark on the existence of "argument keywords" (for lack of a better term), properties in the schema that do nothing by themselves, but are used by other keywords, or affect the behavior of other keywords. The old boolean form of "exclusiveMinimum"/"exclusiveMaximum" would be the best example of this. |
I did not know that! Ah, I see you can only do it while looking at an individual diff. I will continue putting whitespace-only changes in their own commit, which is what i did here. |
Take a look at PR #600. That kind of effect can be defined in terms of annotation behavior, which keeps it all within a simpler theoretical framework. I also think that modifiers like the boolean |
|
@awwright could you see if my changes address your concerns and let me know? A lot of other work is stacked up on this PR so it would be great to get it merged. |
ghost
deleted a comment
gregsdennis
added
clarification
NOTE: The second commit in this PR indents for a new section without changing the text, so it's best to look at each commit separately.
This is groundwork for more of the vocabulary and annotation
collection process work.
Move the general description of applicators from the applicator
vocabulary to a section alongside the Assertion and Annotation
sections. Rework the text a bit, and also clarify an aspect
of annotation collection related to applicators.
Group the Annotation, Assertion, and Application sections
as Keyword Behaviors.
Arguably, this has overgrown the "Overview" section, but since
the "Vocabulary" part of the overview is also about to be
expanded, let's wait until then to figure out how to refactor it.