Factor out agents schema

Makefile

@@ -17,6 +17,7 @@ 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/agents/unreleased \
 	build/linkml-docs/s/prov/unreleased \
 	build/linkml-docs/s/identifiers/unreleased \
 	build/linkml-docs/s/distribution/unreleased \
@@ -57,6 +58,7 @@ check-models: \
 	checkmodel/properties/unreleased \
 	checkmodel/thing/unreleased \
 	checkmodel/roles/unreleased \
+	checkmodel/agents/unreleased \
 	checkmodel/prov/unreleased \
 	checkmodel/identifiers/unreleased \
 	checkmodel/distribution/unreleased \
@@ -93,6 +95,8 @@ check-validation: \
 	checkvalidation/thing/unreleased \
 	convertexamples/roles/unreleased \
 	checkvalidation/roles/unreleased \
+	convertexamples/agents/unreleased \
+	checkvalidation/agents/unreleased \
 	convertexamples/prov/unreleased \
 	checkvalidation/prov/unreleased \
 	convertexamples/identifiers/unreleased \
@@ -119,6 +123,7 @@ checkinvalid/%: src/%/validation src/%.yaml
 convert-examples: \
 	convertexamples/thing/unreleased \
 	convertexamples/roles/unreleased \
+	convertexamples/agents/unreleased \
 	convertexamples/prov/unreleased \
 	convertexamples/identifiers/unreleased \
 	convertexamples/distribution/unreleased \

extra-docs/index.md

@@ -4,6 +4,7 @@ ALL CONTENT HERE IS UNRELEASED AND MAY CHANGE ANY TIME
 - [Properties schema](s/properties/unreleased/index.md)
 - [Identifiers schema](s/identifiers/unreleased/index.md)
 - [Roles schema](s/roles/unreleased/index.md)
+- [Agents schema](s/agents/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)

mkdocs.yml

@@ -8,6 +8,7 @@ nav:
     - Properties (unreleased): s/properties/unreleased/index.md
     - Identifiers (unreleased): s/identifiers/unreleased/index.md
     - Roles (unreleased): s/roles/unreleased/index.md
+    - Agents (unreleased): s/agents/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
@@ -21,6 +22,7 @@ plugins:
           '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/agents/index.md': 's/agents/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'

src/agents/unreleased.yaml

