Agent and Contribution to TU

ga4gh · Nov 27, 2024 · 4d9f544 · 4d9f544
1 parent d23d0c4
commit 4d9f544
Show file tree

Hide file tree

Showing 12 changed files with 88 additions and 223 deletions.
diff --git a/schema/va-spec/base/def/Activity.rst b/schema/va-spec/base/def/Activity.rst
diff --git a/schema/va-spec/base/def/Agent.rst b/schema/va-spec/base/def/Agent.rst
@@ -1,5 +1,5 @@
-.. warning:: This data class is at a **draft** maturity level and may \
-    change significantly in future releases. Maturity \
+.. note:: This data class is at a **trial use** maturity level and may \
+    change in future releases. Maturity \
     levels are described in the :ref:`maturity-model`.
 
 **Computational Definition**
@@ -26,11 +26,6 @@ Some Agent attributes are inherited from :ref:`gks-core:Entity`.
       - string
       - 0..1
       - The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.
-   *  - label
-      - 
-      - string
-      - 0..1
-      - A primary name for the entity.
    *  - description
       - 
       - string
@@ -64,6 +59,6 @@ Some Agent attributes are inherited from :ref:`gks-core:Entity`.
       - The given name of the Agent.
    *  - subtype
       - 
-      - string
+      - :ref:`MappableConcept`
       - 0..1
-      - A specific type of agent the Agent object represents. Must be one of {person, organization, software}.
+      - A specific type of agent the Agent object represents. Recommended subtypes include codes for `person`, `organization`, or `software`.
diff --git a/schema/va-spec/base/def/Contribution.rst b/schema/va-spec/base/def/Contribution.rst
@@ -1,5 +1,5 @@
-.. warning:: This data class is at a **draft** maturity level and may \
-    change significantly in future releases. Maturity \
+.. note:: This data class is at a **trial use** maturity level and may \
+    change in future releases. Maturity \
     levels are described in the :ref:`maturity-model`.
 
 **Computational Definition**
@@ -8,7 +8,7 @@ An action taken by an agent in contributing to the creation, modification, asses
 
 **Information Model**
 
-Some Contribution attributes are inherited from :ref:`Activity`.
+Some Contribution attributes are inherited from :ref:`gks-core:Entity`.
 
 .. list-table::
    :class: clean-wrap
@@ -52,39 +52,23 @@ Some Contribution attributes are inherited from :ref:`Activity`.
       - :ref:`Extension`
       - 0..m
       - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.
-   *  - subtype
-      - 
-      - :ref:`MappableConcept`
-      - 0..1
-      - A specific type of activity the Activity instance represents.
-   *  - date
-      - 
-      - :ref:`date`
-      - 0..1
-      - The date that the Activity was completed.
-   *  - specifiedBy
-      - 
-                        .. raw:: html
-
-                            <span style="background-color: #B2DFEE; color: black; padding: 2px 6px; border: 1px solid black; border-radius: 3px; font-weight: bold; display: inline-block; margin-bottom: 5px;" title="Unordered">&#8942;</span>
-      - :ref:`Method`
-      - 0..m
-      - A method that was followed in performing an Activity, that describes how it was executed.
    *  - type
       - 
       - string
       - 1..1
       - MUST be "Contribution".
    *  - contributor
       - 
-                        .. raw:: html
-
-                            <span style="background-color: #B2DFEE; color: black; padding: 2px 6px; border: 1px solid black; border-radius: 3px; font-weight: bold; display: inline-block; margin-bottom: 5px;" title="Unordered">&#8942;</span>
       - :ref:`Agent`
-      - 1..1
+      - 0..1
       - The agent that made the contribution.
    *  - activityType
       - 
       - :ref:`MappableConcept`
       - 0..1
       - The specific type of activity performed or role played by an agent in making the contribution (e.g. for a publication, agents may contribute as a primary author, editor, figure designer, data generator, etc.). Values of this property may be framed as activities, or as contribution roles (e.g. using terms from the Contribution Role Ontology (CRO)).
+   *  - date
+      - 
+      - :ref:`date`
+      - 0..1
+      - The date that the Activity was completed.
diff --git a/schema/va-spec/base/json/Agent b/schema/va-spec/base/json/Agent
@@ -3,18 +3,14 @@
    "$id": "https://w3id.org/ga4gh/schema/va-spec/1.0.0-ballot.2024-11.1/base/json/Agent",
    "title": "Agent",
    "type": "object",
