Factor out a roles schema

This takes the most essential classes and slots from the `prov` schema, and factors them out. It does so, trying to consolidate the concepts of PROV's `Influence` and DCAT's `QualifiedRelation` into a single schema element (`Relationship`). `Relationship` links two (and only two) things. The previous exception of a multi-object relationship within `Derivation` is given up for homogeneity. A `Relationship` can be characterized by multiple roles. The corresponding slot `had_roles` is declared to be multivalued (and uses the plural form in its slot name). A number of `prov-schema` elements have been removed in an effort to simplify the resulting data structures: The slots `agent` and `entity` are replaced by a reuse of thing's `object` uniformly. The respective range definitions have been moved to the corresponding association classes. `Influence` is removed, and `Relationship` is used as a base for more specialized PROV relationships.
psychoinformatics-de · Dec 13, 2024 · 7f1e6c5 · 7f1e6c5
1 parent 82461a6
commit 7f1e6c5
Show file tree

Hide file tree

Showing 37 changed files with 1,813 additions and 1,769 deletions.
diff --git a/Makefile b/Makefile
@@ -16,6 +16,7 @@ all: build/mkdocs-site
 build/linkml-docs: \
 	build/linkml-docs/s/properties/unreleased \
 	build/linkml-docs/s/thing/unreleased \
+	build/linkml-docs/s/roles/unreleased \
 	build/linkml-docs/s/prov/unreleased \
 	build/linkml-docs/s/identifiers/unreleased \
 	build/linkml-docs/s/distribution/unreleased \
@@ -55,6 +56,7 @@ check: check-models check-validation
 check-models: \
 	checkmodel/properties/unreleased \
 	checkmodel/thing/unreleased \
+	checkmodel/roles/unreleased \
 	checkmodel/prov/unreleased \
 	checkmodel/identifiers/unreleased \
 	checkmodel/distribution/unreleased \
@@ -89,6 +91,8 @@ checkmodel/%: src/%.yaml
 check-validation: \
 	convertexamples/thing/unreleased \
 	checkvalidation/thing/unreleased \
+	convertexamples/roles/unreleased \
+	checkvalidation/roles/unreleased \
 	convertexamples/prov/unreleased \
 	checkvalidation/prov/unreleased \
 	convertexamples/identifiers/unreleased \
@@ -114,6 +118,7 @@ checkinvalid/%: src/%/validation src/%.yaml
 
 convert-examples: \
 	convertexamples/thing/unreleased \
+	convertexamples/roles/unreleased \
 	convertexamples/prov/unreleased \
 	convertexamples/identifiers/unreleased \
 	convertexamples/distribution/unreleased \

diff --git a/extra-docs/index.md b/extra-docs/index.md
@@ -3,6 +3,7 @@ ALL CONTENT HERE IS UNRELEASED AND MAY CHANGE ANY TIME
 - [Thing schema](s/thing/unreleased/index.md)
 - [Properties schema](s/properties/unreleased/index.md)
 - [Identifiers schema](s/identifiers/unreleased/index.md)
+- [Roles schema](s/roles/unreleased/index.md)
 - [Provenance schema](s/prov/unreleased/index.md)
 - [Data distribution schema](s/distribution/unreleased/index.md)
 - [DataLad dataset schema](s/datalad-dataset/unreleased/index.md)

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -7,6 +7,7 @@ nav:
     - Thing (unreleased): s/thing/unreleased/index.md
     - Properties (unreleased): s/properties/unreleased/index.md
     - Identifiers (unreleased): s/identifiers/unreleased/index.md
+    - Roles (unreleased): s/roles/unreleased/index.md
     - Provenance (unreleased): s/prov/unreleased/index.md
     - Distribution (unreleased): s/distribution/unreleased/index.md
     - DataLad dataset (unreleased): s/datalad-dataset/unreleased/index.md
@@ -19,6 +20,7 @@ plugins:
           's/thing/index.md': 's/thing/unreleased/index.md'
           's/properties/index.md': 's/properties/unreleased/index.md'
           's/identifiers/index.md': 's/identifiers/unreleased/index.md'
+          's/roles/index.md': 's/roles/unreleased/index.md'
           's/prov/index.md': 's/prov/unreleased/index.md'
           's/distribution/index.md': 's/distribution/unreleased/index.md'
           's/datalad-dataset/index.md': 's/datalad-dataset/unreleased/index.md'

