Skip to content

Commit

Permalink
deploy: b1c5858
Browse files Browse the repository at this point in the history
  • Loading branch information
@pietercolpaert
pietercolpaert committed Sep 6, 2023
1 parent 521691d commit 61c4c34
Show file tree
Hide file tree
Showing 2 changed files with 34 additions and 34 deletions.
30 changes: 15 additions & 15 deletions eventstreams.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ An `tree:importStream` MAY be used to describe a publish-subscribe interface to
Note: A 1-dimensional fragmentation based on creation time of the immutable objects is probably going to be the most interesting and highest priority fragmentation for an LDES, as only the latest page, once replicated, should be subscribed to for updates.
However, it may happen that a time-based fragmentation cannot be applied. For example: the backend system on which the LDES has been built does not receive the events at the time they were created, due to human errors (forgetting to indicate that a change was made),
external systems or just latency. Applying a time-based fragmentation in that situation will result in losing caching, due to the ever-changing pages. Instead, in the spirit of an LDES’s goal, the publisher should publish the events in the order they were received
by the backend system (that order is never changing), trying to gave as many pages as possible an HTTP `Cache-Control: public, max-age=604800, immutable` header
by the backend system (that order is never changing), trying to give as many pages as possible an HTTP `Cache-Control: public, max-age=604800, immutable` header.

