Skip to content

Commit 076465b

Browse files
jdsikajdsika
committed
feat(envited-x): add AttributeProvenance shape for metadata derivation tracking
Extend the envited-x base ontology with a formal mechanism to declare how individual metadata attributes were derived and which software agent (tool or LLM model) produced them. New OWL classes and properties: - envited-x:AttributeProvenance (subclass of prov:Activity) - envited-x:hasAttributeProvenance (on DomainSpecification) - envited-x:attributeName, derivationMethod, confidence, llmModel New SHACL shapes: - envited-x:AttributeProvenanceShape — validates provenance entries - envited-x:SoftwareAgentShape — validates tool identity (schema:name, gx:version, optional envited-x:llmModel) Derivation method enum: - extraction: directly parsed from source file - calculation: computed from multiple source values - rule-based-inference: heuristic/keyword-based mapping - llm-inference: LLM model generated the value - manual: human input (e.g. wizard) Reuses existing external vocabularies: - prov:SoftwareAgent, prov:wasAssociatedWith, prov:endedAtTime (W3C PROV-O) - schema:name (Schema.org) - gx:version (Gaia-X Trust Framework) Motivation: automated metadata enrichment tools (e.g. llm_enricher in sl-5-8-asset-tools) need a standardized way to declare which fields they filled and with what confidence, enabling downstream consumers to distinguish human-curated from machine-derived values. Signed-off-by: Carlo van Driesten <carlo.van-driesten@bmw.de>
1 parent 2dbcf5e commit 076465b

4 files changed

Lines changed: 181 additions & 0 deletions

File tree

