Skip to content

describing property-based indexing as a variant of data indexing #145

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 9 commits into from
Apr 17, 2019
Merged

describing property-based indexing as a variant of data indexing #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
976e969
describing property-based indexing as a variant of data indexing
pchampin Mar 19, 2019
c3a463d
Skip illegal examples.
gkellogg Apr 15, 2019
c3db5f5
Set `@version` on example 77.
gkellogg Apr 15, 2019
5e96898
Update index.html
gkellogg Apr 15, 2019
2ed383d
Add note on restrictions on the use of property-based data indexing.
gkellogg Apr 15, 2019
38731a7
used a different prefix for DC elements
pchampin Apr 16, 2019
fcd855e
added section on property-based index maps in Grammar section
pchampin Apr 16, 2019
9c55bb9
improvements to other sections of the Grammar
pchampin Apr 16, 2019
a311780
fixed typo
pchampin Apr 16, 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
10 changes: 5 additions & 5 deletions Gemfile.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
GIT
remote: git://github.com/ruby-rdf/json-ld.git
revision: 32935901cd7390b256c6904c096645681db3668f
revision: 3ad421e9e0328be7225809012f0091c269e84b5c
branch: develop
specs:
json-ld (3.0.2)
Expand Down Expand Up @@ -80,9 +80,9 @@ GEM
nokogumbo (1.5.0)
nokogiri
public_suffix (3.0.3)
rack (2.0.6)
rack (2.0.7)
rake (12.3.2)
rdf (3.0.10)
rdf (3.0.11)
hamster (~> 3.0)
link_header (~> 0.0, >= 0.0.8)
rdf-aggregate-repo (2.2.1)
Expand Down Expand Up @@ -131,8 +131,8 @@ GEM
rdf-turtle (3.0.5)
ebnf (~> 1.1)
rdf (~> 3.0)
rdf-vocab (3.0.4)
rdf (~> 3.0)
rdf-vocab (3.0.5)
rdf (~> 3.0, >= 3.0.11)
rdf-xsd (3.0.1)
rdf (~> 3.0)
shex (0.5.2)
Expand Down
2 changes: 1 addition & 1 deletion common/extract-examples.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,7 @@ def dataset_to_table(repo)

File.open(input, "r") do |f|
doc = Nokogiri::HTML.parse(f.read)
doc.css(".example, .illegal-example").each do |element|
doc.css(".example").each do |element|
error = nil
warn = nil
example_number += 1 if %w(pre aside).include?(element.name)
Expand Down
237 changes: 230 additions & 7 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6166,8 +6166,8 @@ <h3>Using the Document Base for the Default Vocabulary</h3>

<p>Databases are typically used to make access to
data more efficient. Developers often extend this sort of functionality into
their application data to deliver similar performance gains. Often this
data does not have any meaning from a Linked Data standpoint, but is
their application data to deliver similar performance gains.
This data may have no meaning from a Linked Data standpoint, but is
still useful for an application.</p>

<p>JSON-LD introduces the notion of <a>index maps</a>
Expand Down Expand Up @@ -6552,6 +6552,202 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
-->
</pre>
</aside>

