Adds a feature of dimension anotations #202
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| "cube-link": patch | ||
| --- | ||
|
|
||
| Adding dimension annotations (`meta:annotation`) re https://gitlab.ldbar.ch/bafu/visualize/-/issues/542 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
|
There was a problem hiding this comment. @tpluscode it would be helpful for the reader to explicitly state lower limit values and upper limit values 😉 as there are also situations where only one sort occurs and this information is needed to check and display whether the values are within the acceptable range. There was a problem hiding this comment. Good catch. We seem to have dropped that along the way - or at least I think we had that covered once. Or would you see a case where a LIMIT could no specified to be an upper or lowr Limit @Rdataflow ? It would not really be a limit without that specification? There was a problem hiding this comment. After a small chat with @Rdataflow, we both agree that the generic One thing we should distinguish is between the mathematical concept of a limit (or limes) and limit as we envisioned here. Here, we think about something like a speed limit. Or some value, which should not be exceeded (or exceedence leads to some consequence), or below which a measurement can't be quantified like a detection limit. We would argue, that these kinds of limits do generally have an upper or lower meaning associated with them. So the use of Edit: wrote There was a problem hiding this comment. @Kronmar-Bafu I do not follow, which part is in your opinion missing from the spec? The snippet shows |
||
|
|
||
| ## 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 | ||
tpluscode marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| 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/). | ||
|
Comment on lines
+135
to
+136
There was a problem hiding this comment. I could not find a simple enough way to include this in the validation shape |
||
|
|
||
| <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> | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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> ; | ||
|
There was a problem hiding this comment. That's a test cases which should fail There was a problem hiding this comment. ah, I see, to check they are not accepted :-) There was a problem hiding this comment. I tried to make this even more accurate but I seem to have hit a limitation of shat SHACL can do when there are multiple properties with same value. I failed to make a validation to catch for example sh:minInclusive <https://ld.admin.ch/time/year/2020>
sh:minExclusive <https://ld.admin.ch/time/year/2020> |
||
| sh:minExclusive <https://ld.admin.ch/time/year/2022> ; | ||
| ] ; | ||
| ] ; | ||
| ] ; | ||
| sh:property | ||
| [ | ||
| a meta:KeyDimension ; | ||
tpluscode marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| sh:path <year> ; | ||
| schema:name "year" ; | ||
| sh:minCount 1 ; | ||
| sh:maxCount 1 ; | ||
| sh:nodeKind sh:IRI ; | ||
| ] ; | ||
| sh:property | ||
| [ | ||
| a meta:KeyDimension ; | ||
tpluscode marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| sh:path <station> ; | ||
| schema:name "station" ; | ||
| sh:minCount 1 ; | ||
| sh:maxCount 1 ; | ||
| sh:nodeKind sh:IRI ; | ||
| ] ; | ||
| . | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 . |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 ; | ||
tpluscode marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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 ; | ||
| ] ; | ||
| . | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 ; | ||
| ] | ||
| ) . |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Here, this part,
schema:valueis too generic. Do we mean a lower or an upper limit?We can avoid this confusion in at least three ways I could think of:
meta:UpperLimitandmeta:LowerLimitmeta:limitType "upper"or something like thatschema:valueby something more precise, like aschema:maxValuefor an upper limit or aschema:minValuefor a lower limit.I would advocate together with Thomas for option three, as it reuses
schema:maxValue/schema:minValueinstead of introducing new things.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ok, I think I understood now.
Let me clarify one more point. Would it ever make sense to have both
schema:minValueandschema:maxValueon a limit. From what you write, I guess that is pointless?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Depends on how you want to look at it.
It could be, that something is supposed to follow an upper and a lower limit. One could then add a
schema:minValueas well as aschema:maxValueto the samemeta:Limit. Or be more precise and add twometa:Limit.From a semantic's point it might be clearer to add two
meta:Limitin such a case. So yes, there's not really a point to have both predicates for onemeta:Limit. Or would you like to disagree @Rdataflow ?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I just imagined the case of a target range, being specified by means of lower and upper limit. Yes, for such cases it could make sense to have both at the some node ;-)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Two thoughts:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Alright, you got me conviced. I was steering more towards thinking of target ranges as "two limits in a trenchcoat" and thus wanting to split them up. But that would just be more "wordy". So let's keep the possibility.
As for your second thought @l00mi , I agree. a
dcterms:titlewould make sense.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In principle, any property is allowed. The shapes aren't closed. Do you think it's worth mentioning that explicitly in the spec?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
#206
@Kronmar-Bafu @Rdataflow