Merge pull request #220 from okp4/refactor/semantic-versioning-uris

Refactor/semantic versioning uris

.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish
+"on":
+  push:
+    branches:
+      - main
+    tags:
+      - v*
+concurrency:
+  group: "publish-${{ github.ref }}"
+  cancel-in-progress: true
+jobs:
+  publish-gh-pages:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+
+      - name: Bump version to next (if not tagged)
+        if: "startsWith(github.ref, 'refs/heads/')"
+        run: |
+          echo next > version
+
+      - name: Build documentation
+        run: |
+          make build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.OKP4_TOKEN }}
+          publish_dir: target/ontology/
+          destination_dir: .
+          keep_files: true
+          cname: ontology.okp4.space

.releaserc.yml

@@ -9,20 +9,31 @@ plugins:
   - - "@semantic-release/changelog"
     - changelogFile: CHANGELOG.md
       changelogTitle: "# OKP4 Ontology Changelog"
+  - - "@google/semantic-release-replace-plugin"
+    - replacements:
+        - files: [version]
+          from: ^.+$
+          to: ${nextRelease.version}
+          countMatches: true
+          results:
+            - file: version
+              hasChanged: true
+              numMatches: 1
+              numReplacements: 1
   - - "@semantic-release/exec"
     - prepareCmd: make build
   - - "@semantic-release/github"
     - assets:
         - label: OKP4 Ontology (JSON-LD)
-          path: ./target/okp4-ontology.jsonld
+          path: ./target/okp4-ontology-*.jsonld
         - label: OKP4 Ontology (Turtle)
-          path: ./target/okp4-ontology.ttl
+          path: ./target/okp4-ontology-*.ttl
         - label: OKP4 Ontology (RDF/XML)
-          path: ./target/okp4-ontology.rdf
+          path: ./target/okp4-ontology-*.rdf
         - label: OKP4 Ontology (N-Triples)
-          path: ./target/okp4-ontology.nt
+          path: ./target/okp4-ontology-*.nt
         - label: OKP4 Ontology Bundle
-          path: ./target/okp4-ontology-bundle.tar.gz
+          path: ./target/okp4-ontology-*-bundle.tar.gz
   - - "@semantic-release/git"
     - assets:
         - CHANGELOG.md

Makefile

@@ -30,10 +30,17 @@ COLOR_YELLOW := $(shell tput -Txterm setaf 3)
 # Build constants
 ROOT               := .
 
+# - Version constants
+VERSION 	  := $(shell cat version)
+VERSION_MAJOR := $(word 1,$(subst ., ,$(VERSION)))
+VERSION_MINOR := $(word 2,$(subst ., ,$(VERSION)))
+VERSION_PATCH := $(word 3,$(subst ., ,$(VERSION)))
+
+# - Destination directories
 DST                := $(ROOT)/target
 DST_CACHE          := $(DST)/.cache
 DST_MAKE           := $(DST)/.make
-DST_ONT            := $(DST)/ontology
+DST_ONT            := $(DST)/ontology/v$(VERSION_MAJOR)
 DST_FORMAT         := $(DST_MAKE)/format
 DST_LINT           := $(DST_MAKE)/lint
 DST_TEST           := $(DST_MAKE)/test
