DatasetMetadata: express reused-term class linkage with schema:domainIncludes (fixes #92)

.github/README.md

@@ -75,6 +75,59 @@ It is recommended to use the [new File Header RDFS](https://github.com/entsoe/ap
 # RDF schemas (RDFS)
 The RDFS 2020 export of the RDFS augmented version is based on IEC 61970-501:2006 (Ed1). The package contains RDFS for CGMES v3.0 and NC Profiles. These are the files which file name contains “Voc-RDFS2020”.
 
+## RDFS conventions and the RDFS ↔ SHACL division of responsibility
+
+The RDFS2020 vocabulary is the **self-standing structural schema** of the exchange. It is serialised as flat RDF/XML — one `rdf:Description` per class or attribute, **no nested descriptions and no blank nodes** — and it defines:
+
+- **Classes and attributes** — which classes exist and which attributes each class carries. This structural backbone lives here, and only here.
+- **The class ↔ attribute linkage**, expressed so that reused vocabularies are not altered:
+  - attributes **owned in a CIM namespace** (`https://cim4.eu/ns/dcatcim#`, `https://cim4.eu/ns/Metadata-European#`, `https://cim.ucaiug.io/ns#`, …) use **`rdfs:domain`** — CIM owns the term, so a strict domain is correct, even when the domain class is external (e.g. `dcatcim:preferredVersion rdfs:domain dcat:Dataset`);
+  - **reused external terms attached to a class of the same vocabulary** (`dcat:keyword` on `dcat:Dataset`, `rdf:subject`/`rdf:predicate`/`rdf:object` on `rdf:Statement`) also use **`rdfs:domain`** — the linkage stays inside the owner's own vocabulary, so it restates rather than alters the owner's intent (RDF Schema itself declares `rdfs:domain rdf:Statement` for the reification properties);
+  - **reused external terms attached to a foreign class** (`dcterms:`, `prov:`, `adms:` on `dcat:Dataset` or `dcatcim:Statements`) use **`schema:domainIncludes`** — schema.org's non-inferential counterpart to `rdfs:domain`, which records "expected on this class" **without** the RDFS entailment. Asserting `rdfs:domain` on a term the profile does not own is ontology hijacking (`dcterms:title rdfs:domain dcat:Dataset` would entail that every titled resource, including an ontology, is a `dcat:Dataset`); Dublin Core leaves these terms domain-free for exactly that reason. See [#92](https://github.com/entsoe/application-profiles-library/issues/92).
+  - **Exception**: `dcat:startDate` and `dcat:endDate` keep **`schema:domainIncludes`** although property and class share the `dcat:` namespace — DCAT itself declares `rdfs:domain dcterms:PeriodOfTime` for both, so asserting `rdfs:domain dcat:Dataset` would contradict the owner's own declaration. The general test is: `rdfs:domain` may only be asserted where it matches, or at least cannot conflict with, what the owning vocabulary declares.
+- **Simple, attribute-local constraints** — datatype (`cims:dataType`) and multiplicity (`cims:multiplicity`).
+
+> **NB — BREAKING for `rdfs:domain`-driven tooling.** For reused external terms attached to a foreign class the linkage is now `schema:domainIncludes`, not `rdfs:domain`. Tooling that derives attribute-to-class membership must read both predicates. The `https://schema.org/` namespace is declared on the root `rdf:RDF` element.
+
+```xml
+<!-- reused external term on a same-vocabulary class — rdfs:domain restates the owner -->
+<rdf:Description rdf:about="http://www.w3.org/ns/dcat#keyword">
+  <cims:dataType rdf:resource="#String"/>
+  <rdfs:domain rdf:resource="http://www.w3.org/ns/dcat#Dataset"/>
+  <cims:multiplicity rdf:resource="http://iec.ch/TC57/1999/rdf-schema-extensions-19990926#M:0..n"/>
+  <cims:stereotype>dcat</cims:stereotype>
+  <rdf:type rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#Property"/>
+</rdf:Description>
+
+<!-- reused external term on a foreign class — non-inferential class linkage, no hijacking -->
+<rdf:Description rdf:about="http://purl.org/dc/terms/accessRights">
+  <cims:dataType rdf:resource="#URI"/>
+  <schema:domainIncludes rdf:resource="http://www.w3.org/ns/dcat#Dataset"/>
+  <cims:multiplicity rdf:resource="http://iec.ch/TC57/1999/rdf-schema-extensions-19990926#M:0..1"/>
+  <cims:stereotype>dcterms</cims:stereotype>
+  <rdf:type rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#Property"/>
+</rdf:Description>
+
+<!-- CIM-owned term — rdfs:domain stays -->
+<rdf:Description rdf:about="https://cim4.eu/ns/Metadata-European#usedSettings">
+  <cims:dataType rdf:resource="#URI"/>
+  <rdfs:domain rdf:resource="http://www.w3.org/ns/dcat#Dataset"/>
+  <rdf:type rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#Property"/>
+</rdf:Description>
+```
+
+The **Simple** SHACL constraints are generated mechanically from this RDFS (cardinalities and datatypes), so the vocabulary is the single source of truth for the structure. It follows that the structure must not migrate into SHACL: removing structural information from the RDFS without an RDFS-expressible replacement breaks every tool that generates the Simple SHACL, or an exchange schema, from the vocabulary.
+
+**SHACL** carries only what RDFS cannot express — the **Complex** and **Validation** constraints: value ranges, conditional and cross-attribute rules, cross-profile checks and SPARQL-based logic. SHACL is the validation layer; it does not hold the structural backbone.
+
+| Layer | Holds | Examples |
+|---|---|---|
+| **RDFS** (vocabulary) | structure + simple attribute-local constraints | classes, attributes, class↔attribute linkage (`rdfs:domain` / `schema:domainIncludes`), `cims:dataType`, `cims:multiplicity` |
+| **Simple SHACL** | mechanical projection of the RDFS | cardinality and datatype shapes generated from the vocabulary |
+| **Complex / Validation SHACL** | what RDFS cannot express | value ranges, conditionals, cross-profile, SPARQL |
+
+(The IEC 61970-501:Ed2 beta below explores moving these simple constraints fully into SHACL; the RDFS2020 files documented here keep them in the vocabulary.)
+
 In addition a [beta version](https://github.com/entsoe/application-profiles-library/tree/main/CGMES/CurrentRelease/RDFS/Beta_501_Ed2_CD) of application profile based on RDFS specified in the draft IEC 61970-501:Ed2 (see subfolder CGMES\RDFS\Beta_501_Ed2_CD) is provided. The purpose of inclusion of the beta version in the distribution is to enable the review process. 
 
 Please use these files only for information on the direction where RDFS will evolve in that standard and provide feedback that will be discussed in the standardisation process.