Skip to content

Core: Improve language for schema references section #551

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 6 commits into from
Mar 1, 2018
Merged

Core: Improve language for schema references section #551

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9e69ef6
Core: Improve language for schema references section
awwright Feb 28, 2018
6b541c0
Move the schema references preamble back up to the top of the section
awwright Feb 28, 2018
f51f8cb
Clarify/strenghten some security considerations
awwright Feb 28, 2018
adf96df
Core: Cite definition at first usage of URI in the section
awwright Feb 28, 2018
ad91243
s/name/plain name/
awwright Mar 1, 2018
d9abd15
Core: Link to Hypermedia section instead
awwright Mar 1, 2018
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
48 changes: 27 additions & 21 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -528,6 +528,11 @@
</section>

<section title="Base URI and Dereferencing">
<t>
To differentiate between schemas in a vast ecosystem, schemas are
identified by <xref target="RFC3986">URI</xref>, and can embed references to other schemas by specifying their URI.
</t>

<section title="Initial Base URI">
<t>
<xref target="RFC3986">RFC3986 Section 5.1</xref> defines how to determine the
Expand Down Expand Up @@ -557,8 +562,8 @@
<section title="Identifying the root schema">
<t>
The root schema of a JSON Schema document SHOULD contain an "$id" keyword with
a URI (containing a scheme). This URI SHOULD either not have a fragment, or
have one that is an empty string.
an <xref target="RFC3986">absolute-URI</xref> (containing a scheme, but no fragment),
or this absolute URI but with an empty fragment.
<!-- All of the standard meta-schemas use an empty fragment in their id/$id values. -->
</t>
</section>
Expand All @@ -583,18 +588,16 @@
without requiring JSON Pointer references to be updated.
</t>
<t>
To name subschemas in a JSON Schema document,
subschemas can use "$id" to give themselves a document-local identifier.
This is done by setting "$id" to a URI reference consisting
only of a plain name fragment (not a JSON Pointer fragment).
The fragment identifier MUST begin with a letter ([A-Za-z]), followed by
any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons
(":"), or periods (".").
To specify such a subschema identifier,
the "$id" keyword is set to a URI reference with a plain name fragment (not a JSON Pointer fragment).
This value MUST begin with the number sign that specifies a fragment ("#"),
then a letter ([A-Za-z]),
followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"),
colons (":"), or periods (".").
</t>
<t>
The effect of defining a fragment-only "$id" URI reference that neither
matches the above requirements nor is a valid JSON pointer
is not defined.
The effect of using a fragment in "$id" that isn't blank or doesn't follow the
plain name syntax is undefined.
<cref>
How should an "$id" URI reference containing a fragment with other components
be interpreted? There are two cases: when the other components match
Expand Down Expand Up @@ -711,11 +714,14 @@
</t>
<section title="Loading a referenced schema">
<t>
To differentiate schemas between each other in a vast ecosystem, schemas are
identified by URI. As specified above, this does not necessarily mean
anything is downloaded, but instead JSON Schema implementations SHOULD
already understand the schemas they will be using, including the URIs that
identify them.
The use of URIs to identify remote schemas does not necessarily mean anything is downloaded,
but instead JSON Schema implementations SHOULD understand ahead of time which schemas they will be using,
and the URIs that identify them.
</t>
<t>
When schemas are downloaded,
Copy link
Contributor

Choose a reason for hiding this comment

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

I don't follow this paragraph. Taking the dependent clause out I read "When schemas are downloaded... see Usage over HTTP" which is a bit unclear.

Could this be rephrased as something like:

"For use cases when it is desirable to download schemas, such as a hypermedia system where schemas are discovered at runtime, see Usage for Hypermedia"

Note I'm proposing linking to section 11 as a whole rather than 11.3, because the actual linking of a downloadable schema is covered in 11.1, and I think that is needed to fully understand the issue (along with 11.3).

Copy link
Member Author

Choose a reason for hiding this comment

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

Oh, I totally missed that. Yes, I was looking for that section.

for example by a generic user-agent that doesn't know until runtime which schemas to download,
see <xref target="hypermedia">Usage for Hypermedia</xref>.
</t>
<t>
Implementations SHOULD be able to associate arbitrary URIs with an arbitrary
Expand All @@ -728,7 +734,7 @@
<t>
A schema MAY (and likely will) have multiple URIs, but there is no way for a
URI to identify more than one schema. When multiple schemas try to identify
with the same URI, validators SHOULD raise an error condition.
as the same URI, validators SHOULD raise an error condition.
</t>
</section>
<section title="Dereferencing">
Expand Down Expand Up @@ -829,7 +835,7 @@
</t>
</section>

<section title="Usage for Hypermedia">
<section title="Usage for Hypermedia" anchor="hypermedia">

<t>
JSON has been adopted widely by HTTP servers for automated APIs and robots. This
Expand Down Expand Up @@ -974,12 +980,12 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
<t>
Instances and schemas are both frequently written by untrusted third parties, to be
deployed on public Internet servers.
Validators should take care that the parsing of schemas doesn't consume excessive
Validators should take care that the parsing and validating against schemas doesn't consume excessive
system resources.
Validators MUST NOT fall into an infinite loop.
</t>
<t>
Servers need to take care that malicious parties can't change the functionality of
Servers MUST ensure that malicious parties can't change the functionality of
existing schemas by uploading a schema with an pre-existing or very similar "$id".
</t>
<t>
Expand Down