-   "maturity": "draft",
+   "maturity": "trial use",
    "description": "An autonomous actor (person, organization, or software agent) that bears some form of responsibility for an activity taking place, for the existence of an entity, or for another agent's activity.",
    "properties": {
       "id": {
          "type": "string",
          "description": "The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
          "$comment": "Note that it is common for implementers to create their own internal logical ids - typically a serially or randomly generated value like a UUID that is assigned to the data object as it is created in a system. But an implementer may choose to re-use an existing, globally unique id from an external system or authority for this purpose (e.g. an HGNC id for a Gene object) - as long as it is unique within the implementing system, and can be used to reference the identified object in this context."
       },
-      "label": {
-         "type": "string",
-         "description": "A primary name for the entity."
-      },
       "description": {
          "type": "string",
          "description": "A free-text description of the Entity."
@@ -48,13 +44,8 @@
          "description": "The given name of the Agent."
       },
       "subtype": {
-         "type": "string",
-         "description": "A specific type of agent the Agent object represents. Must be one of {person, organization, software}.",
-         "enum": [
-            "person",
-            "organization",
-            "software"
-         ]
+         "description": "A specific type of agent the Agent object represents. Recommended subtypes include codes for `person`, `organization`, or `software`.",
+         "$ref": "/ga4gh/schema/gks-core/1.0.0-snapshot.2024-11.1/json/MappableConcept"
       }
    },
    "required": [

diff --git a/schema/va-spec/base/json/Contribution b/schema/va-spec/base/json/Contribution
@@ -3,7 +3,7 @@
    "$id": "https://w3id.org/ga4gh/schema/va-spec/1.0.0-ballot.2024-11.1/base/json/Contribution",
    "title": "Contribution",
    "type": "object",
-   "maturity": "draft",
+   "maturity": "trial use",
    "description": "An action taken by an agent in contributing to the creation, modification, assessment, or deprecation of a particular entity (e.g. a Statement, EvidenceLine, DataSet, Publication, etc.)",
    "properties": {
       "id": {
@@ -36,24 +36,6 @@
          "description": "A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
          "$comment": "Extension objects have a key-value data structure that allows definition of custom fields in the data itself. Extensions are not expected to be natively understood, but may be used for pre-negotiated exchange of message attributes between systems."
       },
-      "subtype": {
-         "description": "A specific type of activity the Activity instance represents.",
-         "$comment": "This attribute can be used to report a specific type for the Activity in cases where a model does not define Activity subclasses for this purpose. Implementers can define their own set of data set type codes/terms, to match the needs of the domain or application.",
-         "$ref": "/ga4gh/schema/gks-core/1.0.0-snapshot.2024-11.1/json/MappableConcept"
-      },
-      "date": {
-         "description": "The date that the Activity was completed.",
-         "$comment": "By convention, populate this attribute with the date the activity was completed (e.g. in cases where the activity spans multiple days). The date MUST be formatted as a date string in ISO8601 format \"YYYY-MM-DD\".",
-         "$ref": "/ga4gh/schema/gks-core/1.0.0-snapshot.2024-11.1/json/date"
-      },
-      "specifiedBy": {
-         "type": "array",
-         "ordered": false,
-         "items": {
-            "$ref": "/ga4gh/schema/va-spec/1.0.0-ballot.2024-11.1/base/json/Method"
-         },
-         "description": "A method that was followed in performing an Activity, that describes how it was executed."
-      },
       "type": {
          "type": "string",
          "description": "MUST be \"Contribution\".",
@@ -62,19 +44,17 @@
          "default": "Contribution"
       },
       "contributor": {
-         "type": "array",
-         "ordered": false,
-         "items": {
-            "$ref": "/ga4gh/schema/va-spec/1.0.0-ballot.2024-11.1/base/json/Agent"
-         },
-         "description": "The agent that made the contribution.",
-         "minItems": 1,
-         "maxItems": 1,
-         "$comment": "Note that this MUST be a single agent (which can be a Person, or an Organization). If multiple Agents contributed to an entity, a separate Contribution instances MUST be created to describe each."
+         "$ref": "/ga4gh/schema/va-spec/1.0.0-ballot.2024-11.1/base/json/Agent",
+         "description": "The agent that made the contribution."
       },
       "activityType": {
          "description": "The specific type of activity performed or role played by an agent in making the contribution (e.g. for a publication, agents may contribute as a primary author, editor, figure designer, data generator, etc.). Values of this property may be framed as activities, or as contribution roles (e.g. using terms from the Contribution Role Ontology (CRO)).",
          "$ref": "/ga4gh/schema/gks-core/1.0.0-snapshot.2024-11.1/json/MappableConcept"
+      },
+      "date": {
+         "description": "The date that the Activity was completed.",
+         "$comment": "By convention, populate this attribute with the date the activity was completed (e.g. in cases where the activity spans multiple days). The date MUST be formatted as a date string in ISO8601 format \"YYYY-MM-DD\".",
+         "$ref": "/ga4gh/schema/gks-core/1.0.0-snapshot.2024-11.1/json/date"
       }
    },
    "required": [

diff --git a/schema/va-spec/base/va-core-source.yaml b/schema/va-spec/base/va-core-source.yaml
@@ -88,44 +88,6 @@ $defs:
       #     by whom a record serialization was generated or modified; what upstream resources it was derived or retrieved
       #     from; and record-level administrative information such as versioning and lifecycle status.
 
-  Activity:
-    inherits: gks-core:Entity
-    maturity: draft
-    description: >-
-      An action or set of actions performed by an agent, that occurs over a period of time.
-      Activities may use, generate, modify, move, or destroy one or more entities.
-    heritableProperties:
-      subtype:
-        $refCurie: gks.core:MappableConcept
-        description: >-
-          A specific type of activity the Activity instance represents.
-        $comment: >-
-          This attribute can be used to report a specific type for the Activity in cases where
-          a model does not define Activity subclasses for this purpose. Implementers can define
-          their own set of data set type codes/terms, to match the needs of the domain or application.
-      date:
-        $refCurie: gks.core:date
-        description: >-
-          The date that the Activity was completed.
-        $comment: >-
-          By convention, populate this attribute with the date the activity was completed (e.g.
-          in cases where the activity spans multiple days). The date MUST be formatted as a date
-          string in ISO8601 format "YYYY-MM-DD".
-      performedBy:
-        type: array
-        ordered: false
-        items:
-          $ref: "#/$defs/Agent"
-        description: >-
-          A list of Agent(s) who participated in executing the Activity.
-      specifiedBy:
-        type: array
-        ordered: false
-        items:
-          $ref: "#/$defs/Method"
-        description: >-
-          A method that was followed in performing an Activity, that describes how it was executed.
-
   StudyResult:
     inherits: InformationEntity
     maturity: trial use
@@ -308,8 +270,8 @@ $defs:
 
   Contribution:
     type: object
-    inherits: Activity
-    maturity: draft
+    inherits: gks-core:Entity
+    maturity: trial use
     description: >-
       An action taken by an agent in contributing to the creation, modification, assessment, or
       deprecation of a particular entity (e.g. a Statement, EvidenceLine, DataSet, Publication, etc.)
@@ -320,22 +282,24 @@ $defs:
         default: Contribution
         description: MUST be "Contribution".
       contributor:
-        extends: performedBy
-        minItems: 1
-        maxItems: 1
+        $ref: "#/$defs/Agent"
         description: >-
           The agent that made the contribution.
-        $comment: >-
-          Note that this MUST be a single agent (which can be a Person, or an Organization).
-          If multiple Agents contributed to an entity, a separate Contribution instances MUST be
-          created to describe each.
       activityType:
         $refCurie: gks.core:MappableConcept
         description: >-
           The specific type of activity performed or role played by an agent in making the contribution
           (e.g. for a publication, agents may contribute as a primary author, editor, figure designer,
           data generator, etc.). Values of this property may be framed as activities, or as contribution
           roles (e.g. using terms from the Contribution Role Ontology (CRO)).
+      date:
+        $refCurie: gks.core:date
+        description: >-
+          The date that the Activity was completed.
+        $comment: >-
+          By convention, populate this attribute with the date the activity was completed (e.g.
+          in cases where the activity spans multiple days). The date MUST be formatted as a date
+          string in ISO8601 format "YYYY-MM-DD".
 
   Document:
     type: object
@@ -393,7 +357,7 @@ $defs:
   Agent:
     type: object
     inherits: gks-core:Entity
-    maturity: draft
+    maturity: trial use
     description: >-
       An autonomous actor (person, organization, or software agent) that bears some form
       of responsibility for an activity taking place, for the existence of an entity, or for
@@ -406,16 +370,13 @@ $defs:
         description: MUST be "Agent".
       name:
         type: string
+        extends: label
         description: The given name of the Agent.
       subtype:
-        type: string
+        $refCurie: gks.core:MappableConcept
         description: >-
-          A specific type of agent the Agent object represents. Must be one of {person,
-          organization, software}.
-        enum:
-          - person
-          - organization
-          - software
+          A specific type of agent the Agent object represents. Recommended subtypes
+          include codes for `person`, `organization`, or `software`.
 
   Statement:
     type: object