-
-
Notifications
You must be signed in to change notification settings - Fork 347
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
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -45,46 +45,45 @@ The terms "JSON", "JSON text", "JSON value", "member", "element", "object", | |
| "array", "number", "string", "boolean", "true", "false", and "null" in this | ||
| document are to be interpreted as defined in [RFC 8259](#rfc8259). | ||
|
|
||
| ## Overview | ||
|
|
||
| This document proposes a new media type `application/schema+json` to identify a | ||
| JSON Schema for describing JSON data. It also proposes a further optional media | ||
| type, `application/schema-instance+json`, to provide additional integration | ||
| features. JSON Schemas are themselves JSON documents. This, and related | ||
| specifications, define keywords allowing authors to describe JSON data in | ||
| several ways. | ||
|
|
||
| JSON Schema uses keywords to assert constraints on JSON instances or annotate | ||
| those instances with additional information. Additional keywords are used to | ||
| apply assertions and annotations to more complex JSON data structures, or based | ||
| on some sort of condition. | ||
|
|
||
| To facilitate re-use, keywords can be organized into vocabularies. A vocabulary | ||
| consists of a list of keywords, together with their syntax and semantics. A | ||
| dialect is defined as a set of vocabularies and their required support | ||
| identified in a meta-schema. | ||
|
|
||
| JSON Schema can be extended either by defining additional vocabularies, or less | ||
| formally by defining additional keywords outside of any vocabulary. Unrecognized | ||
| individual keywords are not supported. | ||
|
|
||
| This document defines a set of core keywords that MUST be supported by any | ||
| implementation, and cannot be disabled. These keywords are each prefixed with a | ||
| "$" character to emphasize their required nature. These keywords are essential | ||
| to the functioning of the `application/schema+json` media type. | ||
|
|
||
| Additionally, this document defines a RECOMMENDED set of keywords for | ||
| applying subschemas conditionally, and for applying subschemas to the contents | ||
| of objects and arrays. These keywords, or a set very much like them, are | ||
| required to write schemas for non-trivial JSON instances, whether those schemas | ||
| are intended for assertion validation, annotation, or both. While not part of | ||
| the required core set, for maximum interoperability this additional | ||
| set is included in this document and its use is strongly encouraged. | ||
|
|
||
| Further keywords for purposes such as structural validation or hypermedia | ||
| annotation are defined in other documents. These other documents each define a | ||
| dialect collecting the standard sets of keywords needed to write schemas for | ||
| that document's purpose. | ||
| ## Validation | ||
|
|
||
| A JSON Schema document describes a validator (also known as a "recognizer" or | ||
| "acceptor") which classifies a provided JSON document as "accepted" or | ||
| "rejected." | ||
|
Comment on lines
+50
to
+52
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 commentThe 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 commentThe 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 commentThe 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 commentThe 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. |
||
|
|
||
| It supports "structural validation" (context-free grammars), and certain more | ||
| complicated conditions. Validation follows JSON semantics, so two documents that | ||
| are value-equal, but vary only by character escapes, property ordering, or | ||
| whitespace, will validate with the same result. | ||
|
|
||
| A condition for accepting a document is called an "assertion". Assertions impose | ||
| constraints that instances must conform to. Given a schema and an instance, the | ||
| schema "accepts" an input whenever all the assertions are met, and the schema | ||
| "rejects" when any of the assertions fail. Schemas without any assertions accept | ||
| all JSON documents. | ||
|
|
||
| Assertions are encoded into a JSON Schema using "keywords," described below. | ||
|
|
||
| ## Annotations | ||
|
|
||
| A schema may also describe an "annotator," a way to read an instance and output | ||
| a set of "annotations." Annotations can be any output metadata about that | ||
| instance. | ||
|
|
||
| For example, you can document the meaning of a property, suggest a default value | ||
| for new instances, generate a list of hyperlinks from the instance, or declare | ||
| relationships between data. Applications may make use of annotations to query | ||
| for arbitrary information; for example, to extract a list of names from a | ||
| document with a known structure. Annotations may also describe values within the | ||
| instance in a standard way; for example, extracting a common type of hyperlink | ||
| from many different types of documents, using a different | ||
|
|
||
| Like assertions, the instructions for producing annotations are encoded in a | ||
| schema using keywords. Output is only defined over valid instances, so | ||
| annotations are not returned until the input has been validated. However, not | ||
| all valid input is meaningful or true to a given application. That is, if you | ||
| process an arbitrary instance with nonsense data, the resulting annotations may | ||
| not necessarily be true, even though the input is valid. | ||
|
|
||
| ## Definitions | ||
|
|
||
|
|
||