<section class="informative changed"><h3>Property-based data indexing</h3>
<p>In its simplest form (as in the examples above),
data indexing assigns no semantics to the keys of an <a>index map</a>.
However, in some situations,
the keys used to index objects are semantically linked to these objects,
and should be preserved not only syntactically, but also semantically.
</p>
<p>If the <a>processing mode</a> is set to <code>json-ld-1.1</code>,
<code>"@container": "@index"</code> in a term description can be accompanied with
an <code>"@index"</code> key. The value of that key must map to an <a>IRI</a>,
which identifies the semantic property linking each object to its key.
</p>
<aside class="example ds-selector-tabs"
title="Property-based data indexing">
<div class="selectors">
<button class="selected" data-selects="original">Original</button>
<button data-selects="expanded">Expanded</button>
<button data-selects="statements">Statements</button>
<button data-selects="turtle">Turtle</button>
<a class="playground" target="_blank"></a>
</div>
<pre class="original selected nohighlight" data-transform="updateExample">
<!--
{
"@context": {
"@version": 1.1,
"schema": "http://schema.org/",
"dc11": "http://purl.org/dc/elements/1.1/",
"name": "schema:name",
"body": "schema:articleBody",
"words": "schema:wordCount",
"post": {
"@id": "schema:blogPost",
****"@container": "@index",
"@index": "dc11:language"****
}
},
"@id": "http://example.com/",
"@type": "schema:Blog",
"name": "World Financial News",
"post": {
"en": {
####↑ "en" will add `"dc11:language": "en"` when expanded####
"@id": "http://example.com/posts/1/en",
"body": "World commodities were up today with heavy trading of crude oil...",
"words": 1539
},
"de": {
"@id": "http://example.com/posts/1/de",
"body": "Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl...",
"words": 1204
}
}
}
-->
</pre>
<pre class="expanded nohighlight"
data-transform="updateExample"
data-ignore
data-result-for="Property-based data indexing-original">
<!--
[{
"@id": "http://example.com/",
"@type": ["http://schema.org/Blog"],
"http://schema.org/name": [{"@value": "World Financial News"}],
"http://schema.org/blogPost": [{
"@id": "http://example.com/posts/1/en",
"http://schema.org/articleBody": [
{"@value": "World commodities were up today with heavy trading of crude oil..."}
],
"http://schema.org/wordCount": [
{"@value": 1539}
],
****"http://purl.org/dc/elements/1.1/language": "en"****
}, {
"@id": "http://example.com/posts/1/de",
"http://schema.org/articleBody": [
{"@value": "Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl..."}
],
"http://schema.org/wordCount": [{"@value": 1204}],
****"http://purl.org/dc/elements/1.1/language": "de"****
}]
}]
-->
</pre>
<table class="statements"
data-ignore
data-result-for="Property-based data indexing-expanded"
data-to-rdf>
<thead><tr>
<th>Subject</th>
<th>Property</th>
<th>Value</th>
<th>Value Type</th>
</tr></thead>
<tbody>
<tr>
<td>http://example.com/</td>
<td>rdf:type</td>
<td>schema:Blog</td>
<td></td>
</tr>
<tr>
<td>http://example.com/</td>
<td>schema:name</td>
<td>World Financial News</td>
<td></td>
</tr>
<tr>
<td>http://example.com/</td>
<td>schema:blogPost</td>
<td>http://example.com/posts/1/de</td>
<td></td>
</tr>
<tr>
<td>http://example.com/</td>
<td>schema:blogPost</td>
<td>http://example.com/posts/1/en</td>
<td></td>
</tr>
<tr>
<td>http://example.com/posts/1/de</td>
<td>schema:articleBody</td>
<td>Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl...</td>
<td></td>
</tr>
<tr>
<td>http://example.com/posts/1/de</td>
<td>schema:wordCount</td>
<td>1204</td>
<td>xsd:integer</td>
</tr>
<tr>
<td>http://example.com/posts/1/de</td>
<td>dc11:language</td>
<td>de</td>
<td></td>
</tr>
<tr>
<td>http://example.com/posts/1/en</td>
<td>schema:articleBody</td>
<td>World commodities were up today with heavy trading of crude oil...</td>
<td></td>
</tr>
<tr>
<td>http://example.com/posts/1/en</td>
<td>schema:wordCount</td>
<td>1539</td>
<td>xsd:integer</td>
</tr>
<tr>
<td>http://example.com/posts/1/en</td>
<td>dc11:language</td>
<td>en</td>
<td></td>
</tr>
</tbody>
</table>
<pre class="turtle nohighlight"
data-content-type="text/turtle"
data-ignore
data-result-for="Property-based data indexing-expanded"
data-transform="updateExample"
data-to-rdf>
<!--
@prefix schema: <http://schema.org/> .
@prefix dc11: <http://purl.org/dc/elements/1.1/language> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<http://example.com/> a schema:Blog;
schema:blogPost <http://example.com/posts/1/de>,
<http://example.com/posts/1/en>;
schema:name "World Financial News" .

<http://example.com/posts/1/de>
schema:articleBody
"Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl...";
schema:wordCount 1204;
****dc11:language "de"****.