diff --git a/src/datalad-dataset/unreleased/examples/Distribution-datasetcontentaccess.json b/src/datalad-dataset/unreleased/examples/Distribution-datasetcontentaccess.json
@@ -39,7 +39,7 @@
   "qualified_part": [
     {
       "name": "README.md",
-      "entity": "gitsha:f776e30f386b83e13196eab6445f30d3ab54c155"
+      "object": "gitsha:f776e30f386b83e13196eab6445f30d3ab54c155"
     }
   ],
   "@type": "Distribution"

diff --git a/src/datalad-dataset/unreleased/examples/Distribution-datasetcontentaccess.yaml b/src/datalad-dataset/unreleased/examples/Distribution-datasetcontentaccess.yaml
@@ -40,4 +40,4 @@ has_part:
     - https://github.com/datalad-datasets/machinelearning-books.git
 qualified_part:
   name: README.md
-  entity: gitsha:f776e30f386b83e13196eab6445f30d3ab54c155
+  object: gitsha:f776e30f386b83e13196eab6445f30d3ab54c155
diff --git a/src/datalad-dataset/unreleased/examples/Distribution-gittree.json b/src/datalad-dataset/unreleased/examples/Distribution-gittree.json
@@ -5,11 +5,11 @@
   "qualified_part": [
     {
       "name": "table.csv",
-      "entity": "annex-key:MD5E-s3214--ba1f2511fc30423bdbb183fe33f3dd0f.csv"
+      "object": "annex-key:MD5E-s3214--ba1f2511fc30423bdbb183fe33f3dd0f.csv"
     },
     {
       "name": "index.html",
-      "entity": "gitsha:e12e9505cff5417f594d719b99720b4c39d86434"
+      "object": "gitsha:e12e9505cff5417f594d719b99720b4c39d86434"
     }
   ],
   "@type": "Distribution"

diff --git a/src/datalad-dataset/unreleased/examples/Distribution-gittree.yaml b/src/datalad-dataset/unreleased/examples/Distribution-gittree.yaml
@@ -3,9 +3,9 @@ id: gitsha:9a48c2bf7e97a081f2b1ab68eb909bbfc86267be
 # of metadata records on dataset aspects) there is no need to
 # reiterate any information here: just link content under a name
 qualified_part:
-  - entity: annex-key:MD5E-s3214--ba1f2511fc30423bdbb183fe33f3dd0f.csv
+  - object: annex-key:MD5E-s3214--ba1f2511fc30423bdbb183fe33f3dd0f.csv
     name: table.csv
-  - entity: gitsha:e12e9505cff5417f594d719b99720b4c39d86434
+  - object: gitsha:e12e9505cff5417f594d719b99720b4c39d86434
     name: index.html
 # this tree is the top-level tree of a particular commit
 is_distribution_of: gitsha:8d6f033bb2a6109b2c4d64d6f27b0feb181e4d0f
diff --git a/src/distribution/unreleased.yaml b/src/distribution/unreleased.yaml
@@ -579,11 +579,13 @@ classes:
       - dcat:Relationship
     slots:
       - name
-      - entity
+      - object
     slot_usage:
       name:
         description: >-
           The name of the part within the containing entity.
