diff --git a/artifacts/envited-x/PROPERTIES.md b/artifacts/envited-x/PROPERTIES.md index be6d4897..bc6464e2 100644 --- a/artifacts/envited-x/PROPERTIES.md +++ b/artifacts/envited-x/PROPERTIES.md @@ -4,6 +4,7 @@ ```mermaid classDiagram +class Attribute_Provenance class Class_definition_for_CodeArtifactBase class Class_definition_for_CodeAsset class Class_definition_for_Content @@ -23,6 +24,7 @@ class Class_definition_for_SoftwareResourceBase ### Class Hierarchy +- Attribute Provenance (https://w3id.org/ascs-ev/envited-x/envited-x/v3/AttributeProvenance) - Class definition for CodeArtifactBase (https://w3id.org/ascs-ev/envited-x/envited-x/v3/CodeArtifactBase) - Class definition for CodeAsset (https://w3id.org/ascs-ev/envited-x/envited-x/v3/CodeAsset) - Class definition for Content (https://w3id.org/ascs-ev/envited-x/envited-x/v3/Content) @@ -43,6 +45,7 @@ class Class_definition_for_SoftwareResourceBase |Class|IRI|Description|Parents| |---|---|---|---| +|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| |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| |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. Carries domain-specific metadata while delegating GX compliance @@ -78,6 +81,7 @@ class Class_definition_for_SoftwareResourceBase - gx: - manifest: - owl: +- prov: - rdf: - schema: - sh: @@ -86,6 +90,10 @@ class Class_definition_for_SoftwareResourceBase ### SHACL Properties +#### envited-x:attributeName {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-attributename .property-anchor } +#### envited-x:confidence {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-confidence .property-anchor } +#### envited-x:derivationMethod {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-derivationmethod .property-anchor } +#### envited-x:hasAttributeProvenance {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasattributeprovenance .property-anchor } #### envited-x:hasCodeArtifact {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hascodeartifact .property-anchor } #### envited-x:hasContent {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hascontent .property-anchor } #### envited-x:hasDataSource {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasdatasource .property-anchor } @@ -97,11 +105,13 @@ class Class_definition_for_SoftwareResourceBase #### envited-x:hasResourceDescription {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasresourcedescription .property-anchor } #### envited-x:hasServiceOffering {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hasserviceoffering .property-anchor } #### envited-x:hasSoftwareResource {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-hassoftwareresource .property-anchor } +#### envited-x:llmModel {: #prop-https---w3id-org-ascs-ev-envited-x-envited-x-v3-llmmodel .property-anchor } #### gx:copyrightOwnedBy {: #prop-https---w3id-org-gaia-x-development-copyrightownedby .property-anchor } #### gx:license {: #prop-https---w3id-org-gaia-x-development-license .property-anchor } #### gx:providedBy {: #prop-https---w3id-org-gaia-x-development-providedby .property-anchor } #### gx:resourcePolicy {: #prop-https---w3id-org-gaia-x-development-resourcepolicy .property-anchor } #### gx:serviceOfferingTermsAndConditions {: #prop-https---w3id-org-gaia-x-development-serviceofferingtermsandconditions .property-anchor } +#### gx:version {: #prop-https---w3id-org-gaia-x-development-version .property-anchor } #### manifest:hasAccessRole {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-hasaccessrole .property-anchor } #### manifest:hasArtifacts {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-hasartifacts .property-anchor } #### manifest:hasCategory {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-hascategory .property-anchor } @@ -109,6 +119,8 @@ class Class_definition_for_SoftwareResourceBase #### manifest:hasManifestReference {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-hasmanifestreference .property-anchor } #### manifest:hasReferencedArtifacts {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-hasreferencedartifacts .property-anchor } #### manifest:iri {: #prop-https---w3id-org-ascs-ev-envited-x-manifest-v5-iri .property-anchor } +#### prov:endedAtTime {: #prop-http---www-w3-org-ns-prov-endedattime .property-anchor } +#### prov:wasAssociatedWith {: #prop-http---www-w3-org-ns-prov-wasassociatedwith .property-anchor } #### rdf:type {: #prop-http---www-w3-org-1999-02-22-rdf-syntax-ns-type .property-anchor } #### schema:description {: #prop-https---schema-org-description .property-anchor } #### schema:name {: #prop-https---schema-org-name .property-anchor } @@ -164,3 +176,12 @@ class Class_definition_for_SoftwareResourceBase |DomainSpecificationShape|envited-x|hasDataSource|0||||envited-x.shacl.ttl| |DomainSpecificationShape|envited-x|hasQuality|0||||envited-x.shacl.ttl| |DomainSpecificationShape|envited-x|hasQuantity|0||||envited-x.shacl.ttl| +|DomainSpecificationShape|envited-x|hasAttributeProvenance|0||Records which metadata attributes were automatically derived, by which tool and method.||envited-x.shacl.ttl| +|AttributeProvenanceShape|envited-x|attributeName|1|1|The name of the metadata attribute whose provenance is declared.||envited-x.shacl.ttl| +|AttributeProvenanceShape|envited-x|derivationMethod|1|1|The method used to derive the attribute value.||envited-x.shacl.ttl| +|AttributeProvenanceShape|envited-x|confidence||1|Confidence level of the derived value.||envited-x.shacl.ttl| +|AttributeProvenanceShape|prov|wasAssociatedWith|1|1|The software agent (tool or service) that produced this attribute value.||envited-x.shacl.ttl| +|AttributeProvenanceShape|prov|endedAtTime||1|Timestamp when the attribute was derived.||envited-x.shacl.ttl| +|SoftwareAgentShape|schema|name|1|1|Human-readable name of the software agent.||envited-x.shacl.ttl| +|SoftwareAgentShape|gx|version|1|1|Version identifier of the software agent.||envited-x.shacl.ttl| +|SoftwareAgentShape|envited-x|llmModel||1|Identifier of the LLM model used, if derivation method is llm-inference. Absent for non-LLM methods.||envited-x.shacl.ttl| diff --git a/artifacts/envited-x/envited-x.context.jsonld b/artifacts/envited-x/envited-x.context.jsonld index 3a4e3d45..fc205a3b 100644 --- a/artifacts/envited-x/envited-x.context.jsonld +++ b/artifacts/envited-x/envited-x.context.jsonld @@ -16,8 +16,22 @@ "skos": "http://www.w3.org/2004/02/skos/core#", "schema": "https://schema.org/", "envited-x": "https://w3id.org/ascs-ev/envited-x/envited-x/v3/", + "prov": "http://www.w3.org/ns/prov#", "manifest": "https://w3id.org/ascs-ev/envited-x/manifest/v5/", "gx": "https://w3id.org/gaia-x/development#", + "attributeName": { + "@id": "envited-x:attributeName" + }, + "confidence": { + "@id": "envited-x:confidence" + }, + "derivationMethod": { + "@id": "envited-x:derivationMethod" + }, + "hasAttributeProvenance": { + "@id": "envited-x:hasAttributeProvenance", + "@type": "@id" + }, "hasCodeArtifact": { "@id": "envited-x:hasCodeArtifact", "@type": "@id" @@ -57,6 +71,10 @@ "@id": "envited-x:hasSoftwareResource", "@type": "@id" }, + "llmModel": { + "@id": "envited-x:llmModel" + }, + "AttributeProvenance": "envited-x:AttributeProvenance", "CodeArtifactBase": "envited-x:CodeArtifactBase", "CodeAsset": "envited-x:CodeAsset", "Content": "envited-x:Content", diff --git a/artifacts/envited-x/envited-x.owl.ttl b/artifacts/envited-x/envited-x.owl.ttl index 5599bd6a..b78b1a54 100644 --- a/artifacts/envited-x/envited-x.owl.ttl +++ b/artifacts/envited-x/envited-x.owl.ttl @@ -7,6 +7,8 @@ @prefix foaf: . @prefix org: . @prefix prov: . +@prefix schema: . +@prefix xsd: . # Ontology metadata @@ -44,7 +46,8 @@ # Imports strict dependencies owl:imports , - ; + , + ; # Reference to SHACL validation rules dcterms:conformsTo ; @@ -405,3 +408,44 @@ envited-x:isOwner a manifest:AccessRole, owl:NamedIndividual ; envited-x:isRegistered a manifest:AccessRole, owl:NamedIndividual ; rdfs:label "Registered Access Role"@en ; rdfs:comment "Indicates that the artifact access role is registered user in the envited-x context."@en . + + +################################################################### +# Attribute Provenance — records how individual metadata fields +# were derived and which software tool/model produced them. +################################################################### + +envited-x:AttributeProvenance a owl:Class ; + rdfs:label "Attribute Provenance"@en ; + rdfs:comment "Records the derivation method and responsible software agent for one or more metadata attributes that were automatically filled."@en ; + rdfs:subClassOf prov:Activity . + +envited-x:hasAttributeProvenance a owl:ObjectProperty ; + rdfs:label "has attribute provenance"@en ; + rdfs:comment "Links a DomainSpecification to provenance records describing how individual attributes were derived."@en ; + rdfs:domain envited-x:DomainSpecification ; + rdfs:range envited-x:AttributeProvenance . + +envited-x:attributeName a owl:DatatypeProperty ; + rdfs:label "attribute name"@en ; + rdfs:comment "The name of the metadata attribute whose provenance is being declared."@en ; + rdfs:domain envited-x:AttributeProvenance ; + rdfs:range xsd:string . + +envited-x:derivationMethod a owl:DatatypeProperty ; + rdfs:label "derivation method"@en ; + 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 ; + rdfs:domain envited-x:AttributeProvenance ; + rdfs:range xsd:string . + +envited-x:confidence a owl:DatatypeProperty ; + rdfs:label "confidence"@en ; + rdfs:comment "Confidence level of the derived value: high, medium, or low."@en ; + rdfs:domain envited-x:AttributeProvenance ; + rdfs:range xsd:string . + +envited-x:llmModel a owl:DatatypeProperty ; + rdfs:label "LLM model"@en ; + 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 ; + rdfs:domain prov:SoftwareAgent ; + rdfs:range xsd:string . diff --git a/artifacts/envited-x/envited-x.shacl.ttl b/artifacts/envited-x/envited-x.shacl.ttl index 99da87f2..7938266b 100644 --- a/artifacts/envited-x/envited-x.shacl.ttl +++ b/artifacts/envited-x/envited-x.shacl.ttl @@ -1,6 +1,7 @@ @prefix envited-x: . @prefix manifest: . @prefix gx: . +@prefix prov: . @prefix sh: . @prefix rdf: . @prefix skos: . @@ -548,6 +549,13 @@ envited-x:DomainSpecificationShape a sh:NodeShape ; sh:minCount 0 ; sh:message "Optional: a DomainSpecification may specify quantity-related information via envited-x:hasQuantity."@en ; ] ; + sh:property [ + sh:path envited-x:hasAttributeProvenance ; + sh:node envited-x:AttributeProvenanceShape ; + sh:minCount 0 ; + sh:description "Records which metadata attributes were automatically derived, by which tool and method."@en ; + sh:message "Optional: a DomainSpecification may declare provenance for automatically derived attributes via envited-x:hasAttributeProvenance."@en ; + ] ; sh:targetClass envited-x:DomainSpecification . @@ -590,3 +598,97 @@ envited-x:QuantityShape a sh:NodeShape ; sh:message "Node must be of type envited-x:Quantity." ; sh:targetClass envited-x:Quantity . + + +################################################################### +# Attribute Provenance Shape — validates provenance annotations +# for automatically derived metadata attributes. +################################################################### + +envited-x:AttributeProvenanceShape a sh:NodeShape ; + sh:closed false ; + sh:description "Declares how a metadata attribute was derived and which software agent produced it."@en ; + sh:property [ + skos:example "scenarioCategory" ; + sh:datatype xsd:string ; + sh:description "The name of the metadata attribute whose provenance is declared."@en ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:message "Each AttributeProvenance must declare exactly one attributeName."@en ; + sh:name "attribute name"@en ; + sh:order 0 ; + sh:path envited-x:attributeName + ] , [ + skos:example "rule-based-inference" ; + sh:description "The method used to derive the attribute value."@en ; + sh:in ("extraction" "calculation" "rule-based-inference" "llm-inference" "manual") ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:message "derivationMethod must be one of: extraction, calculation, rule-based-inference, llm-inference, manual."@en ; + sh:name "derivation method"@en ; + sh:order 1 ; + sh:path envited-x:derivationMethod + ] , [ + skos:example "high" ; + sh:description "Confidence level of the derived value."@en ; + sh:in ("high" "medium" "low") ; + sh:maxCount 1 ; + sh:message "confidence must be one of: high, medium, low."@en ; + sh:name "confidence"@en ; + sh:order 2 ; + sh:path envited-x:confidence + ] , [ + sh:description "The software agent (tool or service) that produced this attribute value."@en ; + sh:node envited-x:SoftwareAgentShape ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:message "Each AttributeProvenance must reference exactly one prov:wasAssociatedWith software agent."@en ; + sh:name "software agent"@en ; + sh:order 3 ; + sh:path prov:wasAssociatedWith + ] , [ + sh:datatype xsd:dateTime ; + sh:description "Timestamp when the attribute was derived."@en ; + sh:maxCount 1 ; + sh:name "generation time"@en ; + sh:order 4 ; + sh:path prov:endedAtTime + ] ; + sh:targetClass envited-x:AttributeProvenance . + + +envited-x:SoftwareAgentShape a sh:NodeShape ; + sh:closed false ; + sh:description "Identifies a software tool or LLM model that derived metadata values."@en ; + sh:property [ + skos:example "sl-5-8-asset-tools/llm_enricher" ; + sh:datatype xsd:string ; + sh:description "Human-readable name of the software agent."@en ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:message "A SoftwareAgent must have a schema:name."@en ; + sh:name "name"@en ; + sh:order 0 ; + sh:path schema:name + ] , [ + skos:example "0.1.0" ; + sh:datatype xsd:string ; + sh:description "Version identifier of the software agent."@en ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:message "A SoftwareAgent must declare its gx:version."@en ; + sh:name "version"@en ; + sh:order 1 ; + sh:path gx:version + ] , [ + skos:example "claude-sonnet-4" ; + sh:datatype xsd:string ; + sh:description "Identifier of the LLM model used, if derivation method is llm-inference. Absent for non-LLM methods."@en ; + sh:maxCount 1 ; + sh:name "LLM model"@en ; + sh:order 2 ; + sh:path envited-x:llmModel + ] . + # Note: No sh:targetClass here — this shape is validated indirectly via + # sh:node reference from AttributeProvenanceShape. We do not claim + # authority over all prov:SoftwareAgent instances globally.