Skip to content

Commit 17dc51b

Browse files
lanthalerlanthaler
committed
Remove property generators from syntax spec
This addresses #142.
1 parent 71a41f4 commit 17dc51b

File tree

1 file changed

+104
-184
lines changed

1 file changed

+104
-184
lines changed

‎spec/latest/json-ld-syntax/index.html

Lines changed: 104 additions & 184 deletions
Original file line numberDiff line numberDiff line change
@@ -1644,92 +1644,14 @@ <h2>String Internationalization</h2>
16441644
</section>
16451645

16461646
<section>
1647-
<h2>Property Generators</h2>
1648-
1649-
<p class="issue atrisk">This feature is at risk as it introduces a lot of
1650-
algorithmic complexity for an unclear benefit.</p>
1651-
1652-
<p>At times, an author may find that they need to express the same value for
1653-
multiple properties. The simplest approach to accomplish this goal would be
1654-
to do the following:</p>
1655-
1656-
<pre class="example" data-transform="updateExample"
1657-
title="Verbose expression of multiple properties with the same value">
1658-
<!--
1659-
{
1660-
"@context":
1661-
{
1662-
****"title1": "http://purl.org/dc/terms/title"****,
1663-
****"title2": "http://schema.org/name"****,
1664-
****"title3": "http://www.w3.org/2000/01/rdf-schema#label"****
1665-
},
1666-
"@id": "http://example.com/book",
1667-
****"title1": "The Count of Monte Cristo"****,
1668-
****"title2": "The Count of Monte Cristo"****,
1669-
****"title3": "The Count of Monte Cristo"****
1670-
}
1671-
-->
1672-
</pre>
1673-
1674-
<p>Unfortunately, the approach above produces redundant data and would become a
1675-
publishing burden for large data sets. In these situations, the author may use
1676-
a <tdef>property generator</tdef> to express a <tref>term</tref> that maps to
1677-
multiple <tref title="property">properties</tref> in the <tref>JSON-LD graph</tref>.
1678-
This method can be accomplished by using the following markup pattern:</p>
1679-
1680-
<pre class="example" data-transform="updateExample"
1681-
title="Generating multiple properties using a single term">
1682-
<!--
1683-
{
1684-
"@context":
1685-
{
1686-
****"title": { "@id": [ "http://purl.org/dc/terms/title",
1687-
"http://schema.org/name",
1688-
"http://www.w3.org/2000/01/rdf-schema#label" ] }****
1689-
},
1690-
"@id": "http://example.com/book",
1691-
****"title": "The Count of Monte Cristo"****
1692-
}
1693-
-->
1694-
</pre>
1695-
1696-
<p>While the term above is only used once outside of the <code>@context</code>,
1697-
the document above will be interpreted like so:</p>
1698-
1699-
<table class="example">
1700-
<thead>
1701-
<th>Subject</th>
1702-
<th>Property</th>
1703-
<th>Value</th>
1704-
</thead>
1705-
<tbody>
1706-
<tr>
1707-
<td>http://example.com/book</td>
1708-
<td>http://purl.org/dc/terms/title</td>
1709-
<td>The Count of Monte Cristo</td>
1710-
</tr>
1711-
<tr>
1712-
<td>http://example.com/book</td>
1713-
<td>http://schema.org/name</td>
1714-
<td>The Count of Monte Cristo</td>
1715-
</tr>
1716-
<tr>
1717-
<td>http://example.com/book</td>
1718-
<td>http://www.w3.org/2000/01/rdf-schema#label</td>
1719-
<td>The Count of Monte Cristo</td>
1720-
</tr>
1721-
</tbody>
1722-
</table>
1723-
</section>
1724-
1725-
<section>
1726-
<h2>IRI Expansion Within a Context</h2>
1647+
<h2>IRI Expansion within a Context</h2>
17271648
<p>In general, normal IRI expansion rules apply
17281649
anywhere an IRI is expected (see <a href="#iris"></a>). Within
17291650
a <tref>context</tref> definition, this can mean that terms defined
17301651
within the context may also be used within that context as long as
17311652
there are no circular dependencies. For example, it is common to use
17321653
the <code>xsd</code> namespace when defining <tref>typed value</tref>s:</p>
1654+
17331655
<pre class="example" data-transform="updateExample"
17341656
title="IRI expansion within a context">
17351657
<!--
@@ -1753,6 +1675,7 @@ <h2>IRI Expansion Within a Context</h2>
17531675
}
17541676
-->
17551677
</pre>
1678+
17561679
<p>In this example, the <code>xsd</code> <tref>term</tref> is defined
17571680
and used as a <tref>prefix</tref> for the <code>@type</code> coercion
17581681
of the <code>age</code> property.</p>
@@ -2953,10 +2876,8 @@ <h2>Context Definition</h2>
29532876