@@ -0,0 +1,155 @@
+id: https://concepts.datalad.org/s/agents/unreleased
+name: agents-schema
+version: UNRELEASED
+status: bibo:status/draft
+title: Schema for characterizing agents and their relationships
+description: |
+  The main class of this schema is [`Agent`](Agent). It extends the
+  [`Thing`](Thing) base class primarily with slots to annotate
+  [`identifiers`](identifiers) of an `Agent`, and to characterize relationships
+  to other things with roles ([`qualified_relations`](qualified_relations)).
+
+  With [`Person`](Person), [`Organization`](Organization), and
+  [`SoftwareAgent`](SoftwareAgent), three additional classes are provided
+  for the three agent types included in PROV-DM. However, these classes
+  support no additional slots over their base class. Their purpose is only
+  semantic differentiation.
+
+  This schema does not implement a slot matching `prov:wasInfluencedBy`,
+  because [`qualified_relations`](qualified_relations) is already closely
+  matching the concept and expressiveness of this property. For the same
+  reason, there is a [`acted_on_behalf_of`](acted_on_behalf_of) slot, but no
+  `prov:qualifiedDelegation`, and no `prov:Delegation` equivalent. Instead, a
+  custom [`Role`](Role) can be declared, if desired as a dedicated `Delegation`
+  subclass, and used to qualify the relation to another [`Agent`](Agent) via
+  [`qualified_relations`](qualified_relations).
+
+  Two custom CURIE prefixes are declared by this schema. 1) `email:` to allow
+  for using emails as suitable schema identifiers for an email (e.g., 
+  `email:[email protected]`), and 2) `geo:`, defined simply as `geo:`, to be able
+  to use GEO URIs as schema identifiers for locations.
+
+  The schema definition is available as
+
+  - [JSON-LD context](../unreleased.jsonld)
+  - [LinkML YAML](../unreleased.yaml)
+  - [OWL TTL](../unreleased.owl.ttl)
+
+comments:
+  - ALL CONTENT HERE IS UNRELEASED AND MAY CHANGE ANY TIME
+
+license: MIT
+
+prefixes:
+  bibo: http://purl.org/ontology/bibo/
+  dlagents: https://concepts.datalad.org/s/agents/unreleased/
+  dlidentifiers: https://concepts.datalad.org/s/identifiers/unreleased/
+  dlroles: https://concepts.datalad.org/s/roles/unreleased/
+  dlthing: https://concepts.datalad.org/s/thing/unreleased/
+  foaf: http://xmlns.com/foaf/0.1/
+  linkml: https://w3id.org/linkml/
+  prov: http://www.w3.org/ns/prov#
+  # declare a namespace for emails, such that they can be defined as a curie
+  # e.g.: email:[email protected]
+  # -> https://concepts.datalad.org/ns/email/[email protected]
+  email: https://concepts.datalad.org/ns/email/
+  # disambiguate a GEO URI from a curie prefix
+  geo: "geo:"
+
+default_prefix: dlagents
+
+imports:
+  - ../identifiers/unreleased
+  - ../thing/unreleased
+  - ../roles/unreleased
+
+
+slots:
+  acted_on_behalf_of:
+    slot_uri: dlagents:acted_on_behalf_of
+    description: >-
+      Assign the authority and responsibility for carrying out a specific
+      activity of the subject agent to another agent.
+    domain: Agent
+    range: Agent
+    inlined: false
+    multivalued: true
+    exact_mappings:
+      - prov:actedOnBehalfOf
+
+classes:
+  Agent:
+    class_uri: dlagents:Agent
+    is_a: Thing
+    description: >-
+      Something that bears some form of responsibility for an activity
+      taking place, for the existence of an entity, or for another
+      agent's activity.
+    slots:
+      - acted_on_behalf_of
+      - identifiers
+      - qualified_relations
+    exact_mappings:
+      - foaf:Agent
+      - prov:Agent
+    comments:
+      - >-
+        This class does not support even a basic `name` slot, because
+        depending on the context, there may not be a suitable name,
+        or one name would not be enough. If no specialized derived
+        class is available in a context where a `name` or similar
+        attribute is desired, it can be expressed via the
+        `has_attributes` slot.
+
+  AgentInfluence:
+    class_uri: dlagents:AgentInfluence
+    is_a: Relationship
+    description: >-
+      Capacity of an agent to have an effect on the character, development,
+      or behavior of another Entity, Agent, or Activity
+    slot_usage:
+      object:
+        range: Agent
+    exact_mappings:
+      - prov:AgentInfluence
+
+  Person:
+    class_uri: dlagents:Person
+    is_a: Agent
+    description: >-
+      Person agents are people, alive, dead, or fictional.
+    exact_mappings:
+      - foaf:Person
+      - prov:Person
+    comments:
+      - This class does not offer common slots like "affiliation" or "email".
+        Instead, this information should be expressed as `qualified_relations`
+        to other things with a role characterization. An affiliation can be
+        expressed as a relation to an organization, and the role that the
+        organization has for the person (e.g., "employer").
+
+  Organization:
+    class_uri: dlagents:Organization
+    is_a: Agent
+    description: >-
+      A social or legal instititution such as a company, a society,
+      or a university.
+    exact_mappings:
+      - foaf:Organization
+      - prov:Organization
+    comments:
+      - This class does not offer common slots like "address" or "contact".
+        Instead, this information should be expressed as `qualified_relations`
+        to other things with a role-characterization. An address can be
+        expressed as a relation to a location, and the role this location
+        has for the organization (e.g., "main office"). Likewise, a contact
+        can be describe as a relation to a person, and the role that this
+        person fulfills for the organization (e.g., "spokesperson").
+
+  SoftwareAgent:
+    class_uri: dlagents:SoftwareAgent
+    is_a: Agent
+    description: >-
+      Running software.
+    exact_mappings:
+      - prov:SoftwareAgent

src/agents/unreleased/examples/Person-01-minimal.json

@@ -0,0 +1,5 @@
+{
+  "id": "http://orcid.org/0000-0001-7628-0801",
+  "schema_type": "dlagents:Person",
+  "@type": "Person"
+}

src/agents/unreleased/examples/Person-01-minimal.yaml

@@ -0,0 +1,2 @@
+# A valid minimal person record is an identifier
+id: http://orcid.org/0000-0001-7628-0801

src/agents/unreleased/examples/Person-02-attributes.json

@@ -0,0 +1,20 @@
+{
+  "id": "https://orcid.org/0000-0001-6398-6370",
+  "has_attributes": [
+    {
+      "predicate": "foaf:name",
+      "schema_type": "dlthing:AttributeSpecification",
+      "value": "Michael Hanke"
+    },
+    {
+      "predicate": "http://www.bioassayontology.org/bao#BAO_0002826",
+      "schema_type": "dlthing:AttributeSpecification",
+      "value": "1"
+    }
+  ],
+  "schema_type": "dlagents:Person",
+  "acted_on_behalf_of": [
+    "https://ror.org/02nv7yv05"
+  ],
+  "@type": "Person"
+}

