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

Show file tree
Hide file tree
Changes from all 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
2 changes: 1 addition & 1 deletion common/terms.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -335,5 +335,5 @@
A <a>value object</a> is a <a>dictionary</a> that has an <code>@value</code> <a>member</a>.</dd>
<dt><dfn>vocabulary mapping</dfn></dt><dd>
The vocabulary mapping is set in the <a>context</a> using the <code>@vocab</code> key
whose value MUST be an <a>absolute IRI</a> or <code>null</code>.</dd>
whose value MUST be an <a>IRI</a> or <code>null</code>.</dd>
</dl>
88 changes: 73 additions & 15 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,24 @@ <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 class="note">Other specifications may publish additional profile parameter
URIs with their own defined sematics.</p>
<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, which is required when multiple profile URIs are combined.</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,16 +10496,16 @@ <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>
function to be parsed. An (invalid) document may contain code that,
when executed, could lead to unexpected side effects compromising
the security of a system.</p>
<p>When processing JSON-LD documents, links to remote contexts are
<p>When processing JSON-LD documents, links to remote contexts and frames are
typically followed automatically, resulting in the transfer of files
without the explicit request of the user for each one. If remote
contexts are served by third parties, it may allow them to gather
Expand Down Expand Up @@ -10537,7 +10545,7 @@ <h3>application/ld+json</h3>
</dl>
</dd>
<dt>Person &amp; email address to contact for further information:</dt>
<dd>Manu Sporny &lt;[email protected]&gt;</dd>
<dd>Ivan Herman &lt;[email protected]&gt;</dd>
<dt>Intended usage:</dt>
<dd>Common</dd>
<dt>Restrictions on usage:</dt>
Expand All @@ -10552,6 +10560,56 @@ <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#flattened http://www.w3.org/ns/json-ld#compacted"****
-->
</pre>
<p>Requests the server to return the requested resource as JSON-LD
in both <a href="#compacted-document-form">compacted document form</a>
and <a href="#flattened-document-form">flattened document form</a>.
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