29542877
<p>If the <tref>expanded term definition</tref> contains the <code>@id</code>
29552878
<tref>keyword</tref>, its value MUST be <tref>null</tref>, an <tref>absolute IRI</tref>,
2956-
a <tref>blank node identifier</tref>, a <tref>compact IRI</tref>, a <tref>term</tref>
2957-
defined in the defining <tref>context definition</tref> or the <tref>active context</tref>,
2958-
or an <tref>array</tref> composed of any of the previous allowed values except
2959-
<tref>null</tref>.</p>
2879+
a <tref>blank node identifier</tref>, a <tref>compact IRI</tref>, or a <tref>term</tref>
2880+
defined in the defining <tref>context definition</tref> or the <tref>active context</tref>.</p>
29602881

29612882
<p>If the <tref>expanded term definition</tref> contains the <code>@type</code>
29622883
<tref>keyword</tref>, its value MUST be an <tref>absolute IRI</tref>, a
@@ -3327,111 +3248,110 @@ <h3>Microdata</h3>
33273248
</section>
33283249
</section>
33293250

3330-
<section class="appendix informative">
3331-
<h1>IANA Considerations</h1>
3332-
3333-
<p>This section is included merely for standards community review and will be
3334-
submitted to the Internet Engineering Steering Group if this specification
3335-
becomes a W3C Recommendation.</p>
3336-
3337-
<h3>application/ld+json</h3>
3338-
<dl>
3339-
<dt>Type name:</dt>
3340-
<dd>application</dd>
3341-
<dt>Subtype name:</dt>
3342-
<dd>ld+json</dd>
3343-
<dt>Required parameters:</dt>
3344-
<dd>None</dd>
3345-
<dt>Optional parameters:</dt>
3346-
<dd>
3347-
<dl>
3348-
<dt><code>profile</code></dt>
3349-
<dd>
3350-
<p>A whitespace-separated list of IRIs identifying specific constraints
3351-
or conventions that apply to a JSON-LD document. A profile MUST NOT change
3352-
the semantics of the resource representation when processed without profile
3353-
knowledge, so that clients both with and without knowledge of a profiled
3354-
resource can safely use the same representation. The <code>profile</code>
3355-
parameter MAY also be used by clients to express their preferences in the
3356-
content negotiation process. It is RECOMMENDED that profile IRIs are
3357-
dereferenceable and provide useful documentation at that IRI. For more
3358-
information and background please refer to [[PROFILE-LINK]].</p>
3359-
<p>This specification defines four values for the <code>profile</code> parameter.
3360-
To request or specify Expanded JSON-LD document form, the IRI
3361-
<code>http://www.w3.org/ns/json-ld#expanded</code> SHOULD be used.
3362-
To request or specify Expanded, Flattened JSON-LD document form, the IRI
3363-
<code>http://www.w3.org/ns/json-ld#expanded-flattened</code> SHOULD
3364-
be used. To request or specify Compacted JSON-LD document form, the IRI
3365-
<code>http://www.w3.org/ns/json-ld#compacted</code> SHOULD be used.
3366-
To request or specify Compacted, Flattened JSON-LD document form, the IRI
3367-
<code>http://www.w3.org/ns/json-ld#compacted-flattened</code> SHOULD be used.
3368-
Please note that, according [[HTTP11]], the value of the <code>profile</code>
3369-
parameter has to be enclosed in quotes (<code>"</code>) because it contains
3370-
special characters and, in some cases, whitespace.</p>
3371-
</dd>
3372-
</dl>
3373-
</dd>
3374-
<dt>Encoding considerations:</dt>
3375-
<dd>See RFC&nbsp;6839, section 3.1.</dd>
3376-
<dt>Security considerations:</dt>
3377-
<dd>Since JSON-LD is intended to be a pure data exchange format for
3378-
directed graphs, the serialization SHOULD NOT be passed through a
3379-
code execution mechanism such as JavaScript's <code>eval()</code>
3380-
function to be parsed.<br/>
3381-
JSON-LD contexts that are loaded from the Web over non-secure connections,
3382-
such as HTTP, run the risk of modifying the JSON-LD
3383-
<tref>active context</tref> in a way that could compromise security. It
3384-
is advised that any application that depends on a remote context for mission
3385-
critical purposes vet and cache the remote context before allowing the
3386-
system to use it.<br />
3387-
JSON-LD allows the substitution of long IRIs with short terms and the
3388-
compression of multiple properties into a single property generator. Therefore,
3389-
JSON-LD documents may expand enormously when processed and, in the worst case,
3390-
the resulting data might consume all of the recipient's resources. Applications
3391-
should treat any data with due skepticism.
3392-
</dd>
3393-
<dt>Interoperability considerations:</dt>
3394-
<dd>Not Applicable</dd>
3395-
<dt>Published specification:</dt>
3396-
<dd>The <a href="http://json-ld.org/spec/latest/">JSON-LD</a> specification.</dd>
3397-
<dt>Applications that use this media type:</dt>
3398-
<dd>Any programming environment that requires the exchange of
3399-
directed graphs. Implementations of JSON-LD have been created for
3400-
JavaScript, Python, Ruby, PHP, and C++.
3401-
</dd>
3402-
<dt>Additional information:</dt>
3403-
<dd>
3404-
<dl>
3405-
<dt>Magic number(s):</dt>
3406-
<dd>Not Applicable</dd>
3407-
<dt>File extension(s):</dt>
3408-
<dd>.jsonld</dd>
3409-
<dt>Macintosh file type code(s):</dt>
3410-
<dd>TEXT</dd>
3411-
</dl>
3412-
</dd>
3413-
<dt>Person &amp; email address to contact for further information:</dt>
3414-
<dd>Manu Sporny &lt;[email protected]&gt;</dd>
3415-
<dt>Intended usage:</dt>
3416-
<dd>Common</dd>
3417-
<dt>Restrictions on usage:</dt>
3418-
<dd>None</dd>
3419-
<dt>Author(s):</dt>
3420-
<dd>Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, Niklas Lindström</dd>
3421-
<dt>Change controller:</dt>
3422-
<dd>W3C</dd>
3423-
</dl>
3251+
<section class="appendix normative">
3252+
<h2>IANA Considerations</h2>
3253+
<em>This section is normative</em>
34243254

3425-
<p>Fragment identifiers used with <a href="#application-ld-json">application/ld+json</a>
3426-
resources MAY identify a node in a <tref>JSON-LD graph</tref> expressed in
3427-
the resource. This idiom, which is also used in RDF [[RDF-CONCEPTS]], gives a
3428-
simple way to "mint" new, document-local IRIs to label nodes and therefore contributes
3429-
considerably to the expressive power of JSON-LD.</p>
3255+
<p>This section is included for community review and will be submitted to the
3256+
Internet Engineering Steering Group (IESG) as part of the Last Call announcement
3257+
for this specification.</p>
3258+
3259+
<h3>application/ld+json</h3>
3260+
<dl>
3261+
<dt>Type name:</dt>
3262+
<dd>application</dd>
3263+
<dt>Subtype name:</dt>
3264+
<dd>ld+json</dd>
3265+
<dt>Required parameters:</dt>
3266+
<dd>None</dd>
3267+
<dt>Optional parameters:</dt>
3268+
<dd>
3269+
<dl>
3270+
<dt><code>profile</code></dt>
3271+
<dd>
3272+
<p>A whitespace-separated list of IRIs identifying specific constraints
3273+
or conventions that apply to a JSON-LD document. A profile MUST NOT change
3274+
the semantics of the resource representation when processed without profile
3275+
knowledge, so that clients both with and without knowledge of a profiled
3276+
resource can safely use the same representation. The <code>profile</code>
3277+
parameter MAY also be used by clients to express their preferences in the
3278+
content negotiation process. It is RECOMMENDED that profile IRIs are
3279+
dereferenceable and provide useful documentation at that IRI. For more
3280+
information and background please refer to [[PROFILE-LINK]].</p>
3281+
<p>This specification defines four values for the <code>profile</code> parameter.
3282+
To request or specify Expanded JSON-LD document form, the IRI
3283+
<code>http://www.w3.org/ns/json-ld#expanded</code> SHOULD be used.
3284+
To request or specify Expanded, Flattened JSON-LD document form, the IRI
3285+
<code>http://www.w3.org/ns/json-ld#expanded-flattened</code> SHOULD
3286+
be used. To request or specify Compacted JSON-LD document form, the IRI
3287+
<code>http://www.w3.org/ns/json-ld#compacted</code> SHOULD be used.
3288+
To request or specify Compacted, Flattened JSON-LD document form, the IRI
3289+
<code>http://www.w3.org/ns/json-ld#compacted-flattened</code> SHOULD be used.
3290+
Please note that, according [[HTTP11]], the value of the <code>profile</code>
3291+
parameter has to be enclosed in quotes (<code>"</code>) because it contains
3292+
special characters and, in some cases, whitespace.</p>
3293+
</dd>
3294+
</dl>
3295+
</dd>
3296+
<dt>Encoding considerations:</dt>
3297+
<dd>See RFC&nbsp;6839, section 3.1.</dd>
3298+
<dt>Security considerations:</dt>
3299+
<dd>Since JSON-LD is intended to be a pure data exchange format for
3300+
directed graphs, the serialization SHOULD NOT be passed through a
3301+
code execution mechanism such as JavaScript's <code>eval()</code>
3302+
function to be parsed.<br/>
3303+
JSON-LD contexts that are loaded from the Web over non-secure connections,
3304+
such as HTTP, run the risk of modifying the JSON-LD
3305+
<tref>active context</tref> in a way that could compromise security. It
3306+
is advised that any application that depends on a remote context for mission
3307+
critical purposes vet and cache the remote context before allowing the
3308+
system to use it.<br />
3309+
Given that JSON-LD allows the substitution of long IRIs with short terms,
3310+
JSON-LD documents may expand considerably when processed and, in the worst case,
3311+
the resulting data might consume all of the recipient's resources. Applications
3312+
should treat any data with due skepticism.
3313+
</dd>
3314+
<dt>Interoperability considerations:</dt>
3315+
<dd>Not Applicable</dd>
3316+
<dt>Published specification:</dt>
3317+
<dd>The <a href="http://json-ld.org/spec/latest/">JSON-LD</a> specification.</dd>
3318+
<dt>Applications that use this media type:</dt>
3319+
<dd>Any programming environment that requires the exchange of
3320+
directed graphs. Implementations of JSON-LD have been created for
3321+
JavaScript, Python, Ruby, PHP, and C++.
3322+
</dd>
3323+
<dt>Additional information:</dt>
3324+
<dd>
3325+
<dl>
3326+
<dt>Magic number(s):</dt>
3327+
<dd>Not Applicable</dd>
3328+
<dt>File extension(s):</dt>
3329+
<dd>.jsonld</dd>
3330+
<dt>Macintosh file type code(s):</dt>
3331+
<dd>TEXT</dd>
3332+
</dl>
3333+
</dd>
3334+
<dt>Person &amp; email address to contact for further information:</dt>
3335+
<dd>Manu Sporny &lt;[email protected]&gt;</dd>
3336+
<dt>Intended usage:</dt>
3337+
<dd>Common</dd>
3338+
<dt>Restrictions on usage:</dt>
3339+
<dd>None</dd>
3340+
<dt>Author(s):</dt>
3341+
<dd>Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, Niklas Lindström</dd>
3342+
<dt>Change controller:</dt>
3343+
<dd>W3C</dd>
3344+
</dl>
34303345

3346+
<p>Fragment identifiers used with <a href="#application-ld-json">application/ld+json</a>
3347+
resources MAY identify a node in a <tref>JSON-LD graph</tref> expressed in
3348+
the resource. This idiom, which is also used in RDF [[RDF-CONCEPTS]], gives a
3349+
simple way to "mint" new, document-local IRIs to label nodes and therefore contributes
3350+
considerably to the expressive power of JSON-LD.</p>
34313351
</section>
34323352

34333353
<section class="appendix informative">
3434-
<h1>Acknowledgements</h1>
3354+
<h2>Acknowledgements</h2>
34353355

34363356
<p>The authors would like to extend a deep appreciation and the most sincere
34373357
thanks to Mark Birbeck, who contributed foundational concepts

0 commit comments

Comments
 (0)