src/agents/unreleased/examples/Person-02-attributes.yaml

@@ -0,0 +1,12 @@
+# The Person class does not define even basic attribute slots.
+# But common and exotic ones can be expressed nevertheless
+id: https://orcid.org/0000-0001-6398-6370
+acted_on_behalf_of:
+  - https://ror.org/02nv7yv05
+has_attributes:
+  - predicate: foaf:name
+    value: Michael Hanke
+  # has biosafety level
+  # "minimal potential hazard to laboratory personnel and the environment"
+  - predicate: http://www.bioassayontology.org/bao#BAO_0002826
+    value: "1"

src/agents/unreleased/examples/Person-03-relations.json

@@ -0,0 +1,19 @@
+{
+  "id": "https://example.com/ns/people/jane",
+  "schema_type": "dlagents:Person",
+  "qualified_relations": [
+    {
+      "object": "email:[email protected]",
+      "had_roles": [
+        "http://schema.org/email"
+      ]
+    },
+    {
+      "object": "geo:-19.738897,63.453072?z=19",
+      "had_roles": [
+        "obo:NCIT_C17556"
+      ]
+    }
+  ],
+  "@type": "Person"
+}

src/agents/unreleased/examples/Person-03-relations.yaml

@@ -0,0 +1,14 @@
+# Using "unconventional" object identifiers to qualify relationships.
+# The schema defines a custom namespace prefix to use emails as
+# identifiers for emails (not persons!). The schema also enables the
+# use of GEO URIs as identifiers for locations
+id: https://example.com/ns/people/jane
+qualified_relations:
+  - object: email:[email protected]
+    had_roles:
+      - http://schema.org/email
+  # using a GEO URI as a location identifier
+  - object: "geo:-19.738897,63.453072?z=19"
+    had_roles:
+      # worksite
+      - obo:NCIT_C17556

src/agents/unreleased/validation/Person.valid.cfg.yaml

@@ -0,0 +1,11 @@
+schema: src/agents/unreleased.yaml
+target_class: Person
+data_sources:
+  - src/agents/unreleased/examples/Person-01-minimal.yaml
+  - src/agents/unreleased/examples/Person-02-attributes.yaml
+  - src/agents/unreleased/examples/Person-03-relations.yaml
+plugins:
+  JsonschemaValidationPlugin:
+    closed: true
+    include_range_class_descendants: false
+  RecommendedSlotsPlugin:

src/distribution/unreleased.yaml

@@ -442,37 +442,6 @@ slots:
 
 
 classes:
-  #
-  # agents
-  #
-  Person:
-    class_uri: dldist:Person
-    is_a: Agent
-    description: >-
-      Person agents are people.
-    slots:
-      - address
-      - affiliation
-      - email
-    slot_usage:
-      affiliation:
-        multivalued: true
-    exact_mappings:
-      - foaf:Person
-      - prov:Person
-
-  Organization:
-    class_uri: dldist:Organization
-    is_a: Agent
-    description: >-
-      A social or legal instititution such as a company, a society,
-      or a university.
-    slots:
-      - address
-    exact_mappings:
-      - foaf:Organization
-      - prov:Organization
-
   #
   # entities
   #

src/distribution/unreleased/examples/Resource-study.json

@@ -16,7 +16,7 @@
           "predicate": "obo:PATO_0002201"
         }
       ],
-      "schema_type": "dlprov:Agent"
+      "schema_type": "dlagents:Agent"
     },
     {
       "id": "exthisds:#s002",
@@ -51,7 +51,7 @@
           "predicate": "obo:PATO_0000047"
         }
       ],
-      "schema_type": "dlprov:Agent"
+      "schema_type": "dlagents:Agent"
     },
     {
       "id": "exthisds:#study_2005-004406-93",

src/distribution/unreleased/examples/Resource-study.yaml

@@ -2,7 +2,7 @@ id: exthisdsver:#
 relations:
   # study participants (role assigned below)
   - id: exthisds:#s001
-    schema_type: dlprov:Agent
+    schema_type: dlagents:Agent
     has_attributes:
       - predicate: foaf:name
         value: s001
@@ -12,7 +12,7 @@ relations:
         # ambidextrous
         object: obo:PATO_0002204
   - id: exthisds:#s002
-    schema_type: dlprov:Agent
+    schema_type: dlagents:Agent
     is_characterized_by:
       # biological sex
       - predicate: obo:PATO_0000047