Add ldes uml (#109)

Author: ValyVanDenBroeck

.github/workflows/ldes-specification-build.yml

@@ -67,4 +67,4 @@ jobs:
             git push
           else
             echo "No changes to commit."
-          fi
+          fi

.github/workflows/ldes-vocabulary-build.yml

@@ -13,9 +13,47 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
 
     steps:
       - uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      - name: Install GraphViz
+        run: sudo apt-get update && sudo apt-get install -y graphviz
+
+      - name: Download PlantUML jar
+        run: curl -L -o plantuml.jar https://github.com/plantuml/plantuml/releases/download/v1.2024.7/plantuml-1.2024.7.jar
+
+      # Optionally check the SHA256 checksum to avoid corrupt downloads
+      # - name: Verify PlantUML jar checksum
+      #   run: echo "<expected_sha256_here>  plantuml.jar" | sha256sum -c -
+
+      - name: Render .puml to .svg
+        run: |
+          find . -name '*.puml' -exec java -jar plantuml.jar -tsvg -o . {} +
+
+      - name: Commit rendered diagrams
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git add *.svg
+
+          if git diff --cached --quiet; then
+            echo "No diagram changes to commit."
+          else
+            git commit -m "auto-rendered PlantUML diagrams"
+            git push
+          fi
+          rm -f plantuml.jar || true
 
       - name: Publish Bikeshed document
         uses: w3c/spec-prod@v2
@@ -61,4 +99,4 @@ jobs:
             git push
           else
             echo "No changes to commit."
-          fi
+          fi

context.jsonld

@@ -11,8 +11,8 @@
       "DurationAgoPolicy": "ldes:DurationAgoPolicy",
       "PointInTimePolicy": "ldes:PointInTimePolicy",
       "node": {"@type": "@id", "@id": "tree:node"},
-      "members": {"@type": "@id", "@id": "tree:member", "@container":"@list"},
-      "relations": {"@type": "@id", "@id": "tree:relation"},
+      "member": {"@type": "@id", "@id": "tree:member", "@container":"@list"},
+      "relation": {"@type": "@id", "@id": "tree:relation"},
       "view": {"@type": "@id", "@id": "tree:view"},
       "path": {"@container": "@list", "@id": "tree:path", "@type": "@id"},
       "value": {"@id":"tree:value"},

eventstreams.bs

@@ -435,7 +435,7 @@ When using the current time in calculations, the consumer MUST take into account
 The `ldes:timestampPath` points to the timestamp in the member that can be compared with the current time minus the durations.
 When the `ldes:versionTimestampPath` has been set, the two version durations must be compared with this timestamp.
 
-Historically, there are more specific types of retention policies that MUST remain supported, although their use is discouraged in favor of the retention policy design just introduced.
+Historically, there are more specific types of retention policies that MUST remain supported, although their use is discouraged in favour of the retention policy design just introduced.
 These retention policy types are:
  1. `ldes:DurationAgoPolicy`: a time-based retention policy in which data generated before a specified duration is not retained.
  2. `ldes:LatestVersionSubset`: a version subset based on the latest versions of an entity in the stream.

server-primer.bs

@@ -27,7 +27,7 @@ Note: When using content negotiation, set `Vary: Accept`.
 
 It SHOULD provide an `ETag` header on responses. If the page is immutable, it SHOULD provide a `Cache-Control: immutable` header.
 
-If [[!json-ld]] is used, there is an example context at https://w3id.org/ldes/context. 
+If [[!json-ld]] is used, there is an example [context](https://w3id.org/ldes/context). 
 Do not reference this URL directly in production; copy it into your project. 
 If you host an external context yourself, ensure robust caching with the `ETag` and/or `Cache-Control` max-age headers.
 
@@ -136,7 +136,7 @@ Computation and time base
 - If `ldes:versionTimestampPath` is set, evaluate `ldes:versionDuration` and `ldes:versionDeleteDuration` against that version timestamp.
 - Servers SHOULD account for small clock skew by using a safety buffer when computing which members fall outside the window.
 
-Publishing changes and server behavior
+Publishing changes and server behaviour
 - When compaction removes members or whole nodes from a view, update the search tree so that no relations point to removed nodes.
 - For nodes that are no longer available, respond with `410 Gone`. Clients will treat such a page as having no members and no relations.
 - Do not modify the content of immutable pages; instead, stop linking to them, redirect, or make them `410 Gone`.
@@ -147,7 +147,7 @@ Sliding full history for one year, plus version constraints
 ```turtle
 @prefix ldes: <https://w3id.org/ldes#> .
 @prefix tree: <https://w3id.org/tree#> .
-@prefix dcterms: <http://purl.org/dc/terms/> .
+@prefix dct: <http://purl.org/dc/terms/> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
 
 <> a ldes:EventSource ;
@@ -177,7 +177,7 @@ Point-in-time start and version window
 
 Notes
 - Changing a retention policy affects client expectations; keep the policy in sync with the actual availability of members.
-- Historical, more specific policy classes (`ldes:DurationAgoPolicy`, `ldes:LatestVersionSubset`, `ldes:PointInTimePolicy`) SHOULD remain supported for backward compatibility but are discouraged in favor of `ldes:retentionPolicy` with the properties above.
+- Historical, more specific policy classes (`ldes:DurationAgoPolicy`, `ldes:LatestVersionSubset`, `ldes:PointInTimePolicy`) SHOULD remain supported for backward compatibility but are discouraged in favour of `ldes:retentionPolicy` with the properties above.
 
 ## Rebalancing the search tree ## {#rebalancing}
 

uml.puml

@@ -0,0 +1,74 @@
+@startuml
+ 
+' ===================
+' Classes and Attributes
+' ===================
+ 
+class "tree::Relation" {
+ + tree:path
+ + tree:remainingItems : int
+ + tree:value
+}
+ 
+class "tree::Node" {
+ + ldes:immutable : boolean
+}
+ 
+class "tree::Collection" {
+ + tree:member
+}
+ 
+class "sh::NodeShape"
+ 
+class "dcat::Distribution"
+
+class "dcat::DataService"
+
+class "tree::SearchTree"
+ 
+class "ldes::RetentionPolicy" {
+ + ldes:fullLogDuration
+ + ldes:startingFrom : dateTime
+ + ldes:versionAmount
+ + ldes:versionDeleteDuration : duration
+ + ldes:versionDuration : duration
+}
+ 
+class "ldes::EventStream" {
+ + ldes:pollingInterval : int
+ + ldes:sequencePath
+ + ldes:timestampPath
+ + ldes:versionOfPath
+ + ldes:versionSequencePath
+ + ldes:versionTimestampPath
+}
+ 
+class "ldes::EventSource" {
+ + ldes:transactionFinalizedObject
+ + ldes:transactionFinalizedPath
+ + ldes:transactionPath
+ + ldes:versionCreateObject
+ + ldes:versionCreatePath
+ + ldes:versionDeleteObject
+ + ldes:versionDeletePath
+ + ldes:versionUpdateObject
+ + ldes:versionUpdatePath
+}
+ 
+' ===================
+' Relationships
+' ===================
+ 
+"tree::Node" --> "tree::SearchTree" : tree:viewDescription
+"tree::Node" --> "dcat::Distribution" : tree:viewDescription
+"tree::Node" --> "dcat::DataService" : tree:viewDescription
+"tree::Node" --> "ldes::RetentionPolicy" : ldes:retentionPolicy
+"tree::Node" --> "tree::Relation" : tree:relation
+"tree::Relation" --> "tree::Node" : tree:node
+"tree::Collection" --> "tree::Node" : tree:view
+"tree::Collection" --> "sh::NodeShape" : tree:shape
+"tree::Collection" <|-- "ldes::EventStream"
+"dcat::Distribution" <|-- "ldes::EventSource"
+"ldes::EventStream" --> "ldes::EventSource" : tree:viewDescription
+
+@enduml

uml.svg

@@ -16,6 +16,11 @@ This specification introduces terms used to describe event streams.
 While these terms can be used independently of the LDES specification,
 the main LDES specification is available at [https://w3id.org/ldes/specification](https://w3id.org/ldes/specification).
 
+<figure id="fig-ldes-model">
+ <img src="uml.svg" alt="LDES model diagram">
+ <figcaption>LDES model diagram (<a href="uml.puml">source</a>)</figcaption>
+</figure>
+
 # Terms # {#terms}
 
 This document introduces terms in the namespace `https://w3id.org/ldes#` with the preferred prefix `ldes:`.
@@ -24,11 +29,11 @@ There is also a [Turtle version available](https://w3id.org/ldes.ttl).
 Used prefixes are:
 
 ```turtle
-@prefix ldes: <https://w3id.org/ldes#> .
-@prefix tree: <https://w3id.org/tree#> .
 @prefix dct: <http://purl.org/dc/terms/> .
+@prefix ldes: <https://w3id.org/ldes#> .
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix tree: <https://w3id.org/tree#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
 ```
 
@@ -100,7 +105,7 @@ If the node is not going to contain new relations leading to new members, or new
 The class `ldes:EventSource` is a subclass of `dcat:Distribution`,
 specialized to represent a feed that uses a chronological search tree to make a Linked Data Event Stream available in order.
 
-An `ldes:EventSource` can only be published for LDESs that have `ldes:timestampPath` set, and thus publishes its entities in chronological order.
+An `ldes:EventSource` can only be published for `ldes:EventStream` that have `ldes:timestampPath` set, and thus publishes its entities in chronological order.
 
 ## ldes:retentionPolicy ## {#retentionPolicy}