<http://example.com/posts/1/en>
schema:articleBody
"World commodities were up today with heavy trading of crude oil...";
schema:wordCount 1539;
****dc11:language "en"****.
-->
</pre>
</aside>

<p class="note">When using property-based data indexing, <a>index maps</a> can only be used
on <a>node objects</a>, not <a>value objects</a> or <a>graph objects</a>.
<a>Value objects</a> are restricted to have only certain keys and do not support
arbitrary properties.</p>
</section>

</section>
<section class="informative"><h2>Language Indexing</h2>

Expand Down Expand Up @@ -9269,7 +9465,7 @@ <h3>Graph Containers</h3>
on an internalized representation of that JSON would need to
iterrate through the values of the array to find a value matching
a particular pattern, such as a <a>language-tagged string</a>
using that language <code>en</code>.</p>
using the language <code>en</code>.</p>

<aside class="example" title="Indexing language-tagged strings">
<p>Given the following expanded document:</p>
Expand Down Expand Up @@ -10576,7 +10772,7 @@ <h2>Node Objects</h2>
key, its value MUST be
a <a>node object</a> or
an <a>array</a> of zero or more <a>node objects</a>.
If the <a>node object</a> contains an <code>@id</code> keyword,
If the <a>node object</a> also contains an <code>@id</code> keyword,
its value is used as the <a>graph name</a> of a <a>named graph</a>.
See <a class="sectionRef" href="#named-graphs"></a> for further discussion on
<code>@graph</code> values. As a special case, if a <a>dictionary</a>
Expand Down Expand Up @@ -10863,6 +11059,32 @@ <h2>Index Maps</h2>
not include <code>@id</code>, or a <a>named graph</a> if it includes <code>@id</code>.</p>
</section>

<section class="changed">
<h2>Property-based Index Maps</h2>

<p>A property-based <a>index map</a> is a variant of <a>index map</a>
were indexes are semantically preserved in the graph as property values.
A property-based <a>index map</a> may be used as a term value within a <a>node object</a>
if the <a>term</a> is defined with <code>@container</code> set to <code>@index</code>,
or an array containing both <code>@index</code> and <code>@set</code>,
and with <code>@index</code> set to a <a>string</a>.
The values of a property-based <a>index map</a> MUST be <a>node objects</a>
or <a>strings</a> which expand to <a>node objects</a>.</p>

<p>When expanding,
if the <a>active context</a> contains a <a>term definition</a>
for the value of <code>@index</code>,
this <a>term definition</a> will be used to expand the keys of the <a>index map</a>.
Otherwise, the keys will be expanded as simple <a>value objects</a>.
Each <a>node object</a> in the expanded values of the <a>index map</a>
will be added an additional property value,
where the property is the expanded value of <code>@index</code>,
and the value is the expanded referencing key.
</p>

<p>See <a class="sectionRef" href="#property-based-data-indexing"></a> for further information on this topic.</p>
</section>

<section class="changed">
<h2>Id Maps</h2>

Expand Down Expand Up @@ -10897,9 +11119,10 @@ <h2>Type Maps</h2>
or an array containing both <code>@type</code> and <code>@set</code>.
The keys of a <a>type map</a> MUST be <a>IRIs</a>
(<a>relative IRI</a>, <a>compact IRI</a> (including <a>blank node identifiers</a>), or <a>absolute IRI</a>),
the <a>keyword</a> <code>@none</code>,
or a <a>term</a> which expands to <code>@none</code>,
and the values MUST be <a>node objects</a>.</p>
<a>terms</a>,
Copy link
Contributor Author

Choose a reason for hiding this comment

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

the previous version limited this to "terms expaning to @none", but for type-map, it seems to me that any term can be used (at least, this works in the playground and the Ruby distiller)

Copy link
Member

Choose a reason for hiding this comment

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

This line is in the Type Maps section, which has always allowed terms.

or the <a>keyword</a> <code>@none</code>,
and the values MUST be <a>node objects</a>
or <a>strings</a> which expand to <a>node objects</a>.</p>

<p>If the value contains a property expanding to <code>@type</code>, and it's value
is contains the referencing key after suitable expansion of both the referencing key
Expand Down