@@ -47,11 +54,11 @@ OBJ_ONTS_RDFXML    := $(patsubst $(SRC_ONT)/%.ttl,$(DST_ONT)/%.rdf.xml,$(SRC_ONT
 OBJ_ONTS_JSONLD    := $(patsubst $(SRC_ONT)/%.ttl,$(DST_ONT)/%.jsonld,$(SRC_ONTS))
 
 OKP4_ARTIFACT_ID   := okp4-ontology
-BIN_OKP4_TTL       := $(DST)/$(OKP4_ARTIFACT_ID).ttl
-BIN_OKP4_NT        := $(DST)/$(OKP4_ARTIFACT_ID).nt
-BIN_OKP4_RDFXML    := $(DST)/$(OKP4_ARTIFACT_ID).rdf.xml
-BIN_OKP4_JSONLD    := $(DST)/$(OKP4_ARTIFACT_ID).jsonld
-BIN_OKP4_BUNDLE    := $(DST)/$(OKP4_ARTIFACT_ID)-bundle.tar.gz
+BIN_OKP4_TTL       := $(DST)/$(OKP4_ARTIFACT_ID)-$(VERSION).ttl
+BIN_OKP4_NT        := $(DST)/$(OKP4_ARTIFACT_ID)-$(VERSION).nt
+BIN_OKP4_RDFXML    := $(DST)/$(OKP4_ARTIFACT_ID)-$(VERSION).rdf.xml
+BIN_OKP4_JSONLD    := $(DST)/$(OKP4_ARTIFACT_ID)-$(VERSION).jsonld
+BIN_OKP4_BUNDLE    := $(DST)/$(OKP4_ARTIFACT_ID)-$(VERSION)-bundle.tar.gz
 
 # - Format
 FLG_FMT_TTLS       := $(patsubst $(SRC_ONT)/%.ttl,$(DST_FORMAT)/%.formatted,$(SRC_ONTS))
@@ -64,6 +71,9 @@ SRC_TST            := $(ROOT)/test
 SRC_TSTS           := $(shell find $(SRC_TST) -name "*.ttl" | sort)
 FLG_TSTS           := $(patsubst $(SRC_TST)/%.ttl,$(DST_TEST)/%.tested,$(SRC_TSTS))
 
+# - Permission mode
+PERMISSION_MODE := 767
+
 # sed -i support
 SED_FLAG=
 SHELL_NAME := $(shell uname -s)
@@ -136,23 +146,24 @@ build-ontology-jsonld: check $(DST) $(OBJ_ONTS_JSONLD) $(BIN_OKP4_JSONLD) ## Bui
 
 $(OBJ_ONTS_TTL): $(DST_ONT)/%.ttl: $(SRC_ONT)/%.ttl
 	@echo "${COLOR_CYAN}🔨 building${COLOR_RESET} ontology ${COLOR_GREEN}$@${COLOR_RESET}"
-	@mkdir -p -m 777 $(@D)
+	@mkdir -p -m $(PERMISSION_MODE) $(@D)
 	@cp $< $@
+	@sed -i ${SED_FLAG} "s/\$$major/$(VERSION_MAJOR)/g" $@
 
 $(OBJ_ONTS_NT): $(DST_ONT)/%.nt: $(DST_ONT)/%.ttl
 	@echo "${COLOR_CYAN}🔨 building${COLOR_RESET} ontology ${COLOR_GREEN}$@${COLOR_RESET}"
-	@mkdir -p -m 777 $(@D)
+	@mkdir -p -m $(PERMISSION_MODE) $(@D)
 	@${call RDF_SERIALIZE,turtle,ntriples,$<,$@}
 	@${call NT_UNIQUIFY,$@}
 
 $(OBJ_ONTS_RDFXML): $(DST_ONT)/%.rdf.xml: $(DST_ONT)/%.ttl
 	@echo "${COLOR_CYAN}🔨 building${COLOR_RESET} ontology ${COLOR_GREEN}$@${COLOR_RESET}"
-	@mkdir -p -m 777 $(@D)
+	@mkdir -p -m $(PERMISSION_MODE) $(@D)
 	@${call RDF_SERIALIZE,turtle,rdfxml,$<,$@}
 
 $(OBJ_ONTS_JSONLD): $(DST_ONT)/%.jsonld: $(DST_ONT)/%.ttl
 	@echo "${COLOR_CYAN}🔨 building${COLOR_RESET} ontology ${COLOR_GREEN}$@${COLOR_RESET}"
-	@mkdir -p -m 777 $(@D)
+	@mkdir -p -m $(PERMISSION_MODE) $(@D)
 	@${call RDF_SERIALIZE,turtle,jsonld,$<,$@}
 
 $(BIN_OKP4_NT): $(OBJ_ONTS_NT)
@@ -181,7 +192,7 @@ $(BIN_OKP4_BUNDLE): $(shell test -d $(DST_ONT) && find $(DST_ONT) -type f -name
 	@echo "${COLOR_CYAN}📦 making${COLOR_RESET} ontology ${COLOR_GREEN}$@${COLOR_RESET} tarball"
 	@tar -cvzf $(BIN_OKP4_BUNDLE) \
 	  -C $(abspath $(ROOT)) LICENSE \
-	  -C $(abspath $(DST)) $(shell cd $(DST) ; echo $(OKP4_ARTIFACT_ID).*) \
+	  -C $(abspath $(DST)) $(shell cd $(DST) ; echo $(OKP4_ARTIFACT_ID)-$(VERSION).*) \
 	  -C $(abspath $(DST_ONT)) $(shell cd $(DST_ONT) ; echo *)
 	@echo "${COLOR_CYAN}📊 tarball ${COLOR_GREEN}statistics${COLOR_RESET}"
 	@echo "${COLOR_CYAN}   ↳ 🗃️ number of files${COLOR_RESET}: ${COLOR_GREEN}$$(tar -tzf $(BIN_OKP4_BUNDLE) | wc -l | bc)${COLOR_RESET}"
@@ -196,7 +207,7 @@ format-ttl: check cache $(FLG_FMT_TTLS) ## Format all Turtle files
 
 $(FLG_FMT_TTLS): $(DST_FORMAT)/%.formatted: $(SRC_ONT)/%.ttl
 	@echo "${COLOR_CYAN}📐 formating: ${COLOR_GREEN}$<${COLOR_RESET}"
-	@mkdir -p -m 777 $(@D)
+	@mkdir -p -m $(PERMISSION_MODE) $(@D)
 	@${call RDF_WRITE,turtle,$<,"$<.formatted"}
 	@mv -f "$<.formatted" $<
 	@touch $@
@@ -210,7 +221,7 @@ lint-ttl: check cache $(FLG_LINT_TTLS) ## Lint all Turtle files
 
 $(FLG_LINT_TTLS): $(DST_LINT)/%.linted: $(SRC_ONT)/%.ttl
 	@echo "${COLOR_CYAN}🔬 linting: ${COLOR_GREEN}$<${COLOR_RESET}"
-	@mkdir -p -m 777 $(@D)
+	@mkdir -p -m $(PERMISSION_MODE) $(@D)
 	@docker run --rm \
       -v `pwd`:/usr/src/ontology:ro \
       -w /usr/src/ontology \
@@ -226,7 +237,7 @@ test-ontology: check build-ontology-nt $(FLG_TSTS) ## Test the ontology
 
 $(FLG_TSTS): $(DST_TEST)/%.tested: $(SRC_TST)/%.ttl $(wildcard $(DST_ONT)/*.ttl)
 	@echo "${COLOR_CYAN}🧪 test: ${COLOR_GREEN}$<${COLOR_RESET}"
-	@mkdir -p -m 777 $(@D)
+	mkdir -p -m $(PERMISSION_MODE) $(@D)
 	@bash -c '\
 		for target in $(BIN_OKP4_NT); do \
 			$(call RDF_SHACL,$<,$$target,$@) \
@@ -291,7 +302,7 @@ cache: $(DST_CACHE)/$(EXEC_OWL_CLI) ## Download all required files to cache
 
 $(DST_CACHE)/$(EXEC_OWL_CLI):
 	@echo "${COLOR_CYAN}⤵️ downlading ${COLOR_GREEN}$(notdir $@)${COLOR_RESET}"
-	@mkdir -p -m 777 $(DST_CACHE); \
+	@mkdir -p -m $(PERMISSION_MODE) $(DST_CACHE); \
     cd $(DST_CACHE); \
     wget https://github.com/atextor/owl-cli/releases/download/v$(VERSION_OWL_CLI)/$(EXEC_OWL_CLI)
 
@@ -308,12 +319,16 @@ $(FLG_CHECK_OK):
 			echo "${COLOR_CYAN}✅ ${COLOR_GREEN}$$cmd${COLOR_RESET} ($$path)"; \
 		fi \
 	done
-	@mkdir -p -m 777 $(@D)
+	@mkdir -p -m $(PERMISSION_MODE) $(@D)
 	@touch $(FLG_CHECK_OK)
 
 $(DST):
 	@echo "${COLOR_CYAN}📂 creating ${COLOR_GREEN}$@${COLOR_RESET}"
-	@mkdir -p -m 777 $(DST)
+	@mkdir -p -m $(PERMISSION_MODE) $(DST)
+
+.PHONY: version
+version: ## Show the current version
+	@echo "${COLOR_CYAN}📦 version: ${COLOR_GREEN}${VERSION}${COLOR_RESET}"
 
 ## Help:
 .PHONY: vars

README.md

@@ -78,6 +78,21 @@ At the root, the ontology is divided into two main parts:
 
 The foundational philosophy underpinning the ontology of the [OKP4 protocol](https://okp4.network) is grounded in the *Open World* principle. This principle operates on the premise that knowledge is not static or finite; rather, it acknowledges that understanding and information can continuously evolve and expand. In practical terms, this means that the ontology is not confined to a predefined or limited set of schemas and thesauri. Instead, it is inherently designed to accommodate and integrate new and diverse contributions.
 
+### Ontology versioning
+
+In managing [RDF](https://www.w3.org/RDF/) resources, it is essential to balance the stability of URIs with the stability of their referenced content:
+
+- _URI Stability_: URIs must remain constant over time. This ensures that each URI consistently references the same resource, providing a reliable point of reference in web-based knowledge systems.
+- _Content Stability_: The content accessed via these URIs should be stable and avoid introducing breaking changes. This stability is crucial for 3rd party systems referencing these URIs, ensuring that their interactions remain consistent.
+
+The OKP4 ontology adopts the [Semantic Versioning](https://semver.org/) format of `MAJOR.MINOR.PATCH`. This approach includes incorporating the `MAJOR` version number into the ontology's URI. As a result, the structure of the ontology's URI is:
+
+```text
+https://w3id.org/okp4/ontology/<MAJOR>/<path>
+```
+
+Note: by including only the `MAJOR` version number in the URI, significant updates that could impact compatibility gives a new ontology version being referenced with a different namespace. `MINOR` updates and `PATCH` (which do not result in breaking changes) have no impact on the URI, maintaining the stability of the URI for external references.
+
 ## Development
 
 ### Building the ontology
@@ -99,11 +114,11 @@ This will build the `okp4` ontology under the `target` directory. The files gene
 
 ```text
 ./target
-   ├── okp4-ontology.nt
-   ├── okp4-ontology.rdf.xml
-   ├── okp4-ontology.jsonld
-   ├── okp4-ontology.ttl
-   └── okp4-ontology-bundle.tar.gz
+   ├── okp4-ontology-<version>.nt
+   ├── okp4-ontology-<version>.rdf.xml
+   ├── okp4-ontology-<version>.jsonld
+   ├── okp4-ontology-<version>.ttl
+   └── okp4-ontology-<version>-bundle.tar.gz
 ```
 
 ### Deploying the ontology in local triple store
@@ -182,6 +197,7 @@ Targets:
   Misc:
     cache                 Download all required files to cache
     check                 Check if all required commands are available in the system
+    version               Show the current version
   Help:
     vars                  Show relevant variables used in this Makefile
     help                  Show this help.

src/schema/digital-resource/credential-dataset-description.ttl

@@ -1,9 +1,9 @@
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix : <https://w3id.org/okp4/ontology/schema/credential/digital-resource/dataset/description/> .
+@prefix : <https://w3id.org/okp4/ontology/v$major/schema/credential/digital-resource/dataset/description/> .
 @prefix schema: <http://schema.org/> .
-@prefix thesaurus: <https://w3id.org/okp4/ontology/thesaurus/> .
+@prefix thesaurus: <https://w3id.org/okp4/ontology/v$major/thesaurus/> .
 
 :DatasetDescriptionCredential a rdfs:Class ;
   rdfs:label "Service Description Credential"@en ;

src/schema/digital-resource/credential-digital-resource-declaration.ttl

@@ -1,7 +1,7 @@
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix : <https://w3id.org/okp4/ontology/schema/credential/digital-resource/declaration/> .
+@prefix : <https://w3id.org/okp4/ontology/v$major/schema/credential/digital-resource/declaration/> .
 @prefix schema: <http://schema.org/> .
 
 :DigitalResourceDeclarationCredential a rdfs:Class ;

src/schema/digital-resource/credential-digital-resource-rights.ttl

@@ -1,6 +1,6 @@
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
-@prefix : <https://w3id.org/okp4/ontology/schema/credential/digital-resource/rights/> .
+@prefix : <https://w3id.org/okp4/ontology/v$major/schema/credential/digital-resource/rights/> .
 @prefix schema: <http://schema.org/> .
 
 :DigitalResourceRightsCredentials a rdfs:Class ;
@@ -29,7 +29,7 @@
   rdfs:label "has license"@en ;
   rdfs:comment "The licensing terms under which the Digital Resource is made available."@en ;
   schema:domainIncludes :DigitalResourceRightsCredentials ;
-  schema:rangeIncludes <https://w3id.org/okp4/ontology/thesaurus/license> .
+  schema:rangeIncludes <https://w3id.org/okp4/ontology/v$major/thesaurus/license> .
 
 :hasPublisher a rdf:Property ;
   rdfs:label "has publisher"@en ;

src/schema/digital-service/credential-digital-service-declaration.ttl

@@ -1,7 +1,7 @@
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix : <https://w3id.org/okp4/ontology/schema/credential/digital-service/declaration/> .
+@prefix : <https://w3id.org/okp4/ontology/v$major/schema/credential/digital-service/declaration/> .
 @prefix schema: <http://schema.org/> .
 
 :DigitalServiceDeclarationCredential a rdfs:Class ;

src/schema/digital-service/credential-digital-service-description.ttl

@@ -1,9 +1,9 @@
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix : <https://w3id.org/okp4/ontology/schema/credential/digital-service/description/> .
+@prefix : <https://w3id.org/okp4/ontology/v$major/schema/credential/digital-service/description/> .
 @prefix schema: <http://schema.org/> .
-@prefix thesaurus: <https://w3id.org/okp4/ontology/thesaurus/> .
+@prefix thesaurus: <https://w3id.org/okp4/ontology/v$major/thesaurus/> .
 
 :DigitalServiceDescriptionCredential a rdfs:Class ;
   rdfs:label "Digital Service Description Credential"@en ;

src/schema/digital-service/credential-digital-service-execution-order.ttl

@@ -1,7 +1,7 @@
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix : <https://w3id.org/okp4/ontology/schema/credential/digital-service/execution-order/> .
+@prefix : <https://w3id.org/okp4/ontology/v$major/schema/credential/digital-service/execution-order/> .
 @prefix schema: <http://schema.org/> .
 
 :DigitalServiceExecutionOrder a rdfs:Class ;

src/schema/digital-service/credential-digital-service-execution-result.ttl

@@ -1,7 +1,7 @@
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix : <https://w3id.org/okp4/ontology/schema/credential/digital-service/execution-proof/> .
+@prefix : <https://w3id.org/okp4/ontology/v$major/schema/credential/digital-service/execution-proof/> .
 @prefix schema: <http://schema.org/> .
 
 :DigitalServiceExecutionResult a rdfs:Class ;
@@ -30,7 +30,7 @@
   Indicates the status of the service execution.
   """@en ;
   schema:domainIncludes :DigitalServiceExecutionResultCredential ;
-  schema:rangeIncludes <https://w3id.org/okp4/ontology/thesaurus/digital-service-execution-status> .
+  schema:rangeIncludes <https://w3id.org/okp4/ontology/v$major/thesaurus/digital-service-execution-status> .
 
 :hasExecutionTime a rdf:Property ;
   rdfs:label "has execution time"@en ;

src/schema/governance/credential-governance-text.ttl

@@ -1,7 +1,7 @@
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix : <https://w3id.org/okp4/ontology/schema/credential/governance/text/> .
+@prefix : <https://w3id.org/okp4/ontology/v$major/schema/credential/governance/text/> .
 @prefix schema: <http://schema.org/> .
 
 :Article a rdfs:Class ;

src/schema/zone/credential-zone-declaration.ttl

@@ -1,6 +1,6 @@
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
-@prefix : <https://w3id.org/okp4/ontology/schema/credential/zone/declaration/> .
+@prefix : <https://w3id.org/okp4/ontology/v$major/schema/credential/zone/declaration/> .
 
 :ZoneDeclarationCredential a rdfs:Class ;
   rdfs:label "Zone Credential"@en ;

src/schema/zone/credential-zone-description.ttl

@@ -1,9 +1,9 @@
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix : <https://w3id.org/okp4/ontology/schema/credential/digital-resource/zone/description/> .
+@prefix : <https://w3id.org/okp4/ontology/v$major/schema/credential/digital-resource/zone/description/> .
 @prefix schema: <http://schema.org/> .
-@prefix thesaurus: <https://w3id.org/okp4/ontology/thesaurus/> .
+@prefix thesaurus: <https://w3id.org/okp4/ontology/v$major/thesaurus/> .
 
 :ZoneDescriptionCredential a rdfs:Class ;
   rdfs:label "Zone Description Credential"@en ;