Skip to content

Commit 562faa2

Browse files
gkellogggkellogg
committed
Added advanced concept sections for Expanded, Compacted, Framed, and Normalized representations based on introductory information from API document. This addresses issue #61 and allows the documents to be de-coupled.
1 parent 28488e1 commit 562faa2

File tree

1 file changed

+278
-0
lines changed

1 file changed

+278
-0
lines changed

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

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1972,6 +1972,284 @@ <h2>Aliasing Keywords</h2>
19721972

19731973
</section>
19741974

1975+
<section>
1976+
<h3>Expansion</h3>
1977+
<p>The JSON-LD API [[JSON-LD-API]] defines an method for <em>expanding</em> a JSON-LD document.
1978+
Expansion is the process of taking a JSON-LD document and applying a
1979+
context such that all IRI, datatypes, and literal values are expanded so
1980+
that the context is no longer necessary. JSON-LD document expansion
1981+
is typically used as a part of <a href="#framing">Framing</a>.</p>
1982+
1983+
<p>For example, assume the following JSON-LD input document:</p>
1984+
1985+
<pre class="example" data-transform="updateExample">
1986+
<!--
1987+
{
1988+
"@context":
1989+
{
1990+
"name": "http://xmlns.com/foaf/0.1/name",
1991+
"homepage": {
1992+
"@id": "http://xmlns.com/foaf/0.1/homepage",
1993+
"@type", "@id"
1994+
}
1995+
},
1996+
"name": "Manu Sporny",
1997+
"homepage": "http://manu.sporny.org/"
1998+
}
1999+
-->
2000+
</pre>
2001+
2002+
<p>Running the JSON-LD Expansion algorithm against the JSON-LD input document
2003+
provided above would result in the following output:</p>
2004+
2005+
<pre class="example" data-transform="updateExample">
2006+
<!--
2007+
{
2008+
"http://xmlns.com/foaf/0.1/name": "Manu Sporny",
2009+
"http://xmlns.com/foaf/0.1/homepage": {
2010+
"@id": "http://manu.sporny.org/"
2011+
}
2012+
}
2013+
-->
2014+
</pre>
2015+
</section>
2016+
2017+
<section>
2018+
<h3>Compaction</h3>
2019+
<p>The JSON-LD API [[JSON-LD-API]] defines an method for <em>compacting</em> a JSON-LD document.
2020+
Compaction is the process of taking a JSON-LD document and applying a
2021+
context such that the most compact form of the document is generated. JSON
2022+
is typically expressed in a very compact, key-value format. That is, full
2023+
IRIs are rarely used as keys. At times, a JSON-LD document may be received
2024+
that is not in its most compact form. JSON-LD, via the API, provides a way
2025+
to compact a JSON-LD document.</p>
2026+
2027+
<p>For example, assume the following JSON-LD input document:</p>
2028+
2029+
<pre class="example" data-transform="updateExample">
2030+
<!--
2031+
{
2032+
"http://xmlns.com/foaf/0.1/name": "Manu Sporny",
2033+
"http://xmlns.com/foaf/0.1/homepage": {
2034+
"@id": "http://manu.sporny.org/"
2035+
}
2036+
}
2037+
-->
2038+
</pre>
2039+
2040+
<p>Additionally, assume the following developer-supplied JSON-LD context:</p>
2041+
2042+
<pre class="example" data-transform="updateExample">
2043+
<!--
2044+
{
2045+
"name": "http://xmlns.com/foaf/0.1/name",
2046+
"homepage": {
2047+
"@id": "http://xmlns.com/foaf/0.1/homepage",
2048+
"@type": "@id"
2049+
}
2050+
}
2051+
-->
2052+
</pre>
2053+
2054+
<p>Running the JSON-LD Compaction algorithm given the context supplied above
2055+
against the JSON-LD input document provided above would result in the following
2056+
output:</p>
2057+
2058+
<pre class="example" data-transform="updateExample">
2059+
<!--
2060+
{
2061+
"@context": {
2062+
"name": "http://xmlns.com/foaf/0.1/name",
2063+
"homepage": {
2064+
"@id": "http://xmlns.com/foaf/0.1/homepage",
2065+
"@type": "@id"
2066+
}
2067+
},
2068+
"name": "Manu Sporny",
2069+
"homepage": "http://manu.sporny.org/"
2070+
}
2071+
-->
2072+
</pre>
2073+
2074+
<p>The compaction algorithm also enables the developer to map any expanded
2075+
format into an application-specific compacted format. While the context
2076+
provided above mapped <code>http://xmlns.com/foaf/0.1/name</code> to
2077+
<strong>name</strong>, it could have also mapped it to any arbitrary string
2078+
provided by the developer.</p>
2079+
</section>
2080+
2081+
<section>
2082+
<h3>Framing</h3>
2083+
<p>The JSON-LD API [[JSON-LD-API]] defines an method for <em>framing</em> a JSON-LD document.
2084+
This allows developers to query by example and force a specific tree layout to a JSON-LD document.</p>
2085+
2086+
<p>A JSON-LD document is a representation of a directed graph. A single
2087+
directed graph can have many different serializations, each expressing
2088+
exactly the same information. Developers typically work with trees, represented as
2089+
<tref>JSON object</tref>s. While mapping a graph to
2090+
a tree can be done, the layout of the end result must be specified in advance.
2091+
A <tdef>Frame</tdef> can be used by a developer on a JSON-LD document to
2092+
specify a deterministic layout for a graph.</p>
2093+
2094+
<p>Framing is the process of taking a JSON-LD document, which expresses a
2095+
graph of information, and applying a specific graph layout
2096+
(called a <tref>Frame</tref>).</p>
2097+
2098+
<p>The JSON-LD document below expresses a library, a book and a chapter:</p>
2099+
2100+
<pre class="example" data-transform="updateExample">
2101+
<!--
2102+
{
2103+
"@context": {
2104+
"Book": "http://example.org/vocab#Book",
2105+
"Chapter": "http://example.org/vocab#Chapter",
2106+
"contains": {
2107+
"@id": "http://example.org/vocab#contains",
2108+
"@type": "@id"
2109+
},
2110+
"creator": "http://purl.org/dc/terms/creator",
2111+
"description": "http://purl.org/dc/terms/description",
2112+
"Library": "http://example.org/vocab#Library",
2113+
"title": "http://purl.org/dc/terms/title"
2114+
},
2115+
"@id":
2116+
[{
2117+
"@id": "http://example.com/library",
2118+
"@type": "Library",
2119+
"contains": "http://example.org/library/the-republic"
2120+
},
2121+
{
2122+
"@id": "http://example.org/library/the-republic",
2123+
"@type": "Book",
2124+
"creator": "Plato",
2125+
"title": "The Republic",
2126+
"contains": "http://example.org/library/the-republic#introduction"
2127+
},
2128+
{
2129+
"@id": "http://example.org/library/the-republic#introduction",
2130+
"@type": "Chapter",
2131+
"description": "An introductory chapter on The Republic.",
2132+
"title": "The Introduction"
2133+
}]
2134+
}-->
2135+
</pre>
2136+
2137+
<p>Developers typically like to operate on items in a hierarchical, tree-based
2138+
fashion. Ideally, a developer would want the data above sorted into top-level
2139+
libraries, then the books that are contained in each library, and then the
2140+
chapters contained in each book. To achieve that layout, the developer can
2141+
define the following <tref>frame</tref>:</p>
2142+
2143+
<pre class="example" data-transform="updateExample">
2144+
<!--
2145+
{
2146+
"@context": {
2147+
"Book": "http://example.org/vocab#Book",
2148+
"Chapter": "http://example.org/vocab#Chapter",
2149+
"contains": "http://example.org/vocab#contains",
2150+
"creator": "http://purl.org/dc/terms/creator"
2151+
"description": "http://purl.org/dc/terms/description"
2152+
"Library": "http://example.org/vocab#Library",
2153+
"title": "http://purl.org/dc/terms/title"
2154+
},
2155+
"@type": "Library",
2156+
"contains": {
2157+
"@type": "Book",
2158+
"contains": {
2159+
"@type": "Chapter"
2160+
}
2161+
}
2162+
}
2163+
-->
2164+
</pre>
2165+
2166+
<p>When the framing algorithm is run against the previously defined
2167+
JSON-LD document, paired with the <tref>frame</tref> above, the following
2168+
JSON-LD document is the end result:</p>
2169+
2170+
<pre class="example" data-transform="updateExample">
2171+
<!--
2172+
{
2173+
"@context": {
2174+
"Book": "http://example.org/vocab#Book",
2175+
"Chapter": "http://example.org/vocab#Chapter",
2176+
"contains": "http://example.org/vocab#contains",
2177+
"creator": "http://purl.org/dc/terms/creator"
2178+
"description": "http://purl.org/dc/terms/description"
2179+
"Library": "http://example.org/vocab#Library",
2180+
"title": "http://purl.org/dc/terms/title"
2181+
},
2182+
"@id": "http://example.org/library",
2183+
"@type": "Library",
2184+
"contains": {
2185+
****"@id": "http://example.org/library/the-republic",****
2186+
"@type": "Book",
2187+
****"creator": "Plato",****
2188+
****"title": "The Republic",****
2189+
"contains": {
2190+
****"@id": "http://example.org/library/the-republic#introduction",****
2191+
"@type": "Chapter",
2192+
****"description": "An introductory chapter on The Republic.",****
2193+
****"title": "The Introduction"****
2194+
},
2195+
},
2196+
}
2197+
-->
2198+
</pre>
2199+
</section>
2200+
2201+
<section>
2202+
<h2>Normalization</h2>
2203+
2204+
<p>The JSON-LD API [[JSON-LD-API]] defines an method for <em>normalizing</em> a JSON-LD document.
2205+
Normalization is the process of performing a deterministic transformation on a JSON-LD document resulting in
2206+
a normalized representation.</p>
2207+
2208+
<p>Normalization is useful when comparing two graphs against one another,
2209+
when generating a detailed list of differences between two graphs, and
2210+
when generating a cryptographic digital signature for information contained
2211+
in a graph or when generating a hash of the information contained in a graph.</p>
2212+
2213+
<p>The example below is an un-normalized JSON-LD document:</p>
2214+
2215+
<pre class="example" data-transform="updateExample">
2216+
<!--
2217+
{
2218+
"@context": {
2219+
"name": "http://xmlns.com/foaf/0.1/name",
2220+
"homepage": {
2221+
"@id": "http://xmlns.com/foaf/0.1/homepage",
2222+
"@type": "@id"
2223+
},
2224+
"xsd": "http://www.w3.org/2001/XMLSchema#"
2225+
},
2226+
"name": "Manu Sporny",
2227+
"homepage": "http://manu.sporny.org/"
2228+
}
2229+
-->
2230+
</pre>
2231+
2232+
<p>The example below is the normalized form of the JSON-LD document above:</p>
2233+
2234+
<pre class="example" data-transform="updateExample">
2235+
<!--
2236+
[{
2237+
"@id": "_:c14n0",
2238+
"http://xmlns.com/foaf/0.1/homepage": {
2239+
"@id": "http://manu.sporny.org/"
2240+
},
2241+
"http://xmlns.com/foaf/0.1/name": "Manu Sporny"
2242+
}]
2243+
-->
2244+
</pre>
2245+
2246+
<p>Notice how all of the <tref>term</tref>s have been expanded and sorted in
2247+
alphabetical order. Also, notice how the <tref>subject</tref> has been labeled with a
2248+
named <tref>unlabeled node</tref>. Normalization ensures that any arbitrary graph
2249+
containing exactly the same information would be normalized to exactly the same form
2250+
shown above.</p>
2251+
2252+
</section>
19752253
</section>
19762254

19772255
<section class="appendix informative">

0 commit comments

Comments
 (0)