Note: Cfr. [the example in the TREE specification on “searching through a list of objects ordered in time”](https://treecg.github.io/specification/#timesearch), also a search form can optionally make a one dimensional feed of immutable objects more searchable.

Expand All @@ -102,7 +102,7 @@ Note: Cfr. [the example in the TREE specification on “searching through a list

By default, an LDES MUST keep all data that has been added to the `tree:Collection` (or `ldes:EventStream`) as defined by the TREE specification.
It MAY add a retention policy in which the server indicates data will be removed from the server.
Third parties SHOULD read retention policies to understand what subset of the data is available in this `tree:View`, and MAY archive these member.
Third parties SHOULD read retention policies to understand what subset of the data is available in this `tree:View`, and MAY archive these members.

In the LDES specification, three types of retention policies are defined which can be used with a `ldes:retentionPolicy` with an instance of a `tree:View` as its subject:
1. `ldes:DurationAgoPolicy`: a time-based retention policy in which data generated before a specified duration is removed
Expand Down Expand Up @@ -196,7 +196,7 @@ A `ldes:PointInTimePolicy` uses a `ldes:pointInTime` with an `xsd:dateTime`-type

We will extend the spec with multiple best practices on how to annotate that your newly published collection is derived from an LDES.

First we talk about a versioned LDES. Versioned LDESes allow for changing an object in a `ldes:EvenStream`, while maintaining the history of events.
First we talk about a versioned LDES. Versioned LDESes allow for changing an object in an `ldes:EvenStream`, while maintaining the history of events.
It is achieved by defining change in an `ldes:EventStream` through new `tree:member` in the `ldes:EventStream` through added metadata for both the `ldes:EvenStream` and each `tree:member`.

Secondly, version materializations are defined that use a versioned LDES as a basis.
Expand All @@ -215,7 +215,7 @@ A <b>versioned</b> LDES with one member.<br>

`dct:isVersionOf` is used as property for `ldes:versionOfPath`, which indicates that `ex:resource1v0` is a version of `ex:resource1`.<br>

`dct:issued` is used as property for `ldes:timestampPath`, which indicates that `ex:resource1v0` was issued in the ldes at "2021-12-15T10:00:00.000Z".
`dct:issued` is used as property for `ldes:timestampPath`, which indicates that `ex:resource1v0` was issued in the LDES at "2021-12-15T10:00:00.000Z".

```turtle
ex:ES a ldes:EventStream;
Expand All @@ -225,7 +225,7 @@ ex:ES a ldes:EventStream;

ex:resource1v0
dct:isVersionOf ex:resource1;
dct:issued "2021-12-15T10:00:00.000Z"^^xsd:dateTime.
dct:issued "2021-12-15T10:00:00.000Z"^^xsd:dateTime;
dct:title "First version of the title".
```
</div>
Expand All @@ -241,12 +241,12 @@ ex:ES a ldes:EventStream;

ex:resource1v0
dct:isVersionOf ex:resource1;
dct:issued "2021-12-15T10:00:00.000Z"^^xsd:dateTime.
dct:issued "2021-12-15T10:00:00.000Z"^^xsd:dateTime;
dct:title "First version of the title".

ex:resource1v1
dct:isVersionOf ex:resource1;
dct:issued "2021-12-15T12:00:00.000Z"^^xsd:dateTime.
dct:issued "2021-12-15T12:00:00.000Z"^^xsd:dateTime;
dct:title "Title has been updated once".
```
2 hours after `ex:resource1v0` was created, the title of `ex:resource1` was changed.
Expand All @@ -259,7 +259,7 @@ This change can be seen by the creation of `ex:resource1v1`, which is the newest
A version materialization can be defined only if the original LDES defines both `ldes:versionOfPath` and `ldes:timestampPath`.

A version materialization replaces the subject of a member with its `ldes:versionOfPath` IRI, and selects a certain version of this object.
It also translated `created` style timestamp predicates to `modified`-style predicates.
It also translates `created` style timestamp predicates to `modified`-style predicates.

<div class="example">
In this example an event stream with 2 versions of the same object got materialized until `2020-10-05T12:00:00Z`
Expand All @@ -269,8 +269,8 @@ ex:ES1 a ldes:EventStream
ldes:versionOfPath dct:isVersionOf;
ldes:timestampPath dct:created;
tree:member [
dcterms:isVersionOf <A> ;
dcterms:created "2020-10-05T11:00:00Z"
dcterms:isVersionOf <A>;
dcterms:created "2020-10-05T11:00:00Z";
owl:versionInfo "v0.0.1";
rdfs:label "A v0.0.1"
], [
Expand All @@ -283,12 +283,12 @@ ex:ES1 a ldes:EventStream
towards the snapshot below
```turtle
ex:ES1v1 a tree:Collection ; # the members are no longer immutable
ldes:versionMaterializationOf ex:ES1 ;
ldes:versionMaterializationUntil "2020-10-05T12:00:00Z"^^xsd:dateTime ;
tree:member <A> .
ldes:versionMaterializationOf ex:ES1;
ldes:versionMaterializationUntil "2020-10-05T12:00:00Z"^^xsd:dateTime;
tree:member <A>.

<A> rdfs:label "A v0.0.1" ;
dcterms:modified "2020-10-05T11:00:00Z" .
<A> rdfs:label "A v0.0.1";
dcterms:modified "2020-10-05T11:00:00Z".
```
</div>

Expand Down
38 changes: 19 additions & 19 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2016,7 +2016,7 @@
<div class="head">
<p data-fill-with="logo"></p>
<h1 class="p-name no-ref" id="title">Linked Data Event Streams</h1>
<h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span class="content">Living Standard, <time class="dt-updated" datetime="2023-04-28">28 April 2023</time></span></h2>
<h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span class="content">Living Standard, <time class="dt-updated" datetime="2023-09-06">6 September 2023</time></span></h2>
<div data-fill-with="spec-metadata">
<dl>
<dt>This version:
Expand All @@ -2030,7 +2030,7 @@ <h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span cla
<div data-fill-with="warning"></div>
<p class="copyright" data-fill-with="copyright"><a href="http://creativecommons.org/publicdomain/zero/1.0/" rel="license"><img alt="CC0" height="15" src="https://licensebuttons.net/p/zero/1.0/80x15.png" width="80"></a> To the extent possible under law, the editors have waived all copyright
and related or neighboring rights to this work.
In addition, as of 28 April 2023,
In addition, as of 6 September 2023,
the editors have made this specification available under the <a href="http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0" rel="license">Open Web Foundation Agreement Version 1.0</a>,
which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0.
Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document. </p>
Expand Down Expand Up @@ -2141,12 +2141,12 @@ <h2 class="heading settled" data-level="2" id="tree"><span class="secno">2. </sp
<p class="note" role="note"><span>Note:</span> A 1-dimensional fragmentation based on creation time of the immutable objects is probably going to be the most interesting and highest priority fragmentation for an LDES, as only the latest page, once replicated, should be subscribed to for updates.
However, it may happen that a time-based fragmentation cannot be applied. For example: the backend system on which the LDES has been built does not receive the events at the time they were created, due to human errors (forgetting to indicate that a change was made),
external systems or just latency. Applying a time-based fragmentation in that situation will result in losing caching, due to the ever-changing pages. Instead, in the spirit of an LDES’s goal, the publisher should publish the events in the order they were received
by the backend system (that order is never changing), trying to gave as many pages as possible an HTTP <code>Cache-Control: public, max-age=604800, immutable</code> header</p>
by the backend system (that order is never changing), trying to give as many pages as possible an HTTP <code>Cache-Control: public, max-age=604800, immutable</code> header.</p>
<p class="note" role="note"><span>Note:</span> Cfr. <a href="https://treecg.github.io/specification/#timesearch">the example in the TREE specification on “searching through a list of objects ordered in time”</a>, also a search form can optionally make a one dimensional feed of immutable objects more searchable.</p>
<h2 class="heading settled" data-level="3" id="retention"><span class="secno">3. </span><span class="content">Retention policies</span><a class="self-link" href="#retention"></a></h2>
<p>By default, an LDES MUST keep all data that has been added to the <code>tree:Collection</code> (or <code>ldes:EventStream</code>) as defined by the TREE specification.
It MAY add a retention policy in which the server indicates data will be removed from the server.
Third parties SHOULD read retention policies to understand what subset of the data is available in this <code>tree:View</code>, and MAY archive these member.</p>
Third parties SHOULD read retention policies to understand what subset of the data is available in this <code>tree:View</code>, and MAY archive these members.</p>
<p>In the LDES specification, three types of retention policies are defined which can be used with a <code>ldes:retentionPolicy</code> with an instance of a <code>tree:View</code> as its subject:</p>
<ol>
<li data-md>
Expand Down Expand Up @@ -2223,7 +2223,7 @@ <h3 class="heading settled" data-level="3.3" id="point-in-time"><span class="sec
<p>A <code>ldes:PointInTimePolicy</code> uses a <code>ldes:pointInTime</code> with an <code>xsd:dateTime</code>-typed literal to indicate the point in time after which data is kept.</p>
<h2 class="heading settled" data-level="4" id="derived"><span class="secno">4. </span><span class="content">Derived collections</span><a class="self-link" href="#derived"></a></h2>
<p>We will extend the spec with multiple best practices on how to annotate that your newly published collection is derived from an LDES.</p>
<p>First we talk about a versioned LDES. Versioned LDESes allow for changing an object in a <code>ldes:EvenStream</code>, while maintaining the history of events.
<p>First we talk about a versioned LDES. Versioned LDESes allow for changing an object in an <code>ldes:EvenStream</code>, while maintaining the history of events.
It is achieved by defining change in an <code>ldes:EventStream</code> through new <code>tree:member</code> in the <code>ldes:EventStream</code> through added metadata for both the <code>ldes:EvenStream</code> and each <code>tree:member</code>.</p>
<p>Secondly, version materializations are defined that use a versioned LDES as a basis.
This technique allows to create <strong>snapshots</strong> in time of a versioned LDES.
Expand All @@ -2239,15 +2239,15 @@ <h3 class="heading settled" data-level="4.1" id="versioning"><span class="secno"
<div class="example" id="ldes-versioning-1">
<a class="self-link" href="#ldes-versioning-1"></a> A <b>versioned</b> LDES with one member.<br>
<p><code class="highlight"><c- nn>dct</c-><c- p>:</c-><c- f>isVersionOf</c-></code> is used as property for <code class="highlight"><c- nn>ldes</c-><c- p>:</c-><c- f>versionOfPath</c-></code>, which indicates that <code class="highlight"><c- nn>ex</c-><c- p>:</c-><c- f>resource1v0</c-></code> is a version of <code class="highlight"><c- nn>ex</c-><c- p>:</c-><c- f>resource1</c-></code>.<br></p>
<p><code class="highlight"><c- nn>dct</c-><c- p>:</c-><c- f>issued</c-></code> is used as property for <code class="highlight"><c- nn>ldes</c-><c- p>:</c-><c- f>timestampPath</c-></code>, which indicates that <code class="highlight"><c- nn>ex</c-><c- p>:</c-><c- f>resource1v0</c-></code> was issued in the ldes at "2021-12-15T10:00:00.000Z".</p>
<p><code class="highlight"><c- nn>dct</c-><c- p>:</c-><c- f>issued</c-></code> is used as property for <code class="highlight"><c- nn>ldes</c-><c- p>:</c-><c- f>timestampPath</c-></code>, which indicates that <code class="highlight"><c- nn>ex</c-><c- p>:</c-><c- f>resource1v0</c-></code> was issued in the LDES at "2021-12-15T10:00:00.000Z".</p>
<pre class="language-turtle highlight"><c- nn>ex</c-><c- p>:</c-><c- f>ES</c-> <c- b>a</c-> <c- nn>ldes</c-><c- p>:</c-><c- f>EventStream</c-><c- p>;</c->
<c- nn>ldes</c-><c- p>:</c-><c- f>versionOfPath</c-> <c- nn>dct</c-><c- p>:</c-><c- f>isVersionOf</c-><c- p>;</c->
<c- nn>ldes</c-><c- p>:</c-><c- f>timestampPath</c-> <c- nn>dct</c-><c- p>:</c-><c- f>issued</c-><c- p>;</c->
<c- nn>tree</c-><c- p>:</c-><c- f>member</c-> <c- nn>ex</c-><c- p>:</c-><c- f>resource1v0</c-><c- p>.</c->

<c- nn>ex</c-><c- p>:</c-><c- f>resource1v0</c->
<c- nn>dct</c-><c- p>:</c-><c- f>isVersionOf</c-> <c- nn>ex</c-><c- p>:</c-><c- f>resource1</c-><c- p>;</c->
<c- nn>dct</c-><c- p>:</c-><c- f>issued</c-> <c- s>"2021-12-15T10:00:00.000Z"</c-><c- p>^^</c-><c- nn>xsd</c-><c- p>:</c-><c- f>dateTime</c-><c- p>.</c->
<c- nn>dct</c-><c- p>:</c-><c- f>issued</c-> <c- s>"2021-12-15T10:00:00.000Z"</c-><c- p>^^</c-><c- nn>xsd</c-><c- p>:</c-><c- f>dateTime</c-><c- p>;</c->
<c- nn>dct</c-><c- p>:</c-><c- f>title</c-> <c- s>"First version of the title"</c-><c- p>.</c->
</pre>
</div>
Expand All @@ -2260,12 +2260,12 @@ <h3 class="heading settled" data-level="4.1" id="versioning"><span class="secno"

<c- nn>ex</c-><c- p>:</c-><c- f>resource1v0</c->
<c- nn>dct</c-><c- p>:</c-><c- f>isVersionOf</c-> <c- nn>ex</c-><c- p>:</c-><c- f>resource1</c-><c- p>;</c->
<c- nn>dct</c-><c- p>:</c-><c- f>issued</c-> <c- s>"2021-12-15T10:00:00.000Z"</c-><c- p>^^</c-><c- nn>xsd</c-><c- p>:</c-><c- f>dateTime</c-><c- p>.</c->
<c- nn>dct</c-><c- p>:</c-><c- f>issued</c-> <c- s>"2021-12-15T10:00:00.000Z"</c-><c- p>^^</c-><c- nn>xsd</c-><c- p>:</c-><c- f>dateTime</c-><c- p>;</c->
<c- nn>dct</c-><c- p>:</c-><c- f>title</c-> <c- s>"First version of the title"</c-><c- p>.</c->

<c- nn>ex</c-><c- p>:</c-><c- f>resource1v1</c->
<c- nn>dct</c-><c- p>:</c-><c- f>isVersionOf</c-> <c- nn>ex</c-><c- p>:</c-><c- f>resource1</c-><c- p>;</c->
<c- nn>dct</c-><c- p>:</c-><c- f>issued</c-> <c- s>"2021-12-15T12:00:00.000Z"</c-><c- p>^^</c-><c- nn>xsd</c-><c- p>:</c-><c- f>dateTime</c-><c- p>.</c->
<c- nn>dct</c-><c- p>:</c-><c- f>issued</c-> <c- s>"2021-12-15T12:00:00.000Z"</c-><c- p>^^</c-><c- nn>xsd</c-><c- p>:</c-><c- f>dateTime</c-><c- p>;</c->
<c- nn>dct</c-><c- p>:</c-><c- f>title</c-> <c- s>"Title has been updated once"</c-><c- p>.</c->
</pre>
2 hours after <code class="highlight"><c- nn>ex</c-><c- p>:</c-><c- f>resource1v0</c-></code> was created, the title of <code class="highlight"><c- nn>ex</c-><c- p>:</c-><c- f>resource1</c-></code> was changed.
Expand All @@ -2274,15 +2274,15 @@ <h3 class="heading settled" data-level="4.1" id="versioning"><span class="secno"
<h3 class="heading settled" data-level="4.2" id="version-materializations"><span class="secno">4.2. </span><span class="content">Version Materializations</span><a class="self-link" href="#version-materializations"></a></h3>
<p>A version materialization can be defined only if the original LDES defines both <code>ldes:versionOfPath</code> and <code>ldes:timestampPath</code>.</p>
<p>A version materialization replaces the subject of a member with its <code>ldes:versionOfPath</code> IRI, and selects a certain version of this object.
It also translated <code>created</code> style timestamp predicates to <code>modified</code>-style predicates.</p>
<div class="example" id="example-7d671c40">
<a class="self-link" href="#example-7d671c40"></a> In this example an event stream with 2 versions of the same object got materialized until <code>2020-10-05T12:00:00Z</code>
It also translates <code>created</code> style timestamp predicates to <code>modified</code>-style predicates.</p>
<div class="example" id="example-fe6ebb5b">
<a class="self-link" href="#example-fe6ebb5b"></a> In this example an event stream with 2 versions of the same object got materialized until <code>2020-10-05T12:00:00Z</code>
<pre class="language-turtle highlight"><c- nn>ex</c-><c- p>:</c-><c- f>ES1</c-> <c- b>a</c-> <c- nn>ldes</c-><c- p>:</c-><c- f>EventStream</c->
<c- nn>ldes</c-><c- p>:</c-><c- f>versionOfPath</c-> <c- nn>dct</c-><c- p>:</c-><c- f>isVersionOf</c-><c- p>;</c->
<c- nn>ldes</c-><c- p>:</c-><c- f>timestampPath</c-> <c- nn>dct</c-><c- p>:</c-><c- f>created</c-><c- p>;</c->
<c- nn>tree</c-><c- p>:</c-><c- f>member</c-> <c- p>[</c->
<c- nn>dcterms</c-><c- p>:</c-><c- f>isVersionOf</c-> <c- g>&lt;A></c-> <c- p>;</c->
<c- nn>dcterms</c-><c- p>:</c-><c- f>created</c-> <c- s>"2020-10-05T11:00:00Z"</c->
<c- nn>dcterms</c-><c- p>:</c-><c- f>isVersionOf</c-> <c- g>&lt;A></c-><c- p>;</c->
<c- nn>dcterms</c-><c- p>:</c-><c- f>created</c-> <c- s>"2020-10-05T11:00:00Z"</c-><c- p>;</c->
<c- nn>owl</c-><c- p>:</c-><c- f>versionInfo</c-> <c- s>"v0.0.1"</c-><c- p>;</c->
<c- nn>rdfs</c-><c- p>:</c-><c- f>label</c-> <c- s>"A v0.0.1"</c->
<c- p>],</c-> <c- p>[</c->
Expand All @@ -2294,12 +2294,12 @@ <h3 class="heading settled" data-level="4.2" id="version-materializations"><span
</pre>
towards the snapshot below
<pre class="language-turtle highlight"><c- nn>ex</c-><c- p>:</c-><c- f>ES1v1</c-> <c- b>a</c-> <c- nn>tree</c-><c- p>:</c-><c- f>Collection</c-> <c- p>;</c-> <c- c># the members are no longer immutable</c->
<c- nn>ldes</c-><c- p>:</c-><c- f>versionMaterializationOf</c-> <c- nn>ex</c-><c- p>:</c-><c- f>ES1</c-> <c- p>;</c->
<c- nn>ldes</c-><c- p>:</c-><c- f>versionMaterializationUntil</c-> <c- s>"2020-10-05T12:00:00Z"</c-><c- p>^^</c-><c- nn>xsd</c-><c- p>:</c-><c- f>dateTime</c-> <c- p>;</c->
<c- nn>tree</c-><c- p>:</c-><c- f>member</c-> <c- g>&lt;A></c-> <c- p>.</c->
<c- nn>ldes</c-><c- p>:</c-><c- f>versionMaterializationOf</c-> <c- nn>ex</c-><c- p>:</c-><c- f>ES1</c-><c- p>;</c->
<c- nn>ldes</c-><c- p>:</c-><c- f>versionMaterializationUntil</c-> <c- s>"2020-10-05T12:00:00Z"</c-><c- p>^^</c-><c- nn>xsd</c-><c- p>:</c-><c- f>dateTime</c-><c- p>;</c->
<c- nn>tree</c-><c- p>:</c-><c- f>member</c-> <c- g>&lt;A></c-><c- p>.</c->

<c- g>&lt;A></c-> <c- nn>rdfs</c-><c- p>:</c-><c- f>label</c-> <c- s>"A v0.0.1"</c-> <c- p>;</c->
<c- nn>dcterms</c-><c- p>:</c-><c- f>modified</c-> <c- s>"2020-10-05T11:00:00Z"</c-> <c- p>.</c->
<c- g>&lt;A></c-> <c- nn>rdfs</c-><c- p>:</c-><c- f>label</c-> <c- s>"A v0.0.1"</c-><c- p>;</c->
<c- nn>dcterms</c-><c- p>:</c-><c- f>modified</c-> <c- s>"2020-10-05T11:00:00Z"</c-><c- p>.</c->
</pre>
</div>
<p>A version materialization is thus a <code>tree:Collection</code> instance that has two predicates set:</p>
Expand Down

0 comments on commit 61c4c34

Please sign in to comment.