Merge pull request #202 from zazuko/targets-limits

Adds a feature of dimension anotations
zazuko · Oct 1, 2024 · a6ae0bc · a6ae0bc
2 parents 2a93676 + a3575ad
commit a6ae0bc
Show file tree

Hide file tree

Showing 13 changed files with 757 additions and 3 deletions.
diff --git a/.changeset/thick-papayas-turn.md b/.changeset/thick-papayas-turn.md
@@ -0,0 +1,5 @@
+---
+"cube-link": patch
+---
+
+Adding dimension annotations (`meta:annotation`) re https://gitlab.ldbar.ch/bafu/visualize/-/issues/542
diff --git a/meta/core.md b/meta/core.md
@@ -27,6 +27,34 @@ To be able to distinguish Dimensions that are defined inside a Cube from Dimensi
 
 </aside>
 
+### meta:Limit {#Limit}
+
+A type of [annotation](#annotation) which can be used to express a limit or target value for a dimension.
+
+<aside class='example' title='Dimension with a target'>
+
+```turtle
+<cube/shape> sh:property [
+  a cube:KeyDimension ;  
+  sh:path ex:year ;
+] , [
+  a cube:MeasureDimension ;
+  meta:annotation [
+    a meta:Limit ;
+    schema:value 95 ;
+    schema:name "Target 2020" ;
+    meta:annotationContext [
+      sh:path ex:year ;
+      sh:hasValue <https://schema.ld.admin.ch/year/2020> ;
+    ] ;
+  ] ;
+] .
+```
+
+</aside>
+
+`schema:minValue` and `schema:maxValue` can be used to express a range of limit values.
+
 ## Properties
 
 ### meta:dataKind (temporal / spatial) {#dataKind}
@@ -84,3 +112,48 @@ With `meta:nextInHierarchy` the next lower level is attached to the higher level
 
 This property is used on a Dimension Constraint to express a relation with other properties through a [meta:Relation](#Relation) instance, the nature of this relationship is determined by the properties used on the instance. 
 See [this example](../#relexample).
+
+### meta:annotation {#annotation}
+
+This property is used to add additional information to a dimension.
+
+### meta:annotationContext {#annotationContext}
+
+Links to dimension values to which the annotation applies.
+The objects of `meta:annotationContext` MUST be well-formed [Property Shapes](https://www.w3.org/TR/shacl/#property-shapes).
+The value of their `sh:path` MUST be an IRI of a cube's key dimension.
+Only a subset of SHACL Constraints are supported which defined which observations that the annotation
+applies to, namely:
+
+1. `sh:hasValue` - to select specific observation value
+2. `sh:in` - to select multiple observation values
+2. `sh:minInclusive` - to select values greater or equal to a specific value
+3. `sh:maxInclusive` - to select values smaller or equal to a specific value
+4. `sh:minExclusive` - to select values greater than a specific value
+5. `sh:maxExclusive` - to select values smaller than a specific value
+
+In case of temporal dimensions, the constraint values are expected to be literals with datatypes `xsd:date`,
+`xsd:dateTime` or `xsd:gYear`, or the IRIs of [temporal entities](https://lindas.admin.ch/governance/core-entities/).
+
+<aside class='example' title='Dimension with a continuous limit on a temporal dimension'>
+
+```turtle
+<cube/shape> sh:property [
+  a cube:KeyDimension ;  
+  sh:path ex:year ;
+] , [
+  a cube:MeasureDimension ;
+  meta:annotation [
+    a meta:Limit ;
+    schema:value 95 ;
+    schema:name "Target 2020" ;
+    meta:annotationContext [
+      sh:path ex:year ;
+      sh:minInclusive "2020-01-01"^^xsd:date ;
+      sh:maxInclusive "2020-12-31"^^xsd:date ;
+    ] ;
+  ] ;
+] .
+```
+
+</aside>
diff --git a/test/standalone-constraint-constraint/invalid.annotation-invalidRanges.ttl b/test/standalone-constraint-constraint/invalid.annotation-invalidRanges.ttl
@@ -0,0 +1,81 @@
+PREFIX ex: <http://example.org/>
+PREFIX dcterms: <http://purl.org/dc/terms/>
+@prefix relation: <https://cube.link/relation/> .
+@prefix meta: <https://cube.link/meta/> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix cube: <https://cube.link/> .
+@prefix observation: <https://environment.ld.admin.ch/foen/nfi/observation/max_min_undefined> .
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix schema: <http://schema.org/> .
+@base <https://example.org/> .
+
+<cube> a cube:Cube ;
+    cube:observationConstraint <shape> ;
+    cube:observationSet <observationSet> .
+
+<observationSet> cube:observation <observationA> .
+
+<observationA> a cube:Observation ;
+    cube:observedBy <observer> ;
+    <measure> 4.9 ;
+    <year> <https://ld.admin.ch/time/year/2020> ;
+.
+
+<shape> a cube:Constraint ;
+    sh:targetClass cube:Observation ;
+    sh:closed true ;
+    sh:property
+        [
+            sh:path rdf:type ;
+            sh:nodeKind sh:IRI ;
+            sh:minCount 1 ;
+            sh:maxCount 1
+        ] ;
+    sh:property
+        [
+            sh:path cube:observedBy ; ;
+            sh:nodeKind sh:IRI ;
+            sh:minCount 1 ;
+            sh:maxCount 1
+        ] ;
+    sh:property
+        [
+            a cube:MeasureDimension ;
+            sh:datatype xsd:decimal ;
+            sh:path <measure> ;
+            schema:name "measure" ;
+            sh:minCount 1 ;
+            sh:maxCount 1 ;
+            meta:annotation
+                [
+                    a meta:Limit ;
+                    schema:value 97 ;
+                    schema:name "Target 2020+" ;
+                    meta:annotationContext
+                        [
+                            sh:path <year> ;
+                            sh:minInclusive <https://ld.admin.ch/time/year/2020> ;
+                            sh:minExclusive <https://ld.admin.ch/time/year/2022> ;
+                        ]  ;
+                ] ;
+        ] ;
+    sh:property
+        [
+            a meta:KeyDimension ;
+            sh:path <year> ;
+            schema:name "year" ;
+            sh:minCount 1 ;
+            sh:maxCount 1 ;
+            sh:nodeKind sh:IRI ;
+        ] ;
+    sh:property
+        [
+            a meta:KeyDimension ;
+            sh:path <station> ;
+            schema:name "station" ;
+            sh:minCount 1 ;
+            sh:maxCount 1 ;
+            sh:nodeKind sh:IRI ;
+        ] ;
+.
diff --git a/test/standalone-constraint-constraint/invalid.annotation-invalidRanges.ttl.approved.txt b/test/standalone-constraint-constraint/invalid.annotation-invalidRanges.ttl.approved.txt
@@ -0,0 +1,18 @@
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@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 schema: <http://schema.org/> .
+@prefix cube: <https://cube.link/> .
+
+_:report a sh:ValidationReport ;
+	sh:result [
+		rdf:type sh:ValidationResult ;
+		sh:resultSeverity sh:Violation ;
+		sh:sourceConstraintComponent sh:XoneConstraintComponent ;
+		sh:sourceShape <https://cube.link/shape/standalone-constraint-constraint#AnnotationContext> ;
+		sh:focusNode _:b5 ;
+		sh:value _:b5 ;
+		sh:resultMessage "annotation context only allows constraints sh:hasValue, sh:in, sh:minInclusive, sh:maxInclusive, sh:minExclusive, sh:maxExclusive and they cannot be mixed" ;
+	] ;
+	sh:conforms false .
diff --git a/test/standalone-constraint-constraint/invalid.annotation-keyDimensions.ttl b/test/standalone-constraint-constraint/invalid.annotation-keyDimensions.ttl
@@ -0,0 +1,87 @@
+PREFIX ex: <http://example.org/>
+PREFIX dcterms: <http://purl.org/dc/terms/>
+@prefix relation: <https://cube.link/relation/> .
+@prefix meta: <https://cube.link/meta/> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix cube: <https://cube.link/> .
+@prefix observation: <https://environment.ld.admin.ch/foen/nfi/observation/max_min_undefined> .
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix schema: <http://schema.org/> .
+@base <https://example.org/> .
+
+<cube> a cube:Cube ;
+    cube:observationConstraint <shape> ;
+    cube:observationSet <observationSet> .
+
+<observationSet> cube:observation <observationA> .
+
+<observationA> a cube:Observation ;
+    cube:observedBy <observer> ;
+    <measure> 4.9 ;
+    <year> <https://ld.admin.ch/time/year/2020> ;
+.
+
+<shape> a cube:Constraint ;
+    sh:targetClass cube:Observation ;
+    sh:closed true ;
+    sh:property
+        [
+            sh:path rdf:type ;
+            sh:nodeKind sh:IRI ;
+            sh:minCount 1 ;
+            sh:maxCount 1
+        ] ;
+    sh:property
+        [
+            sh:path cube:observedBy ; ;
+            sh:nodeKind sh:IRI ;
+            sh:minCount 1 ;
+            sh:maxCount 1
+        ] ;
+    sh:property
+        [
+            a cube:MeasureDimension ;
+            sh:datatype xsd:decimal ;
+            sh:path <measure> ;
+            schema:name "measure" ;
+            sh:minCount 1 ;
+            sh:maxCount 1 ;
+            meta:annotation
+                [
+                    a meta:Limit ;
+                    schema:value 95 ;
+                    meta:annotationContext
+                        [
+                            sh:path <non-dimension> ;
+                            sh:hasValue 10 ;
+                        ] ;
+                ] ,
+                [
+                    a meta:Limit ;
+                    schema:value 95 ;
+                    meta:annotationContext
+                        [
+                            sh:path <station> ;
+                            sh:hasValue ex:Station ;
+                        ] ;
+                ] ;
+        ] ;
+    sh:property
+        [
+            a meta:KeyDimension ;
+            sh:path <year> ;
+            schema:name "year" ;
+            sh:minCount 1 ;
+            sh:maxCount 1 ;
+            sh:nodeKind sh:IRI ;
+        ] ;
+    sh:property
+        [
+            sh:path <station> ;
+            schema:name "station" ;
+            sh:minCount 1 ;
+            sh:maxCount 1 ;
+            sh:nodeKind sh:IRI ;
+        ] ;
+.
diff --git a/test/standalone-constraint-constraint/invalid.annotation-keyDimensions.ttl.approved.txt b/test/standalone-constraint-constraint/invalid.annotation-keyDimensions.ttl.approved.txt
@@ -0,0 +1,48 @@
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@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 schema: <http://schema.org/> .
+@prefix cube: <https://cube.link/> .
+
+_:report a sh:ValidationReport ;
+	sh:result [
+		rdf:type sh:ValidationResult ;
+		sh:resultSeverity sh:Violation ;
+		sh:sourceConstraintComponent sh:NotConstraintComponent ;
+		sh:sourceShape <https://cube.link/shape/standalone-constraint-constraint#AnnotationContextDimensionType> ;
+		sh:focusNode _:b5 ;
+		sh:value _:b5 ;
+		sh:resultMessage "annotation context must have exactly one sh:path which is cube's key dimension" ;
+	], [
+		rdf:type sh:ValidationResult ;
+		sh:resultSeverity sh:Violation ;
+		sh:sourceConstraintComponent sh:XoneConstraintComponent ;
+		sh:sourceShape [
+			sh:path _:b710 ;
+			sh:xone (
+				[
+					sh:class <https://cube.link/meta/KeyDimension> ;
+				]
+				[
+					sh:property [
+						sh:path [
+							sh:inversePath <https://cube.link/meta/annotationContext> ;
+						] ;
+						sh:minCount 1 ;
+					] ;
+				]
+			) ;
+		] ;
+		sh:focusNode _:b7 ;
+		sh:value _:b9 ;
+		sh:resultPath _:b710 ;
+	] ;
+	sh:conforms false .
+
+_:b710 rdf:first sh:path ;
+	rdf:rest (
+		[
+			sh:inversePath sh:path ;
+		]
+	) .