-
-
Notifications
You must be signed in to change notification settings - Fork 345
Split Overview into the two specific use cases (resubmission) #1579
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
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is introducing a lot of new terms, which could cause confusion -- generally we have been saying "evaluator" and "valid" or "invalid". I would prefer we stick to one set of terms rather than introducing new overlapping ones.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Further, the JSON Schema document itself is not the evaluator/validator, but rather describes rules for evaluation, when applied against a provided JSON document ("data instance").
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The goal of this phrasing is to relate the concepts behind JSON Schema to the general concepts that pre-exist JSON Schema. If you're from the world of computer languages, grammars, and parsers, then this will introduce you to the terms used in JSON Schema in terms that you're already familiar with. If you're from the world of JSON then this will introduce you to the terminology that you will inevitably end up seeing elsewhere.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've never seen "recognizer" or "acceptor" used, either in the world of JSON Schema or outside it. "Validator" and "parser" have much higher recognition IMO.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Consider the page https://en.wikipedia.org/wiki/Finite-state_machine (of which the vast majority of keywords in JSON Schema fall within a https://en.wikipedia.org/wiki/Pushdown_automaton specifically) — the word "valid" doesn't even show up. This passage helps build a bridge to this audience.
What kind of change does this PR introduce?
Issue & Discussion References
Replaces #1370
Summary
Note
This is a resubmission of @awwright's #1370. Please refer there for extensive conversation. The below text is also from that PR.
This is an alternative to #1244, and like that issue, this one should be incorporated prior to #1365. This PR makes a clearer distinction between validation uses and annotation uses that 1365 will draw on (it relies on classifying which use each keyword is being used for, since validation use is different from annotation use).
This PR moves vocabulary-related discussion deeper into the specification, and replaces Overview with a specific description of what a JSON Schema can do, especially in terms of its output.
Once its capabilities are described, the rest of the specification can describe how you write a schema that can do these things.
This replaces the Overview section, which is a little bit redundant with the above Abstract, then Introduction, sections.
Does this PR introduce a breaking change?
No.