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/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/uml.puml b/uml.puml new file mode 100644 index 0000000..168abbb --- /dev/null +++ b/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 diff --git a/uml.svg b/uml.svg new file mode 100644 index 0000000..6506581 --- /dev/null +++ b/uml.svg @@ -0,0 +1 @@ +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 diff --git a/vocabulary.bs b/vocabulary.bs index 64d9889..f143ee0 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:`. @@ -24,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: . ``` @@ -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}