From 0dd795eec7fb2e94289841b366296ef7cb303ce3 Mon Sep 17 00:00:00 2001 From: ValyVanDenBroeck Date: Wed, 22 Oct 2025 23:45:36 +0200 Subject: [PATCH 1/5] Add uml file Update ldes-vocabulary-build.yml to render plantuml svg Update vocabulary.bs add UML --- .../workflows/ldes-specification-build.yml | 2 +- .github/workflows/ldes-vocabulary-build.yml | 40 ++++++++++- uml.puml | 69 +++++++++++++++++++ vocabulary.bs | 5 ++ 4 files changed, 114 insertions(+), 2 deletions(-) create mode 100644 uml.puml diff --git a/.github/workflows/ldes-specification-build.yml b/.github/workflows/ldes-specification-build.yml index cb6dd6e..a97182e 100644 --- a/.github/workflows/ldes-specification-build.yml +++ b/.github/workflows/ldes-specification-build.yml @@ -67,4 +67,4 @@ jobs: git push else echo "No changes to commit." - fi \ No newline at end of file + fi diff --git a/.github/workflows/ldes-vocabulary-build.yml b/.github/workflows/ldes-vocabulary-build.yml index 58cfdd1..970894c 100644 --- a/.github/workflows/ldes-vocabulary-build.yml +++ b/.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 " 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 \ No newline at end of file + fi diff --git a/uml.puml b/uml.puml new file mode 100644 index 0000000..7d50aa6 --- /dev/null +++ b/uml.puml @@ -0,0 +1,69 @@ +@startuml + +' =================== +' Classes and Attributes +' =================== + +class "tree::Relation" { + + tree:path + + tree:remainingItems : int + + tree:value +} + +class "tree::Node" { + + ldes:immutable : boolean + + ldes:viewDescription +} + +class "tree::Collection" { + + tree:member +} + +class "sh::NodeShape" + +class "dcat::Distribution" + +class "hydra::IriTemplate" + +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::Relation" --> "tree::Node" : tree:node +"tree::Node" --> "tree::Collection" : tree:view +"tree::Collection" --> "tree::Node" : tree:shape +"dcat::Distribution" <|-- "ldes::EventSource" +"ldes::EventSource" --> "ldes::EventStream" : tree:viewDescription +"ldes::EventStream" --> "ldes::RetentionPolicy" : ldes:retentionPolicy +"tree::Relation" --> "hydra::IriTemplate" : hydra:iriTemplate + +@enduml diff --git a/vocabulary.bs b/vocabulary.bs index 64d9889..43f6863 100644 --- a/vocabulary.bs +++ b/vocabulary.bs @@ -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). +
+ LDES model diagram +
LDES model diagram (source)
+
+ # Terms # {#terms} This document introduces terms in the namespace `https://w3id.org/ldes#` with the preferred prefix `ldes:`. From 7b6d3160df363e259f85357ca2d5336647f7fb51 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 27 Oct 2025 17:41:41 +0000 Subject: [PATCH 2/5] auto-rendered PlantUML diagrams --- uml.svg | 1 + 1 file changed, 1 insertion(+) create mode 100644 uml.svg diff --git a/uml.svg b/uml.svg new file mode 100644 index 0000000..433b5ab --- /dev/null +++ b/uml.svg @@ -0,0 +1 @@ +tree::Relationtree:pathtree:remainingItems : inttree:valuetree::Nodeldes:immutable : booleanldes:viewDescriptiontree::Collectiontree:membersh::NodeShapedcat::Distributionhydra::IriTemplateldes::RetentionPolicyldes:fullLogDurationldes:startingFrom : dateTimeldes:versionAmountldes:versionDeleteDuration : durationldes:versionDuration : durationldes::EventStreamldes:pollingInterval : intldes:sequencePathldes:timestampPathldes:versionOfPathldes:versionSequencePathldes:versionTimestampPathldes::EventSourceldes:transactionFinalizedObjectldes:transactionFinalizedPathldes:transactionPathldes:versionCreateObjectldes:versionCreatePathldes:versionDeleteObjectldes:versionDeletePathldes:versionUpdateObjectldes:versionUpdatePathtree:nodetree:viewtree:shapetree:viewDescriptionldes:retentionPolicyhydra:iriTemplate \ No newline at end of file From dec3950269cb7777b2540007f4e342c911c363be Mon Sep 17 00:00:00 2001 From: ValyVanDenBroeck Date: Tue, 28 Oct 2025 11:22:36 +0100 Subject: [PATCH 3/5] Update uml.puml --- uml.puml | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/uml.puml b/uml.puml index 7d50aa6..168abbb 100644 --- a/uml.puml +++ b/uml.puml @@ -12,7 +12,6 @@ class "tree::Relation" { class "tree::Node" { + ldes:immutable : boolean - + ldes:viewDescription } class "tree::Collection" { @@ -22,8 +21,10 @@ class "tree::Collection" { class "sh::NodeShape" class "dcat::Distribution" - -class "hydra::IriTemplate" + +class "dcat::DataService" + +class "tree::SearchTree" class "ldes::RetentionPolicy" { + ldes:fullLogDuration @@ -58,12 +59,16 @@ class "ldes::EventSource" { ' 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::Node" --> "tree::Collection" : tree:view -"tree::Collection" --> "tree::Node" : tree:shape +"tree::Collection" --> "tree::Node" : tree:view +"tree::Collection" --> "sh::NodeShape" : tree:shape +"tree::Collection" <|-- "ldes::EventStream" "dcat::Distribution" <|-- "ldes::EventSource" -"ldes::EventSource" --> "ldes::EventStream" : tree:viewDescription -"ldes::EventStream" --> "ldes::RetentionPolicy" : ldes:retentionPolicy -"tree::Relation" --> "hydra::IriTemplate" : hydra:iriTemplate - +"ldes::EventStream" --> "ldes::EventSource" : tree:viewDescription + @enduml From c6d723b17d0557060aea808c6014912ecdc266c5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 29 Oct 2025 22:18:36 +0000 Subject: [PATCH 4/5] auto-rendered PlantUML diagrams --- uml.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/uml.svg b/uml.svg index 433b5ab..6506581 100644 --- a/uml.svg +++ b/uml.svg @@ -1 +1 @@ -tree::Relationtree:pathtree:remainingItems : inttree:valuetree::Nodeldes:immutable : booleanldes:viewDescriptiontree::Collectiontree:membersh::NodeShapedcat::Distributionhydra::IriTemplateldes::RetentionPolicyldes:fullLogDurationldes:startingFrom : dateTimeldes:versionAmountldes:versionDeleteDuration : durationldes:versionDuration : durationldes::EventStreamldes:pollingInterval : intldes:sequencePathldes:timestampPathldes:versionOfPathldes:versionSequencePathldes:versionTimestampPathldes::EventSourceldes:transactionFinalizedObjectldes:transactionFinalizedPathldes:transactionPathldes:versionCreateObjectldes:versionCreatePathldes:versionDeleteObjectldes:versionDeletePathldes:versionUpdateObjectldes:versionUpdatePathtree:nodetree:viewtree:shapetree:viewDescriptionldes:retentionPolicyhydra:iriTemplate \ No newline at end of file +tree::Relationtree:pathtree:remainingItems : inttree:valuetree::Nodeldes:immutable : booleantree::Collectiontree:membersh::NodeShapedcat::Distributiondcat::DataServicetree::SearchTreeldes::RetentionPolicyldes:fullLogDurationldes:startingFrom : dateTimeldes:versionAmountldes:versionDeleteDuration : durationldes:versionDuration : durationldes::EventStreamldes:pollingInterval : intldes:sequencePathldes:timestampPathldes:versionOfPathldes:versionSequencePathldes:versionTimestampPathldes::EventSourceldes:transactionFinalizedObjectldes:transactionFinalizedPathldes:transactionPathldes:versionCreateObjectldes:versionCreatePathldes:versionDeleteObjectldes:versionDeletePathldes:versionUpdateObjectldes:versionUpdatePathtree:viewDescriptiontree:viewDescriptiontree:viewDescriptionldes:retentionPolicytree:relationtree:nodetree:viewtree:shapetree:viewDescription \ No newline at end of file From 7c6993ccbf724d5116bafc02eb7240a847a7cf3b Mon Sep 17 00:00:00 2001 From: ValyVanDenBroeck Date: Wed, 29 Oct 2025 23:34:39 +0100 Subject: [PATCH 5/5] Comments Emidio --- context.jsonld | 4 ++-- eventstreams.bs | 2 +- server-primer.bs | 8 ++++---- vocabulary.bs | 6 +++--- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/context.jsonld b/context.jsonld index eedcca1..fa377f7 100644 --- a/context.jsonld +++ b/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"}, diff --git a/eventstreams.bs b/eventstreams.bs index ada0e39..60f80f4 100644 --- a/eventstreams.bs +++ b/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. diff --git a/server-primer.bs b/server-primer.bs index e186b5a..adee00d 100644 --- a/server-primer.bs +++ b/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: . @prefix tree: . -@prefix dcterms: . +@prefix dct: . @prefix xsd: . <> 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} diff --git a/vocabulary.bs b/vocabulary.bs index 43f6863..f143ee0 100644 --- a/vocabulary.bs +++ b/vocabulary.bs @@ -29,11 +29,11 @@ There is also a [Turtle version available](https://w3id.org/ldes.ttl). Used prefixes are: ```turtle -@prefix ldes: . -@prefix tree: . @prefix dct: . +@prefix ldes: . @prefix rdf: . @prefix rdfs: . +@prefix tree: . @prefix xsd: . ``` @@ -105,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}