Skip to content

Commit 53e8a9d

Browse files
zyzzyxdontazyzzyxdonta
committed
deploy: 1f6ac6f 
0 parents  commit 53e8a9d

185 files changed

Lines changed: 20097 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.buildinfo‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Sphinx build info version 1
2+
# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
3+
config: d1277b9cc8de3e89bb4ec1d2a4cb3c2a
4+
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎.nojekyll‎

Whitespace-only changes.

‎NOTES.html‎

Lines changed: 492 additions & 0 deletions
Large diffs are not rendered by default.

‎_sources/NOTES.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<!--
2+
SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Dresden - Rossendorf (HZDR)
3+
SPDX-License-Identifier: CC-BY-4.0
4+
SPDX-FileContributor: David Pape
5+
-->
6+
7+
# NOTES
8+
9+
```{todo}
10+
Remove this file after moving all info to the appropriate places.
11+
```
12+
13+
Notes from the research and development process.
14+
15+
## Resources
16+
17+
Specifications:
18+
19+
```{todo}
20+
Link these in the policies spec
21+
```
22+
23+
- [SHACL](https://www.w3.org/TR/shacl/)
24+
- [SHACL JavaScript Extensions](https://www.w3.org/TR/shacl-js/)
25+
26+
Implementations:
27+
28+
```{todo}
29+
These could be provided as extra information in an appendix.
30+
```
31+
32+
- [pySHACL](https://github.com/RDFLib/pySHACL)
33+
- ~~[shacl-js](https://github.com/TopQuadrant/shacl-js)~~ (unmaintained)
34+
- [rdf-validate-shacl](https://github.com/zazuko/rdf-validate-shacl)
35+
- [shacl-engine](https://github.com/rdf-ext/shacl-engine) (also JavaScript)
36+
37+
Other:
38+
39+
```{todo}
40+
Some of these might be good to put into the SHACL guide for policy writers.
41+
```
42+
43+
- [SHACL playground](https://shacl.org/playground/) (no SPARQL support)
44+
- [rdf-validate-shacl playground](https://shacl-playground.zazuko.com/)
45+
- [SHACL Play!](https://shacl-play.sparna.fr/play/)
46+
- [Book: Validating RDF Data](https://book.validatingrdf.com)
47+
48+
## pySHACL Usage
49+
50+
[pySHACL](https://github.com/RDFLib/pySHACL/) can be installed from PyPI:
51+
52+
```bash
53+
pip install 'pyshacl[js]'
54+
# or
55+
pipx install 'pyshacl[js]'
56+
```
57+
58+
It can be used to validate a data graph `data.ttl` against a SHACL shapes graph `shapes.ttl` like so:
59+
60+
```bash
61+
pyshacl --metashacl --imports --js -s shapes.ttl data.ttl
62+
```
63+
64+
The `--metashacl` flag validates the shapes graph, first.
65+
The `--imports` flag is required in order for pySHACL to resolve `owl:imports` properties.
66+
The `--js` flag enables JavaScript functionality.
67+
68+
pySHACL can also be used as a library.

‎_sources/appendices/ontology.md‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
<!--
2+
SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Dresden - Rossendorf (HZDR), Forschungszentrum Jülich (FZJ)
3+
SPDX-License-Identifier: CC-BY-4.0
4+
SPDX-FileContributor: David Pape
5+
SPDX-FileContributor: Oliver Bertuch
6+
-->
7+
8+
# Parameter Ontology & SHACL Shapes
9+
10+
```{todo}
11+
"Parameter Ontology" is quite the narrow scope.
12+
We should phrase this more vaguely to we don't need to change everything later, should we decide to add more concepts.
13+
```
14+
15+
```{todo}
16+
Put this as a file somewhere so that it can be embedded here, but downloaded by a client, too.
17+
```
18+
19+
```{todo}
20+
The formatting used in these code blocks is not supported by the code highlighter, causing warnings when compiling the documentation.
21+
See: <https://github.com/pygments/pygments/pull/2980>
22+
```
23+
24+
Formal OWL definition:
25+
26+
```{todo}
27+
There are loads of errors in this.
28+
```
29+
30+
```turtle
31+
@prefix owl: <http://www.w3.org/2002/07/owl#> .
32+
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
33+
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
34+
@prefix sc: <https://schema.software-metadata.pub/software-card/2025-01/#> .
35+
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
36+
37+
# ============================================================================
38+
# Software CaRD Parameter Ontology (OWL)
39+
# ============================================================================
40+
#
41+
# This file defines the semantic model for Software CaRD parameters using OWL.
42+
# It specifies:
43+
# - Class definitions and their relationships
44+
# - Property definitions with domains and ranges
45+
# - Basic cardinality constraints
46+
# - Enumerated sets of allowed values
47+
#
48+
# NOTE: This OWL ontology is complemented by a SHACL shapes file
49+
# (sc-parameter-shacl.ttl) that provides additional validation constraints
50+
# that cannot be expressed in OWL, such as:
51+
# - Minimum string length requirements
52+
# - Specific literal datatype enforcement
53+
# - Additional validation rules
54+
#
55+
# Both files work together to provide complete semantic definition and
56+
# validation for Software CaRD parameters.
57+
# ============================================================================
58+
59+
<https://schema.software-metadata.pub/software-card/2025-01/Parameter>
60+
a owl:Ontology ;
61+
rdfs:label "Software CaRD Parameter Ontology"@en ;
62+
rdfs:comment """OWL ontology defining the semantic model for configurable parameters
63+
in Software CaRD policies."""@en ;
64+
owl:versionInfo "0.1" ;
65+
rdfs:seeAlso <https://schema.software-metadata.pub/software-card/2025-01/Parameter> .
66+
67+
# Define allowed inner types as an enumerated class
68+
sc:AllowedInnerType a owl:Class ;
69+
rdfs:label "Allowed Inner Type"@en ;
70+
rdfs:comment """The set of datatypes that may be used as inner types for parameters.
71+
This includes common XSD datatypes for literals and rdfs:Resource for
72+
IRI references."""@en ;
73+
owl:oneOf (
74+
xsd:string
75+
xsd:boolean
76+
xsd:integer
77+
xsd:int
78+
xsd:decimal
79+
xsd:float
80+
xsd:double
81+
xsd:anyURI
82+
rdfs:Resource
83+
) ;
84+
rdfs:isDefinedBy <https://schema.software-metadata.pub/software-card/2025-01/#> .
85+
86+
# Define allowed outer types as an enumerated class
87+
sc:AllowedOuterType a owl:Class ;
88+
rdfs:label "Allowed Outer Type"@en ;
89+
rdfs:comment """The set of container types that may be used as outer types for parameters.
90+
This includes scalar (single value), ordered lists, and unordered bags."""@en ;
91+
owl:oneOf ( sc:Scalar rdf:List ) ;
92+
rdfs:isDefinedBy <https://schema.software-metadata.pub/software-card/2025-01/#> .
93+
94+
# Class Definition with cardinality restrictions
95+
sc:Parameter a owl:Class ;
96+
rdfs:label "Parameter"@en ;
97+
rdfs:comment """A configurable placeholder in a Software CaRD policy that can be
98+
assigned different values through a configuration file. Parameters
99+
enable policy reuse across different contexts by allowing specific
100+
constraints to be customized without modifying the policy itself.
101+
102+
Each parameter must specify:
103+
- An outer type (container structure: scalar, list, or bag)
104+
- An inner type (datatype of values)
105+
- A configuration key (where to find the value in config)
106+
- A description (via rdfs:comment)
107+
- Optionally, a default value (if omitted, parameter is required)"""@en ;
108+
rdfs:subClassOf [
109+
a owl:Restriction ;
110+
owl:onProperty rdfs:comment ;
111+
owl:cardinality 1 ;
112+
rdfs:comment "Every parameter must have exactly one description."@en
113+
] ;
114+
rdfs:subClassOf [
115+
a owl:Restriction ;
116+
owl:onProperty sc:parameterOuterType ;
117+
owl:cardinality 1 ;
118+
rdfs:comment "Every parameter must have exactly one outer type."@en
119+
] ;
120+
rdfs:subClassOf [
121+
a owl:Restriction ;
122+
owl:onProperty sc:parameterInnerType ;
123+
owl:cardinality 1 ;
124+
rdfs:comment "Every parameter must have exactly one inner type."@en
125+
] ;
126+
rdfs:subClassOf [
127+
a owl:Restriction ;
128+
owl:onProperty sc:parameterConfigKey ;
129+
owl:cardinality 1 ;
130+
rdfs:comment "Every parameter must have exactly one configuration key."@en
131+
] ;
132+
rdfs:subClassOf [
133+
a owl:Restriction ;
134+
owl:onProperty sc:parameterDefaultValue ;
135+
owl:maxCardinality 1 ;
136+
rdfs:comment "A parameter may have at most one default value. If omitted, the parameter is required."@en
137+
] ;
138+
rdfs:isDefinedBy <https://schema.software-metadata.pub/software-card/2025-01/#> .
139+
140+
# Properties
141+
142+
sc:parameterOuterType a owl:ObjectProperty ;
143+
rdfs:label "parameter outer type"@en ;
144+
rdfs:comment """Specifies the container/cardinality type of the parameter value.
145+
Determines whether the parameter represents a single value (sc:Scalar),
146+
or a list of values (rdf:List)."""@en ;
147+
rdfs:domain sc:Parameter ;
148+
rdfs:range sc:AllowedOuterType ;
149+
rdfs:isDefinedBy <https://schema.software-metadata.pub/software-card/2025-01/#> .
150+
151+
sc:parameterInnerType a owl:ObjectProperty ;
152+
rdfs:label "parameter inner type"@en ;
153+
rdfs:comment """Specifies the datatype of the individual value(s) in the parameter.
154+
Must be one of the supported XSD datatypes or rdfs:Resource for IRI references."""@en ;
155+
rdfs:domain sc:Parameter ;
156+
rdfs:range sc:AllowedInnerType ;
157+
rdfs:isDefinedBy <https://schema.software-metadata.pub/software-card/2025-01/#> .
158+
159+
sc:parameterConfigKey a owl:DatatypeProperty ;
160+
rdfs:label "parameter configuration key"@en ;
161+
rdfs:comment """A string that identifies the configuration key for this parameter.
162+
Used to look up the configured value in the configuration file during
163+
parameter resolution. Must be a non-empty string."""@en ;
164+
rdfs:domain sc:Parameter ;
165+
rdfs:range xsd:string ;
166+
rdfs:isDefinedBy <https://schema.software-metadata.pub/software-card/2025-01/#> .
167+
168+
sc:parameterDefaultValue a rdf:Property ;
169+
rdfs:label "parameter default value"@en ;
170+
rdfs:comment """The value to use when no configured value is provided. If omitted, the
171+
parameter becomes required and must be provided in the configuration file.
172+
When present, the default value must match the parameter's declared outer
173+
and inner types. For scalar parameters, this is a single literal or resource.
174+
For list parameters, this is an rdf:List."""@en ;
175+
rdfs:domain sc:Parameter ;
176+
rdfs:isDefinedBy <https://schema.software-metadata.pub/software-card/2025-01/#> .
177+
178+
# Scalar Type Definition
179+
sc:Scalar a rdfs:Datatype ;
180+
rdfs:label "Scalar"@en ;
181+
rdfs:comment """Represents a single value (as opposed to a collection). Used as the
182+
outer type for parameters that accept exactly one value."""@en ;
183+
rdfs:isDefinedBy <https://schema.software-metadata.pub/software-card/2025-01/#> .
184+
```
185+
186+
Formal SHACL definition:
187+
188+
```{todo}
189+
There are loads of errors in this.
190+
```
191+
192+
```turtle
193+
@prefix owl: <http://www.w3.org/2002/07/owl#> .
194+
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
195+
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
196+
@prefix sc: <https://schema.software-metadata.pub/software-card/2025-01/#> .
197+
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
198+
@prefix sh: <http://www.w3.org/ns/shacl#> .
199+
200+
# ============================================================================
201+
# Software CaRD Parameter Validation Shapes (SHACL)
202+
# ============================================================================
203+
#
204+
# This file defines SHACL validation constraints for Software CaRD parameters.
205+
# It specifies detailed validation rules that complement the OWL ontology,
206+
# including:
207+
# - String length requirements
208+
# - Explicit datatype constraints on literals
209+
# - Value enumeration validation
210+
# - Additional structural constraints
211+
#
212+
# NOTE: This SHACL shapes file works together with the OWL ontology file
213+
# (sc-parameter-owl.ttl) to provide complete validation. The OWL file defines
214+
# the semantic model while this file provides detailed validation rules that
215+
# cannot be expressed in OWL alone.
216+
#
217+
# Use this file with a SHACL validator to check whether parameter definitions
218+
# conform to the Software CaRD specification.
219+
# ============================================================================
220+
221+
<https://schema.software-metadata.pub/software-card/2025-01/Parameter>
222+
a owl:Ontology ;
223+
rdfs:label "Software CaRD Parameter Validation Shapes"@en ;
224+
rdfs:comment """SHACL shapes for validating Software CaRD parameter definitions."""@en ;
225+
owl:versionInfo "0.1" ;
226+
owl:imports <https://schema.software-metadata.pub/software-card/2025-01/Parameter> ;
227+
rdfs:seeAlso <https://schema.software-metadata.pub/software-card/2025-01/Parameter> .
228+
229+
# Constraints expressed as SHACL shapes
230+
sc:ParameterShape a sh:NodeShape ;
231+
sh:targetClass sc:Parameter ;
232+
rdfs:label "Parameter Shape"@en ;
233+
rdfs:comment """SHACL shape defining validation constraints on sc:Parameter instances.
234+
This shape enforces structural and datatype requirements that complement
235+
the OWL ontology definition."""@en ;
236+
237+
# Must have exactly one outer type from allowed set
238+
sh:property [
239+
sh:path sc:parameterOuterType ;
240+
sh:name "Outer Type"@en ;
241+
sh:description "The container/cardinality type of the parameter."@en ;
242+
sh:minCount 1 ;
243+
sh:maxCount 1 ;
244+
sh:in ( sc:Scalar rdf:List ) ;
245+
sh:message "Parameter must have exactly one outer type: sc:Scalar, or rdf:List."@en ;
246+
] ;
247+
248+
# Must have exactly one inner type from allowed set
249+
sh:property [
250+
sh:path sc:parameterInnerType ;
251+
sh:name "Inner Type"@en ;
252+
sh:description "The datatype of the individual value(s)."@en ;
253+
sh:minCount 1 ;
254+
sh:maxCount 1 ;
255+
sh:in (
256+
xsd:string
257+
xsd:boolean
258+
xsd:integer
259+
xsd:int
260+
xsd:decimal
261+
xsd:float
262+
xsd:double
263+
xsd:anyURI
264+
rdfs:Resource
265+
) ;
266+
sh:message "Parameter must have exactly one inner type from the supported list."@en ;
267+
] ;
268+
269+
# Must have exactly one non-empty config key
270+
sh:property [
271+
sh:path sc:parameterConfigKey ;
272+
sh:name "Configuration Key"@en ;
273+
sh:description "The key used to look up this parameter's value in the configuration file."@en ;
274+
sh:minCount 1 ;
275+
sh:maxCount 1 ;
276+
sh:datatype xsd:string ;
277+
sh:minLength 1 ;
278+
sh:message "Parameter must have exactly one non-empty configuration key string."@en ;
279+
] ;
280+
281+
# Must have exactly one description of sufficient length
282+
sh:property [
283+
sh:path rdfs:comment ;
284+
sh:name "Description"@en ;
285+
sh:description "Human-readable description of the parameter's purpose and usage."@en ;
286+
sh:minCount 1 ;
287+
sh:maxCount 1 ;
288+
sh:datatype xsd:string ;
289+
sh:minLength 10 ;
290+
sh:message "Parameter must have exactly one rdfs:comment description of at least 10 characters."@en ;
291+
] ;
292+
293+
# May have at most one default value (optional - if omitted, parameter is required)
294+
sh:property [
295+
sh:path sc:parameterDefaultValue ;
296+
sh:name "Default Value"@en ;
297+
sh:description "Optional default value used when no configured value is provided."@en ;
298+
sh:maxCount 1 ;
299+
sh:message "Parameter may have at most one default value. If omitted, the parameter is required."@en ;
300+
] ;
301+
302+
rdfs:isDefinedBy <https://schema.software-metadata.pub/software-card/2025-01/#> .
303+
```

0 commit comments

Comments
 (0)
⚡