Skip to content

Define additional profile URIs #111

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 7 commits into from
Jan 12, 2019
Merged

Define additional profile URIs #111

Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
33c503a
Define additional profile URIs, and the interpretation of an unspecif…
gkellogg Dec 21, 2018
f6ea3eb
Fix duplicate "when a" in section 3.1.
gkellogg Dec 27, 2018
2646290
Add examples of using the `profile` Mime parameter.
gkellogg Jan 3, 2019
cd91bb9
Update RFC2048#section-2.2.3 to RFC4288#section4.3.
gkellogg Jan 3, 2019
4ffa364
Separates the URLs for context and link from the `profile` parameter …
gkellogg Jan 4, 2019
9fd5387
Update to remove normative discussion of the Link header in requests …
gkellogg Jan 11, 2019
c212913
Update common terms.
gkellogg Jan 12, 2019
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
106 changes: 93 additions & 13 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -770,7 +770,7 @@ <h2>The Context</h2>
either be a simple string, mapping the <a>term</a> to an <a>IRI</a>,
or a <a>dictionary</a>.</p>

<p>When a when a <a>member</a> with a <a>term</a> key has a <a>dictionary</a> value, the <a>dictionary</a> is called
<p>When a <a>member</a> with a <a>term</a> key has a <a>dictionary</a> value, the <a>dictionary</a> is called
an <a>expanded term definition</a>. The example above specifies that
the values of <code>image</code> and <code>homepage</code>, if they are
strings, are to be interpreted as
Expand Down Expand Up @@ -10469,16 +10469,30 @@ <h3>application/ld+json</h3>
It is RECOMMENDED that profile URIs are dereferenceable and provide
useful documentation at that URI. For more information and background
please refer to [[RFC6906]].</p>
<p>This specification defines three values for the <code>profile</code> parameter.
To request or specify <a href="#expanded-document-form">expanded JSON-LD document form</a>,
the URI <code>http://www.w3.org/ns/json-ld#expanded</code> SHOULD be used.
To request or specify <a href="#compacted-document-form">compacted JSON-LD document form</a>,
the URI <code>http://www.w3.org/ns/json-ld#compacted</code> SHOULD be used.
To request or specify <a href="#flattened-document-form">flattened JSON-LD document form</a>,
the URI <code>http://www.w3.org/ns/json-ld#flattened</code> SHOULD be used.
Please note that, according [[HTTP11]], the value of the <code>profile</code>
parameter has to be enclosed in quotes (<code>"</code>) because it contains
special characters and, if multiple profiles are combined, whitespace.</p>
<p>This specification defines four values for the <code>profile</code> parameter.</p>
<dl>
<dt><code>http://www.w3.org/ns/json-ld#expanded</code></dt>
<dd>To request or specify <a href="#expanded-document-form">expanded JSON-LD document form</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#compacted</code></dt>
<dd>To request or specify <a href="#compacted-document-form">compacted JSON-LD document form</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#flattened</code></dt>
<dd>To request or specify <a href="#flattened-document-form">flattened JSON-LD document form</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#framed</code></dt>
<dd>To request or specify <a href="#framed-document-form">framed JSON-LD document form</a>.</dd>
</dl>
<p>
When used as a <a data-cite="RFC4288#section-4.3">media type paramter</a> [[RFC4288]]
in an <a data-cite="rfc7231#section-5.3.2">HTTP Accept header</a> [[RFC7231]],
Copy link
Member

Choose a reason for hiding this comment

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

paramter -> parameter

the value of the <code>profile</code> parameter MUST be enclosed in quotes (<code>"</code>) if it contains
special characters such as whitespace, when multiple profiles are combined.</p>
<p>In addition to the <code>profile</code> values described above,
the <code>profile</code> parameter MAY include one additional URL, which is interpreted as
the location of either a <a>context</a> or <a>frame</a>, depending on the other profile
parameters included. When used without an defined profile URI, such a URL
is interpreted as the location of a <a>context</a>.</p>
<p>JSON-LD processors MAY place restrictions on supported profiles,
MAY provide defaults for <a>context</a> and <a>frame</a> URLs,
and MAY restrict client-provided URLs for <a>contexts</a> and <a>frames</a>.</p>
<p>When processing the "profile" media type parameter, it is important to
Copy link
Member

Choose a reason for hiding this comment

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

" ... MAY provide defaults for context and frame URLs, and MAY restrict client-provided URLs for contexts and frames . "

That seems to be a possibly major new feature. Was this discussed and adopted in an issue (if yes, and I just do not remember, my apologies)?

I guess this is a feature that schema.org processors may declare: they use schema.org as a default profile. But that would mean that users of schema.org may then decide, en masse, not to declare their own context by any means, which means that their data become unusable for others than schema.org. This may have dire consequences...

Copy link
Member

Choose a reason for hiding this comment

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

@iherman this is why the "limit profile parameter use to URI’s" of our resolution text is important, and why it suggests creating a new issue for that URL dereferencing approach--which Gregg's has fleshed out a bit in the API PR w3c/json-ld-api#56 (uses Link headers instead of the profile= media type parameter).

note that its value contains one or more URIs and not IRIs. In some cases
it might therefore be necessary to convert between IRIs and URIs as specified in
Expand All @@ -10488,9 +10502,9 @@ <h3>application/ld+json</h3>
</dl>
</dd>
<dt>Encoding considerations:</dt>
<dd>See <a data-cite="RFC6839#section-3.1">RFC&nbsp;6839, section 3.1</a>.</dd>
<dd>See <a data-cite="RFC8259#section-11">RFC&nbsp;8259, section 11</a>.</dd>
<dt>Security considerations:</dt>
<dd>See [[RFC8259]]
<dd>See <a data-cite="RFC8259#section-12">RFC&nbsp;8259, section 12</a> [[RFC8259]]
<p>Since JSON-LD is intended to be a pure data exchange format for
directed graphs, the serialization SHOULD NOT be passed through a
code execution mechanism such as JavaScript's <code>eval()</code>
Expand Down Expand Up @@ -10552,6 +10566,72 @@ <h3>application/ld+json</h3>
are treated as in RDF syntaxes, as per
<a data-cite="RDF11-CONCEPTS#section-fragID">RDF 1.1 Concepts and Abstract Syntax</a>
[[RDF11-CONCEPTS]].</p>

<section id="iana-examples" class="informative">
<h3>Examples</h3>
<p>The following examples illustrate different ways in which the profile parameter may be used
to describe different acceptable responses.</p>

<pre class="example" data-transform="updateExample"
data-content-type="http"
data-ignore
title="HTTP Request with profile requesting an expanded document">
<!--
GET /ordinary-json-document.json HTTP/1.1
Host: example.com
Accept: application/ld+json;****profile=http://www.w3.org/ns/json-ld#expanded****
-->
</pre>
<p>Requests the server to return the requested resource as JSON-LD
in <a href="#expanded-document-form">expanded document form</a>.</p>

<pre class="example" data-transform="updateExample"
data-content-type="http"
data-ignore
title="HTTP Request with profile requesting a compacted document">
<!--
GET /ordinary-json-document.json HTTP/1.1
Host: example.com
Accept: application/ld+json;****profile=http://www.w3.org/ns/json-ld#compacted****
-->
</pre>
<p>Requests the server to return the requested resource as JSON-LD
in <a href="#compacted-document-form">compacted document form</a>.
As no explicit context resource is specified, the server compacts
using an application-specific default context.</p>

<pre class="example" data-transform="updateExample"
data-content-type="http"
data-ignore
title="HTTP Request with profile requesting a compacted document with a reference to a compaction context">
<!--
GET /ordinary-json-document.json HTTP/1.1
Host: example.com
Accept: application/ld+json;****profile="http://www.w3.org/ns/json-ld#compacted http://example.com/context.jsonld"****
-->
</pre>
<p>Requests the server to return the requested resource as JSON-LD
in <a href="#compacted-document-form">compacted document form</a>
and specifies the location of a context to use for compaction.
Note that as whitespace is used to separate the two URIs, they
are enclosed in double quotes (<code>"</code>).</p>

<pre class="example" data-transform="updateExample"
data-content-type="http"
data-ignore
title="HTTP Request with profile requesting a framed document with a reference to the framing document">
<!--
GET /ordinary-json-document.json HTTP/1.1
Host: example.com
Accept: application/ld+json;****profile="http://www.w3.org/ns/json-ld#framed http://example.com/frame.jsonld"****
-->
</pre>
<p>Requests the server to return the requested resource as JSON-LD
in <a href="#framed-document-form">framed document form</a>
and specifies the location of a frame to use.
Note that as whitespace is used to separate the two URIs, they
are enclosed in double quotes (<code>"</code>).</p>
</section>
</section>

<section id="security" class="appendix">
Expand Down