Skip to content

Clarify how JSON Schema works with a superset of the defined data model #970

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Sep 6, 2020
Merged

Clarify how JSON Schema works with a superset of the defined data model #970

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 25 additions & 19 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,15 @@
<t>
A JSON document to which a schema is applied is known as an "instance".
</t>
<t>
JSON Schema is defined over "application/json" or compatible documents,
including media types with the "+json" structured syntax suffix.
</t>
<t>
Among these, this specification defines the "application/schema-instance+json"
media type which defines handling for fragments in the URI,
and the "schema" media type parameter.
</t>

<section title="Instance Data Model">
<t>
Expand Down Expand Up @@ -243,25 +252,6 @@
</t>
</section>

<section title="Instance Media Types">
<t>
JSON Schema is designed to fully work with "application/json" documents,
as well as media types using the "+json" structured syntax suffix.
</t>
<t>
Some functionality that is useful for working with schemas is
defined by each media type, namely media type parameters and
URI fragment identifier syntax and semantics. These features are
useful in content negotiation and in calculating URIs for specific
locations within an instance, respectively.
</t>
<t>
This specification defines the "application/schema-instance+json"
media type in order to allow instance authors to take full advantage
of parameters and fragment identifiers for these purposes.
</t>
</section>

<section title="Instance Equality">
<t>
Two JSON instances are said to be equal if and only if they are of the same type
Expand All @@ -288,6 +278,22 @@
zeros) are insignificant.
</t>
</section>

<section title="Non-JSON Instances">
<t>
It is possible to use JSON Schema with a superset of the JSON Schema data model,
where an instance may be outside any of the six JSON data types.
</t>
<t>
In this case, annotations still apply; but validation keywords will not be useful,
as they will always pass or always fail.
</t>
<t>
A custom vocabulary may define support for a superset of the core data model.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • does this paragraph belong in the section "Non-JSON Instances"?

  • does this paragraph mean that a custom vocabulary may be expressed in terms of another custom vocabulary? Or that this is not permitted and the core vocabulary only may be used? (I strongly prefer the latter, as implementations could otherwise be stuck in a recursive chain of "load vocabulary X first to understand vocabulary Y". I'd at least want someone to show an example of this being done (e.g. in an appendix) to demonstrate that it allowed and provide a potential test case for implementations.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does this paragraph belong in the section "Non-JSON Instances"?

If an implementations adds support for a superset of the data model, that means it's supporting data that cannot be represented by application/json. The way for a schema to declare using this superset would be with a custom $schema keyword.

does this paragraph mean that a custom vocabulary may be expressed in terms of another custom vocabulary

I haven't really thought that far out, but that seems like a concern for the vocabularies section.

(I hope I'm understanding the question correctly.)

The schema itself may only be expressible in this superset;
for example, to make use of the "const" keyword.
</t>
</section>
</section>

<section title="JSON Schema Documents" anchor="schema-document">
Expand Down