+      object:
+        range: Entity
     comments:
       - This class is a key element of the data model. It enables referencing
         a particular resource (e.g., a file's content, or versioned directory

diff --git a/src/distribution/unreleased/examples/Distribution-datatypes.json b/src/distribution/unreleased/examples/Distribution-datatypes.json
@@ -9,12 +9,10 @@
   "schema_type": "dldist:Distribution",
   "qualified_relation": [
     {
-      "had_role": [
+      "object": "obo:NCIT_C95650",
+      "had_roles": [
         "obo:NCIT_C42645"
       ],
-      "entity": [
-        "obo:NCIT_C95650"
-      ],
       "schema_type": "dlprov:EntityInfluence"
     }
   ],

diff --git a/src/distribution/unreleased/examples/Distribution-datatypes.yaml b/src/distribution/unreleased/examples/Distribution-datatypes.yaml
@@ -2,10 +2,9 @@ id: exthisdsver:./file.jpeg
 # two approaches:
 # first using the common qualified-relation pattern.
 qualified_relation:
-  - entity:
-      # encapsulated image data
-      - obo:NCIT_C95650
-    had_role:
+  # encapsulated image data
+  - object: obo:NCIT_C95650
+    had_roles:
       # data type
       - obo:NCIT_C42645
 # when standardized terms for identifying data types are not available,

diff --git a/src/distribution/unreleased/examples/Distribution-gittree.json b/src/distribution/unreleased/examples/Distribution-gittree.json
@@ -5,11 +5,11 @@
   "qualified_part": [
     {
       "name": "table.csv",
-      "entity": "https://concepts.datalad.org/ns/annex-key/MD5E-s3214--ba1f2511fc30423bdbb183fe33f3dd0f.csv"
+      "object": "https://concepts.datalad.org/ns/annex-key/MD5E-s3214--ba1f2511fc30423bdbb183fe33f3dd0f.csv"
     },
     {
       "name": "index.html",
-      "entity": "https://concepts.datalad.org/ns/gitsha/e12e9505cff5417f594d719b99720b4c39d86434"
+      "object": "https://concepts.datalad.org/ns/gitsha/e12e9505cff5417f594d719b99720b4c39d86434"
     }
   ],
   "@type": "Distribution"

diff --git a/src/distribution/unreleased/examples/Distribution-gittree.yaml b/src/distribution/unreleased/examples/Distribution-gittree.yaml
@@ -3,9 +3,9 @@ id: https://concepts.datalad.org/ns/gitsha/9a48c2bf7e97a081f2b1ab68eb909bbfc8626
 # of metadata records on dataset aspects) there is no need to
 # reiterate any information here: just link content under a name
 qualified_part:
-  - entity: https://concepts.datalad.org/ns/annex-key/MD5E-s3214--ba1f2511fc30423bdbb183fe33f3dd0f.csv
+  - object: https://concepts.datalad.org/ns/annex-key/MD5E-s3214--ba1f2511fc30423bdbb183fe33f3dd0f.csv
     name: table.csv
-  - entity: https://concepts.datalad.org/ns/gitsha/e12e9505cff5417f594d719b99720b4c39d86434
+  - object: https://concepts.datalad.org/ns/gitsha/e12e9505cff5417f594d719b99720b4c39d86434
     name: index.html
 # this tree is the top-level tree of a particular commit
 is_distribution_of: https://concepts.datalad.org/ns/gitsha/8d6f033bb2a6109b2c4d64d6f27b0feb181e4d0f
diff --git a/src/distribution/unreleased/examples/Distribution-parts.json b/src/distribution/unreleased/examples/Distribution-parts.json
@@ -28,15 +28,15 @@
       "qualified_part": [
         {
           "name": "file.txt",
-          "entity": "exthisdsver:./archive.zip/subdir/file.txt"
+          "object": "exthisdsver:./archive.zip/subdir/file.txt"
         }
       ]
     }
   ],
   "qualified_part": [
     {
       "name": "subdir",
-      "entity": "exthisdsver:./archive.zip/subdir"
+      "object": "exthisdsver:./archive.zip/subdir"
     }
   ],
   "@type": "Distribution"

diff --git a/src/distribution/unreleased/examples/Distribution-parts.yaml b/src/distribution/unreleased/examples/Distribution-parts.yaml
@@ -19,7 +19,7 @@ has_part:
             value: "A file"
     qualified_part:
       - name: file.txt
-        entity: exthisdsver:./archive.zip/subdir/file.txt
+        object: exthisdsver:./archive.zip/subdir/file.txt
 qualified_part:
   - name: subdir
-    entity: exthisdsver:./archive.zip/subdir
+    object: exthisdsver:./archive.zip/subdir
diff --git a/src/distribution/unreleased/examples/Resource-gitcommit.json b/src/distribution/unreleased/examples/Resource-gitcommit.json
@@ -7,10 +7,10 @@
       "type": "obo:NCIT_C25625",
       "qualified_association": [
         {
-          "had_role": [
+          "object": "exthisds:#[email protected]",
+          "had_roles": [
             "marcrel:aut"
-          ],
-          "agent": "exthisds:#[email protected]"
+          ]
         }
       ],
       "ended_at": "2001-02-28T18:27:04+02:00"
