Skip to content

Commit

Permalink
Update framing algorithm to use more normative language and be less p…
Browse files Browse the repository at this point in the history 
…rescriptive as to how specific algorithm steps are implemented. Uses new features implemented in many implementations. (Some detailed parts may be added back as informative sections, if that proves necessary).
  • Loading branch information
@gkellogg
gkellogg committed Sep 15, 2016
1 parent 23baa85 commit 5a3e506
Show file tree
Hide file tree
Showing 2 changed files with 217 additions and 283 deletions.
45 changes: 23 additions & 22 deletions spec/latest/common/terms.html
View file
Expand Up @@ -6,21 +6,22 @@ <h1>General Terminology</h1>

<dl class="termlist">
<dt><dfn>array</dfn></dt><dd>
An array structure is represented as square brackets surrounding zero
In the JSON serialization, an array structure is represented as square brackets surrounding zero
or more values. Values are separated by commas.
In JSON, an array is an <em>ordered</em> sequence of zero or more values.
In the <em>abstract representation</em>, an array is an <em>ordered</em> collection of zero or more values.
While JSON-LD uses the same array representation as JSON,
the collection is <em>unordered</em> by default. While order is
preserved in regular JSON arrays, it is not in regular JSON-LD arrays
unless specifically defined (see
<cite><a href="http://www.w3.org/TR/json-ld/#sets-and-lists" class="externalDFN">Sets and Lists</a></cite> in
the JSON-LD specification [[JSON-LD]]).</dd>
<dt><dfn data-lt="JSON objects">JSON object</dfn></dt><dd>
An object structure is represented as a pair of curly brackets surrounding zero or
In the JSON serialization, an object structure is represented as a pair of curly brackets surrounding zero or
more key-value pairs. A key is a <a>string</a>. A single colon comes after
each key, separating the key from the value. A single comma separates a value
from a following key. In contrast to JSON,
in JSON-LD the keys in an object MUST be unique.</dd>
from a following key. In JSON-LD the keys in an object MUST be unique.
In the <em>abstract representation</em> a <a>JSON object</a> is equivalent to a
<a href="http://www.w3.org/TR/WebIDL/#dfn-dictionary" class="externalDFN"><dfn>dictionary</dfn></a> (see [[WebIDL-2]]).</dd>
<dt><dfn>null</dfn></dt><dd>
The use of the <a>null</a> value within JSON-LD is used to
ignore or reset values. A key-value pair in the <code>@context</code> where
Expand All @@ -32,21 +33,26 @@ <h1>General Terminology</h1>
<a>null</a> in expanded form, then the entire <a>JSON
object</a> is ignored.</dd>
<dt><dfn>number</dfn></dt><dd>
A number is similar to that used in most programming languages, except
In the JSON serialization, a number is similar to that used in most programming languages, except
that the octal and hexadecimal formats are not used and that leading
zeros are not allowed.</dd>
zeros are not allowed.
In the <em>abstract representation</em>, a <a>number</a> is equivalent to either
a <a href="http://www.w3.org/TR/WebIDL/#dfn-long" class="externalDFN">long</a>
or <a href="http://www.w3.org/TR/WebIDL/#dfn-double" class="externalDFN">double</a>, depending
on if the number has a non-zero fractional part (see [[WebIDL-2]]).</dd>
<dt><dfn data-lt="strings">string</dfn></dt><dd>
A string is a sequence of zero or more Unicode (UTF-8) characters,
wrapped in double quotes, using backslash escapes (if necessary). A
character is represented as a single character string.</dd>
<dt><dfn>true</dfn> and <dfn>false</dfn></dt><dd>
Values that are used to express one of two possible boolean states.</dd>
Values that are used to express one of two possible
<a href="http://www.w3.org/TR/WebIDL/#idl-boolean" class="externalDFN">boolean</a> states.</dd>
</dl>

<p>Furthermore, the following terminology is used throughout this document:</p>

