Skip to content
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

Minimal change from "profile" to "schema" #414

Merged
merged 1 commit into from
Oct 20, 2017
Merged

Minimal change from "profile" to "schema" #414

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
39 changes: 22 additions & 17 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
<!ENTITY RFC5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
<!ENTITY RFC6839 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6839.xml">
<!ENTITY RFC6901 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6901.xml">
<!ENTITY RFC6906 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6906.xml">
<!ENTITY RFC7049 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7049.xml">
<!ENTITY RFC7159 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7159.xml">
<!ENTITY RFC7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
Expand Down Expand Up @@ -675,7 +674,7 @@

<section title='Linking to a schema'>
<t>
It is RECOMMENDED that instances described by a schema/profile provide a link to
It is RECOMMENDED that instances described by a schema provide a link to
a downloadable JSON Schema using the link relation "describedby", as defined by
<xref target="W3C.REC-ldp-20150226">Linked Data Protocol 1.0, section 8.1</xref>.
</t>
Expand All @@ -696,21 +695,23 @@ Link: <http://example.com/my-hyper-schema#>; rel="describedby"
</section>


<section title='Describing a profile of JSON' anchor="profile">
<section title='Identifying a schema via a media type parameter' anchor="parameter">
<t>
Instances MAY specify a "profile" as described in
<xref target="RFC6906">The 'profile' Link Relation</xref>.
When used as a media-type parameter, HTTP servers gain the ability to perform
Content-Type Negotiation based on profile.
Media types MAY allow for a "schema" media type parameter, which gives
HTTP servers the ability to perform Content-Type Negotiation based on schema.
The media-type parameter MUST be a whitespace-separated list of URIs
(i.e. relative references are invalid).
</t>
<t>
The profile URI is opaque and SHOULD NOT automatically be dereferenced.
If the implementation does not understand the semantics of the provided profile,
When using the media type application/schema-instance+json, the "schema"
parameter MUST be supplied.
</t>
<t>
The schema URI is opaque and SHOULD NOT automatically be dereferenced.
If the implementation does not understand the semantics of the provided schema,
the implementation can instead follow the "describedby" links, if any, which may
provide information on how to handle the profile.
Since "profile" doesn't necessarily point to a network location, the
provide information on how to handle the schema.
Since "schema" doesn't necessarily point to a network location, the
"describedby" relation is used for linking to a downloadable schema.
However, for simplicity, schema authors should make these URIs point to the same
resource when possible.
Expand All @@ -724,34 +725,39 @@ Link: <http://example.com/my-hyper-schema#>; rel="describedby"
<artwork>
<![CDATA[
Content-Type: application/json;
profile="http://example.com/my-hyper-schema#"
schema="http://example.com/my-hyper-schema#"
]]>
</artwork>
</figure>

<t>
Multiple profiles are whitespace separated:
Multiple schemas are whitespace separated:
</t>

<figure>
<artwork>
<![CDATA[
Content-Type: application/json;
profile="http://example.com/alice http://example.com/bob"
schema="http://example.com/alice http://example.com/bob"
]]>
</artwork>
</figure>

<t>
HTTP can also send the "profile" in a Link, though this may impact media-type
<cref>
This paragraph assumes that we can register a "schema" link relation.
Should we instead specify something like "tag:json-schema.org,2017:schema"
for now?
Copy link
Member

Choose a reason for hiding this comment

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

Or a URL like http://json-schema.org/<something here> ? Like JSON-LD does with http://www.w3.org/ns/json-ld#context.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I really like using non-dereferenceable URI schemes like tag: when there is nothing to dereference. While it is certainly valid to use http:// or https:// for such a purpose, it is counter-intuitive and leads to a.) people blindly dumping it in a browser and being annoyed that it doesn't work and b.) awkward paragraphs in specifications about how even though the URI looks dereferenceable, implementations MUST NOT dereference it.

Just make it non-dereferenceable. It solves all the UX problems of apparently-dereferenceable-URIs-that-are-not-actually-dereferenceable.

</cref>
HTTP can also send the "schema" in a Link, though this may impact media-type
semantics and Content-Type negotiation if this replaces the media-type parameter
entirely:
</t>

<figure>
<artwork>
<![CDATA[
Link: </alice>;rel="profile", </bob>;rel="profile"
Link: </alice>;rel="schema", </bob>;rel="schema"
]]>
</artwork>
</figure>
Expand Down Expand Up @@ -915,7 +921,6 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0

<references title="Informative References">
&RFC5988;
&RFC6906;
&RFC7049;
&RFC7231;
&fragid-best-practices;
Expand Down