‎artifacts/envited-x/PROPERTIES.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
```mermaid
66
classDiagram
7+
class Attribute_Provenance
78
class Class_definition_for_CodeArtifactBase
89
class Class_definition_for_CodeAsset
910
class Class_definition_for_Content
@@ -23,6 +24,7 @@ class Class_definition_for_SoftwareResourceBase
2324

2425
### Class Hierarchy
2526

27+
- Attribute Provenance (https://w3id.org/ascs-ev/envited-x/envited-x/v3/AttributeProvenance)
2628
- Class definition for CodeArtifactBase (https://w3id.org/ascs-ev/envited-x/envited-x/v3/CodeArtifactBase)
2729
- Class definition for CodeAsset (https://w3id.org/ascs-ev/envited-x/envited-x/v3/CodeAsset)
2830
- Class definition for Content (https://w3id.org/ascs-ev/envited-x/envited-x/v3/Content)
@@ -43,6 +45,7 @@ class Class_definition_for_SoftwareResourceBase
4345

4446
|Class|IRI|Description|Parents|
4547
|---|---|---|---|
48+
|Attribute Provenance|https://w3id.org/ascs-ev/envited-x/envited-x/v3/AttributeProvenance|Records the derivation method and responsible software agent for one or more metadata attributes that were automatically filled.|Activity|
4649
|Class definition for CodeArtifactBase|https://w3id.org/ascs-ev/envited-x/envited-x/v3/CodeArtifactBase|Base class coupling ENVITED-X code assets to gx:CodeArtifact.|CodeArtifact|
4750
|Class definition for CodeAsset|https://w3id.org/ascs-ev/envited-x/envited-x/v3/CodeAsset|A structured digital asset in the ENVITED-X Data Space representing a code artifact.
4851
Carries domain-specific metadata while delegating GX compliance
@@ -78,6 +81,7 @@ class Class_definition_for_SoftwareResourceBase
7881
- gx: <https://w3id.org/gaia-x/development#>
7982
- manifest: <https://w3id.org/ascs-ev/envited-x/manifest/v5/>
8083
- owl: <http://www.w3.org/2002/07/owl#>
84+
- prov: <http://www.w3.org/ns/prov#>
8185
- rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
8286
- schema: <https://schema.org/>
8387
- sh: <http://www.w3.org/ns/shacl#>
@@ -86,6 +90,10 @@ class Class_definition_for_SoftwareResourceBase
8690

8791
### SHACL Properties
8892

93+
#### envited-x:attributeName {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-attributename .property-anchor }
94+
#### envited-x:confidence {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-confidence .property-anchor }
95+
#### envited-x:derivationMethod {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-derivationmethod .property-anchor }
96+
#### envited-x:hasAttributeProvenance {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasattributeprovenance .property-anchor }
8997
#### envited-x:hasCodeArtifact {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hascodeartifact .property-anchor }
9098
#### envited-x:hasContent {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hascontent .property-anchor }
9199
#### envited-x:hasDataSource {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasdatasource .property-anchor }
@@ -97,18 +105,22 @@ class Class_definition_for_SoftwareResourceBase
97105
#### envited-x:hasResourceDescription {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasresourcedescription .property-anchor }
98106
#### envited-x:hasServiceOffering {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasserviceoffering .property-anchor }
99107
#### envited-x:hasSoftwareResource {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hassoftwareresource .property-anchor }
108+
#### envited-x:llmModel {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-llmmodel .property-anchor }
100109
#### gx:copyrightOwnedBy {: #prop-https---w3id-org-gaia-x-development-copyrightownedby .property-anchor }
101110
#### gx:license {: #prop-https---w3id-org-gaia-x-development-license .property-anchor }
102111
#### gx:providedBy {: #prop-https---w3id-org-gaia-x-development-providedby .property-anchor }
103112
#### gx:resourcePolicy {: #prop-https---w3id-org-gaia-x-development-resourcepolicy .property-anchor }
104113
#### gx:serviceOfferingTermsAndConditions {: #prop-https---w3id-org-gaia-x-development-serviceofferingtermsandconditions .property-anchor }
114+
#### gx:version {: #prop-https---w3id-org-gaia-x-development-version .property-anchor }
105115
#### manifest:hasAccessRole {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-hasaccessrole .property-anchor }
106116
#### manifest:hasArtifacts {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-hasartifacts .property-anchor }
107117
#### manifest:hasCategory {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-hascategory .property-anchor }
108118
#### manifest:hasLicense {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-haslicense .property-anchor }
109119
#### manifest:hasManifestReference {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-hasmanifestreference .property-anchor }
110120
#### manifest:hasReferencedArtifacts {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-hasreferencedartifacts .property-anchor }
111121
#### manifest:iri {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-iri .property-anchor }
122+
#### prov:endedAtTime {: #prop-http---www-w3-org-ns-prov-endedattime .property-anchor }
123+
#### prov:wasAssociatedWith {: #prop-http---www-w3-org-ns-prov-wasassociatedwith .property-anchor }
112124
#### rdf:type {: #prop-http---www-w3-org-1999-02-22-rdf-syntax-ns-type .property-anchor }
113125
#### schema:description {: #prop-https---schema-org-description .property-anchor }
114126
#### schema:name {: #prop-https---schema-org-name .property-anchor }
@@ -164,3 +176,12 @@ class Class_definition_for_SoftwareResourceBase
164176
|DomainSpecificationShape|envited-x|<a id="prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasdatasource"></a>hasDataSource|0||||envited-x.shacl.ttl|
165177
|DomainSpecificationShape|envited-x|<a id="prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasquality"></a>hasQuality|0||||envited-x.shacl.ttl|
166178
|DomainSpecificationShape|envited-x|<a id="prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasquantity"></a>hasQuantity|0||||envited-x.shacl.ttl|
179+
|DomainSpecificationShape|envited-x|<a id="prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasattributeprovenance"></a>hasAttributeProvenance|0||Records which metadata attributes were automatically derived, by which tool and method.||envited-x.shacl.ttl|
180+
|AttributeProvenanceShape|envited-x|<a id="prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-attributename"></a>attributeName|1|1|The name of the metadata attribute whose provenance is declared.|<http://www.w3.org/2001/XMLSchema#string>|envited-x.shacl.ttl|
181+
|AttributeProvenanceShape|envited-x|<a id="prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-derivationmethod"></a>derivationMethod|1|1|The method used to derive the attribute value.||envited-x.shacl.ttl|
182+
|AttributeProvenanceShape|envited-x|<a id="prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-confidence"></a>confidence||1|Confidence level of the derived value.||envited-x.shacl.ttl|
183+
|AttributeProvenanceShape|prov|<a id="prop-http---www-w3-org-ns-prov-wasassociatedwith"></a>wasAssociatedWith|1|1|The software agent (tool or service) that produced this attribute value.||envited-x.shacl.ttl|
184+
|AttributeProvenanceShape|prov|<a id="prop-http---www-w3-org-ns-prov-endedattime"></a>endedAtTime||1|Timestamp when the attribute was derived.|<http://www.w3.org/2001/XMLSchema#dateTime>|envited-x.shacl.ttl|
185+
|SoftwareAgentShape|schema|name|1|1|Human-readable name of the software agent.|<http://www.w3.org/2001/XMLSchema#string>|envited-x.shacl.ttl|
186+
|SoftwareAgentShape|gx|<a id="prop-https---w3id-org-gaia-x-development-version"></a>version|1|1|Version identifier of the software agent.|<http://www.w3.org/2001/XMLSchema#string>|envited-x.shacl.ttl|
187+
|SoftwareAgentShape|envited-x|<a id="prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-llmmodel"></a>llmModel||1|Identifier of the LLM model used, if derivation method is llm-inference. Absent for non-LLM methods.|<http://www.w3.org/2001/XMLSchema#string>|envited-x.shacl.ttl|

‎artifacts/envited-x/envited-x.context.jsonld‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,19 @@
1818
"envited-x": "https://w3id.org/ascs-ev/envited-x/envited-x/v3/",
1919
"manifest": "https://w3id.org/ascs-ev/envited-x/manifest/v5/",
2020
"gx": "https://w3id.org/gaia-x/development#",
21+
"attributeName": {
22+
"@id": "envited-x:attributeName"
23+
},
24+
"confidence": {
25+
"@id": "envited-x:confidence"
26+
},
27+
"derivationMethod": {
28+
"@id": "envited-x:derivationMethod"
29+
},
30+
"hasAttributeProvenance": {
31+
"@id": "envited-x:hasAttributeProvenance",
32+
"@type": "@id"
33+
},
2134
"hasCodeArtifact": {
2235
"@id": "envited-x:hasCodeArtifact",
2336
"@type": "@id"
@@ -57,6 +70,10 @@
5770
"@id": "envited-x:hasSoftwareResource",
5871
"@type": "@id"
5972
},
73+
"llmModel": {
74+
"@id": "envited-x:llmModel"
75+
},
76+
"AttributeProvenance": "envited-x:AttributeProvenance",
6077
"CodeArtifactBase": "envited-x:CodeArtifactBase",
6178
"CodeAsset": "envited-x:CodeAsset",
6279
"Content": "envited-x:Content",

‎artifacts/envited-x/envited-x.owl.ttl‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
88
@prefix org: <http://www.w3.org/ns/org#> .
99
@prefix prov: <http://www.w3.org/ns/prov#> .
10+
@prefix schema: <https://schema.org/> .
11+
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
1012

1113

1214
# Ontology metadata
@@ -405,3 +407,44 @@ envited-x:isOwner a manifest:AccessRole, owl:NamedIndividual ;
405407
envited-x:isRegistered a manifest:AccessRole, owl:NamedIndividual ;
406408
rdfs:label "Registered Access Role"@en ;
407409
rdfs:comment "Indicates that the artifact access role is registered user in the envited-x context."@en .
410+
411+
412+
###################################################################
413+
# Attribute Provenance — records how individual metadata fields
414+
# were derived and which software tool/model produced them.
415+
###################################################################
416+
417+
envited-x:AttributeProvenance a owl:Class ;
418+
rdfs:label "Attribute Provenance"@en ;
419+
rdfs:comment "Records the derivation method and responsible software agent for one or more metadata attributes that were automatically filled."@en ;
420+
rdfs:subClassOf prov:Activity .
421+
422+
envited-x:hasAttributeProvenance a owl:ObjectProperty ;
423+
rdfs:label "has attribute provenance"@en ;
424+
rdfs:comment "Links a DomainSpecification to provenance records describing how individual attributes were derived."@en ;
425+
rdfs:domain envited-x:DomainSpecification ;
426+
rdfs:range envited-x:AttributeProvenance .
427+
428+
envited-x:attributeName a owl:DatatypeProperty ;
429+
rdfs:label "attribute name"@en ;
430+
rdfs:comment "The name of the metadata attribute whose provenance is being declared."@en ;
431+
rdfs:domain envited-x:AttributeProvenance ;
432+
rdfs:range xsd:string .
433+
434+
envited-x:derivationMethod a owl:DatatypeProperty ;
435+
rdfs:label "derivation method"@en ;
436+
rdfs:comment "The method used to derive the attribute value. One of: extraction (parsed from source), calculation (computed from source values), rule-based-inference (heuristic mapping), llm-inference (LLM model generated), manual (human input)."@en ;
437+
rdfs:domain envited-x:AttributeProvenance ;
438+
rdfs:range xsd:string .
439+
440+
envited-x:confidence a owl:DatatypeProperty ;
441+
rdfs:label "confidence"@en ;
442+
rdfs:comment "Confidence level of the derived value: high, medium, or low."@en ;
443+
rdfs:domain envited-x:AttributeProvenance ;
444+
rdfs:range xsd:string .
445+
446+
envited-x:llmModel a owl:DatatypeProperty ;
447+
rdfs:label "LLM model"@en ;
448+
rdfs:comment "Identifier of the LLM model used for inference (e.g. 'claude-sonnet-4', 'gpt-4o'). Absent or null when derivation is not LLM-based."@en ;
449+
rdfs:domain prov:SoftwareAgent ;
450+
rdfs:range xsd:string .

‎artifacts/envited-x/envited-x.shacl.ttl‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
@prefix envited-x: <https://w3id.org/ascs-ev/envited-x/envited-x/v3/> .
22
@prefix manifest: <https://w3id.org/ascs-ev/envited-x/manifest/v5/> .
33
@prefix gx: <https://w3id.org/gaia-x/development#> .
4+
@prefix prov: <http://www.w3.org/ns/prov#> .
45
@prefix sh: <http://www.w3.org/ns/shacl#> .
56
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
67
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@@ -548,6 +549,13 @@ envited-x:DomainSpecificationShape a sh:NodeShape ;
548549
sh:minCount 0 ;
549550
sh:message "Optional: a DomainSpecification may specify quantity-related information via envited-x:hasQuantity."@en ;
550551
] ;
552+
sh:property [
553+
sh:path envited-x:hasAttributeProvenance ;
554+
sh:node envited-x:AttributeProvenanceShape ;
555+
sh:minCount 0 ;
556+
sh:description "Records which metadata attributes were automatically derived, by which tool and method."@en ;
557+
sh:message "Optional: a DomainSpecification may declare provenance for automatically derived attributes via envited-x:hasAttributeProvenance."@en ;
558+
] ;
551559

552560
sh:targetClass envited-x:DomainSpecification .
553561

@@ -590,3 +598,95 @@ envited-x:QuantityShape a sh:NodeShape ;
590598

591599
sh:message "Node must be of type envited-x:Quantity." ;
592600
sh:targetClass envited-x:Quantity .
601+
602+
603+
###################################################################
604+
# Attribute Provenance Shape — validates provenance annotations
605+
# for automatically derived metadata attributes.
606+
###################################################################
607+
608+
envited-x:AttributeProvenanceShape a sh:NodeShape ;
609+
sh:closed false ;
610+
sh:description "Declares how a metadata attribute was derived and which software agent produced it."@en ;
611+
sh:property [
612+
skos:example "scenarioCategory" ;
613+
sh:datatype xsd:string ;
614+
sh:description "The name of the metadata attribute whose provenance is declared."@en ;
615+
sh:minCount 1 ;
616+
sh:maxCount 1 ;
617+
sh:message "Each AttributeProvenance must declare exactly one attributeName."@en ;
618+
sh:name "attribute name"@en ;
619+
sh:order 0 ;
620+
sh:path envited-x:attributeName
621+
] , [
622+
skos:example "rule-based-inference" ;
623+
sh:description "The method used to derive the attribute value."@en ;
624+
sh:in ("extraction" "calculation" "rule-based-inference" "llm-inference" "manual") ;
625+
sh:minCount 1 ;
626+
sh:maxCount 1 ;
627+
sh:message "derivationMethod must be one of: extraction, calculation, rule-based-inference, llm-inference, manual."@en ;
628+
sh:name "derivation method"@en ;
629+
sh:order 1 ;
630+
sh:path envited-x:derivationMethod
631+
] , [
632+
skos:example "high" ;
633+
sh:description "Confidence level of the derived value."@en ;
634+
sh:in ("high" "medium" "low") ;
635+
sh:maxCount 1 ;
636+
sh:message "confidence must be one of: high, medium, low."@en ;
637+
sh:name "confidence"@en ;
638+
sh:order 2 ;
639+
sh:path envited-x:confidence
640+
] , [
641+
sh:description "The software agent (tool or service) that produced this attribute value."@en ;
642+
sh:node envited-x:SoftwareAgentShape ;
643+
sh:minCount 1 ;
644+
sh:maxCount 1 ;
645+
sh:message "Each AttributeProvenance must reference exactly one prov:wasAssociatedWith software agent."@en ;
646+
sh:name "software agent"@en ;
647+
sh:order 3 ;
648+
sh:path prov:wasAssociatedWith
649+
] , [
650+
sh:datatype xsd:dateTime ;
651+
sh:description "Timestamp when the attribute was derived."@en ;
652+
sh:maxCount 1 ;
653+
sh:name "generation time"@en ;
654+
sh:order 4 ;
655+
sh:path prov:endedAtTime
656+
] ;
657+
sh:targetClass envited-x:AttributeProvenance .
658+
659+
660+
envited-x:SoftwareAgentShape a sh:NodeShape ;
661+
sh:closed false ;
662+
sh:description "Identifies a software tool or LLM model that derived metadata values."@en ;
663+
sh:property [
664+
skos:example "sl-5-8-asset-tools/llm_enricher" ;
665+
sh:datatype xsd:string ;
666+
sh:description "Human-readable name of the software agent."@en ;
667+
sh:minCount 1 ;
668+
sh:maxCount 1 ;
669+
sh:message "A SoftwareAgent must have a schema:name."@en ;
670+
sh:name "name"@en ;
671+
sh:order 0 ;
672+
sh:path schema:name
673+
] , [
674+
skos:example "0.1.0" ;
675+
sh:datatype xsd:string ;
676+
sh:description "Version identifier of the software agent."@en ;
677+
sh:minCount 1 ;
678+
sh:maxCount 1 ;
679+
sh:message "A SoftwareAgent must declare its gx:version."@en ;
680+
sh:name "version"@en ;
681+
sh:order 1 ;
682+
sh:path gx:version
683+
] , [
684+
skos:example "claude-sonnet-4" ;
685+
sh:datatype xsd:string ;
686+
sh:description "Identifier of the LLM model used, if derivation method is llm-inference. Absent for non-LLM methods."@en ;
687+
sh:maxCount 1 ;
688+
sh:name "LLM model"@en ;
689+
sh:order 2 ;
690+
sh:path envited-x:llmModel
691+
] ;
692+
sh:targetClass prov:SoftwareAgent .

0 commit comments

Comments
 (0)