<dl class="termlist">
<dt><dfn>absolute IRI</dfn></dt><dd>
<dt><dfn data-lt="absolute IRIs">absolute IRI</dfn></dt><dd>
An absolute <a>IRI</a> is defined in [[!RFC3987]] containing a <em>scheme</em> along with a <em>path</em> and
optional <em>query</em> and fragment segments.</dd>
<dt><dfn data-lt="blank nodes">blank node</dfn></dt><dd>
Expand All @@ -56,7 +62,7 @@ <h1>General Terminology</h1>
identifier because it is either ephemeral in nature or does not contain information that needs to be
linked to from outside of the linked data graph. A blank node is assigned an identifier starting with
the prefix <code>_:</code>.</dd>
<dt><dfn>blank node identifier</dfn></dt><dd>
<dt><dfn data-lt="blank node identifiers">blank node identifier</dfn></dt><dd>
A blank node identifier is a string that can be used as an identifier for a
<a>blank node</a> within the scope of a JSON-LD document. Blank node identifiers
begin with <code>_:</code>.</dd>
Expand All @@ -72,7 +78,7 @@ <h1>General Terminology</h1>
an <a>IRI</a> or a <a>blank node identifier</a>. Within the JSON-LD syntax
these edge labels are called <a>properties</a>. Whenever possible, an
<a>edge</a> should be labeled with an <a>IRI</a>.</dd>
<dt><dfn>Frame</dfn></dt><dd>
<dt><dfn data-lt="frames">Frame</dfn></dt><dd>
A <a>JSON-LD document</a>, which describes the form for outputting
<a>JSON-LD input</a> using matching and embedding rules.</dd>
<dt><dfn>graph name</dfn></dt><dd>
Expand Down Expand Up @@ -108,7 +114,7 @@ <h1>General Terminology</h1>
A <a>linked data graph</a> is a generalized representation of a
<cite><a href="http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-graph">RDF graph</a></cite>
as defined in [[!RDF-CONCEPTS]].</dd>
<dt><dfn>literal</dfn></dt><dd>
<dt><dfn data-lt="literals">literal</dfn></dt><dd>
An <a>object</a> expressed as a value such as a string, number or in expanded form.</dd>
<dt><dfn data-lt="named graphs">named graph</dfn></dt><dd>
A <a>linked data graph</a> that is identified by an <a>IRI</a> or <a>blank node</a>
Expand All @@ -117,7 +123,7 @@ <h1>General Terminology</h1>
Every <a>node</a> is an <a>IRI</a>, a <a>blank node</a>,
a <a>JSON-LD value</a>, or a <a>list</a>.
A piece of information that is represented in a <a>linked data graph</a>.</dd>
<dt><dfn>node definition</dfn></dt><dd>
<dt><dfn data-lt="node definitions">node definition</dfn></dt><dd>
A <a>JSON object</a> used to represent a <a>node</a> and
one or more properties of that node. A <a>JSON object</a> is a
node definition if it does not contain the keys <code>@value</code>,
Expand All @@ -126,14 +132,14 @@ <h1>General Terminology</h1>
<dt><dfn>node reference</dfn></dt><dd>
A <a>JSON object</a> used to reference a node having only the
<code>@id</code> key.</dd>
<dt><dfn>object</dfn></dt><dd>
<dt><dfn data-lt="objects">object</dfn></dt><dd>
A <a>node</a> in a <a>linked data graph</a> with at least one incoming edge.</dd>
<dt><dfn data-lt="properties">property</dfn></dt><dd>
The <a>IRI</a> label of an edge in a <a>linked data graph</a>.</dd>
<dt><dfn>quad</dfn></dt><dd>
A piece of information that contains four items; a <a>subject</a>, a <a>property</a>,
an <a>object</a>, and a <a>graph name</a>.</dd>
<dt><dfn>relative IRI</dfn></dt><dd>
<dt><dfn data-lt="relative IRIs">relative IRI</dfn></dt><dd>
A relative IRI is an <a>IRI</a> that is relative to some other <a>absolute IRI</a>.</dd>
<dt><dfn>subject</dfn></dt><dd>
A <a>node</a> in a <a>linked data graph</a> with at least one outgoing edge, related to an <a>object</a> node through a <a>property</a>.</dd>
Expand Down Expand Up @@ -176,7 +182,7 @@ <h1>Algorithm Terms</h1>
A flag specifying that for <a>properties</a> to be included in the output, they
must be explicitly declared in the <a>framing context</a>.</dd>
<dt><dfn>framing context</dfn></dt><dd>
A context containing a <a>map of embeds</a>, the
A context containing the
<a>object embed flag</a>, the
<a>require all flag</a>, the
<a>explicit inclusion flag</a> and the
Expand All @@ -193,11 +199,6 @@ <h1>Algorithm Terms</h1>
<dt><dfn>local context</dfn></dt><dd>
A context that is specified within a <a>JSON object</a>,
specified via the <code>@context</code> <a>keyword</a>.</dd>
<dt><dfn>map of embeds</dfn></dt><dd>
A map that tracks if a subject is to be embedded in the output of the
<a href="#framing-algorithm">Framing Algorithm</a>; it maps a subject
<code>@id</code> to a parent <a>JSON object</a> and property
or parent array.</dd>
<dt><dfn>map of flattened subjects</dfn></dt><dd>
A map of subjects that is the result of the
<a href="https://www.w3.org/TR/json-ld-api/#node-map-generation">Node Map Generation algorithm</a>.</dd>
Expand All @@ -214,7 +215,7 @@ <h1>Algorithm Terms</h1>
</ul>
</dd>
<dt><dfn>object embed flag</dfn></dt><dd>
A flag specifying that objects should be directly embedded in the output,
A flag specifying that <a>node definitions</a> should be directly embedded in the output,
instead of being referred to by their <a>IRI</a>.</dd>
<dt><dfn>omit default flag</dfn></dt><dd>
A flag specifying that properties that are missing from the
Expand Down

0 comments on commit 5a3e506

Please sign in to comment.