@@ -21,10 +21,10 @@
       "type": "obo:NCIT_C42882",
       "qualified_association": [
         {
-          "had_role": [
+          "object": "exthisds:#[email protected]",
+          "had_roles": [
             "marcrel:cre"
-          ],
-          "agent": "exthisds:#[email protected]"
+          ]
         }
       ],
       "was_informed_by": [
@@ -67,12 +67,10 @@
   "schema_type": "dldist:Resource",
   "qualified_derivation": [
     {
-      "had_role": [
+      "object": "https://concepts.datalad.org/ns/gitsha/a52963ce19a3e3628e9976555ffc8c422b29f054",
+      "had_roles": [
         "owl:priorVersion"
       ],
-      "entity": [
-        "https://concepts.datalad.org/ns/gitsha/a52963ce19a3e3628e9976555ffc8c422b29f054"
-      ],
       "schema_type": "dlprov:Derivation",
       "had_activity": "obo:NCIT_C25446"
     }

diff --git a/src/distribution/unreleased/examples/Resource-gitcommit.yaml b/src/distribution/unreleased/examples/Resource-gitcommit.yaml
@@ -26,16 +26,14 @@ has_attributes:
 version: 8d6f033bb2a6109b2c4d64d6f27b0feb181e4d0f
 qualified_derivation:
   # parent commit(s)
-  - entity:
-      # in a derivation any number of entities can play a role
-      - https://concepts.datalad.org/ns/gitsha/a52963ce19a3e3628e9976555ffc8c422b29f054
+  - object: https://concepts.datalad.org/ns/gitsha/a52963ce19a3e3628e9976555ffc8c422b29f054
     # "change", ie. unknown what was done
     # there are plenty of terms to drill down on the nature
     # of the derivation
     # - obo:NCIT_C64266: merge
     # - obo:NCIT_C64911: add
     had_activity: obo:NCIT_C25446
-    had_role:
+    had_roles:
       - owl:priorVersion
 relations:
   # author activity
@@ -49,8 +47,8 @@ relations:
     ended_at: "2001-02-28T18:27:04+02:00"
     qualified_association:
       # author of the commit
-      - agent: exthisds:#[email protected]
-        had_role:
+      - object: exthisds:#[email protected]
+        had_roles:
           - marcrel:aut
   # commit activity
   - id: https://concepts.datalad.org/ns/gitsha/8d6f033bb2a6109b2c4d64d6f27b0feb181e4d0f#committing
@@ -61,8 +59,8 @@ relations:
     ended_at: "2002-05-30T09:30:10+06:00"
     qualified_association:
       # creator of the commit
-      - agent: exthisds:#[email protected]
-        had_role:
+      - object: exthisds:#[email protected]
+        had_roles:
           - marcrel:cre
     was_informed_by:
       - https://concepts.datalad.org/ns/gitsha/8d6f033bb2a6109b2c4d64d6f27b0feb181e4d0f#authoring

diff --git a/src/distribution/unreleased/examples/Resource-study.json b/src/distribution/unreleased/examples/Resource-study.json
@@ -82,18 +82,18 @@
       "type": "obo:NCIT_C71104",
       "qualified_association": [
         {
-          "had_role": [
+          "object": "exthisds:#s001",
+          "had_roles": [
             "obo:NCIT_C142710",
             "obo:NCIT_C94342"
-          ],
-          "agent": "exthisds:#s001"
+          ]
         },
         {
-          "had_role": [
+          "object": "exthisds:#s002",
+          "had_roles": [
             "obo:NCIT_C142710",
             "obo:NCIT_C173188"
-          ],
-          "agent": "exthisds:#s002"
+          ]
         }
       ]
     }

diff --git a/src/distribution/unreleased/examples/Resource-study.yaml b/src/distribution/unreleased/examples/Resource-study.yaml
@@ -47,14 +47,14 @@ relations:
     # registered clinical trial
     type: obo:NCIT_C71104
     qualified_association:
-      - agent: exthisds:#s001
-        had_role:
+      - object: exthisds:#s001
+        had_roles:
           # study participant
           - obo:NCIT_C142710
           # healthy control
           - obo:NCIT_C94342
-      - agent: exthisds:#s002
-        had_role:
+      - object: exthisds:#s002
+        had_roles:
           - obo:NCIT_C142710
           # subject Assigned to Protocol Treatment Arm
           - obo:NCIT_C173188