Merge pull request #81 from ga4gh/issue-80

Add MappableConcept

schema/core-im/core-im-source.yaml

@@ -335,6 +335,7 @@ $defs:
 
   RecordMetadata:
     type: object
+    inherits: Element
     maturity: draft
     description: >-
       A reusable structure that encapsulates provenance metadata about a serialized data record or
@@ -847,6 +848,7 @@ $defs:
 
   Characteristic:
     type: object
+    inherits: Element
     maturity: draft
     description: >-
       An object holding a name-value pair used to describe a trait or role of an individual
@@ -928,8 +930,20 @@ $defs:
   #     - predicate
   #     - object
 
+  Element:
+    maturity: trial use
+    description: >-
+      The base definition for all identifiable data objects.
+    heritableProperties:
+      id:
+        type: string
+        description: >-
+          The 'logical' identifier of the data element 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.
 
   Coding:
+    inherits: Element
     type: object
     maturity: draft
     description: >-
@@ -961,6 +975,7 @@ $defs:
 
   ConceptMapping:
     type: object
+    inherits: Element
     maturity: draft
     description: >-
       A mapping to a concept in a terminology or code system.
@@ -983,7 +998,27 @@ $defs:
       - relation
       - coding
 
+  MappableConcept:
+    inherits: Entity
+    type: object
+    maturity: trial use
+    description: >-
+      A concept label that may be mapped to one or more :ref:`Codings <Coding>`.
+    properties:
+      label:
+        type: string
+        description: A primary name for the entity.
+      mappings:
+        type: array
+        ordered: false
+        items:
+          $ref: "#/$defs/ConceptMapping"
+        description: >-
+          A list of mappings to concepts in terminologies or code systems. Each mapping should
+          include a coding and a relation.
+
   Extension:
+    inherits: Element
     type: object
     maturity: trial use
     description: >-

schema/core-im/def/Characteristic.rst

@@ -4,6 +4,7 @@ An object holding a name-value pair used to describe a trait or role of an indiv
 
 **Information Model**
 
+Some Characteristic attributes are inherited from :ref:`Element`.
 
 .. list-table::
    :class: clean-wrap
@@ -15,6 +16,10 @@ An object holding a name-value pair used to describe a trait or role of an indiv
       - Type
       - Limits
       - Description
+   *  - id
+      - string
+      - 0..1
+      - The 'logical' identifier of the data element 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.
    *  - name
       - string
       - 1..1

schema/core-im/def/Coding.rst

@@ -4,6 +4,7 @@ A structured representation of a code for a defined concept in a terminology or
 
 **Information Model**
 
+Some Coding attributes are inherited from :ref:`Element`.
 
 .. list-table::
    :class: clean-wrap
@@ -15,6 +16,10 @@ A structured representation of a code for a defined concept in a terminology or
       - Type
       - Limits
       - Description
+   *  - id
+      - string
+      - 0..1
+      - The 'logical' identifier of the data element 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

schema/core-im/def/ConceptMapping.rst

@@ -4,6 +4,7 @@ A mapping to a concept in a terminology or code system.
 
 **Information Model**
 
+Some ConceptMapping attributes are inherited from :ref:`Element`.
 
 .. list-table::
    :class: clean-wrap
@@ -15,6 +16,10 @@ A mapping to a concept in a terminology or code system.
       - Type
       - Limits
       - Description
+   *  - id
+      - string
+      - 0..1
+      - The 'logical' identifier of the data element 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.
    *  - coding
       - :ref:`Coding`
       - 1..1

schema/core-im/def/Element.rst

@@ -0,0 +1,21 @@
+**Computational Definition**
+
+The base definition for all identifiable data objects.
+
+**Information Model**
+
+
+.. list-table::
+   :class: clean-wrap
+   :header-rows: 1
+   :align: left
+   :widths: auto
+
+   *  - Field
+      - Type
+      - Limits
+      - Description
+   *  - id
+      - string
+      - 0..1
+      - The 'logical' identifier of the data element 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.

schema/core-im/def/Extension.rst

@@ -4,6 +4,7 @@ The Extension class provides entities with a means to include additional attribu
 
 **Information Model**
 
+Some Extension attributes are inherited from :ref:`Element`.
 
 .. list-table::
    :class: clean-wrap
@@ -15,6 +16,10 @@ The Extension class provides entities with a means to include additional attribu
       - Type
       - Limits
       - Description
+   *  - id
+      - string
+      - 0..1
+      - The 'logical' identifier of the data element 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.
    *  - name
       - string
       - 1..1

schema/core-im/def/MappableConcept.rst

@@ -0,0 +1,46 @@
+**Computational Definition**
+
+A concept label that may be mapped to one or more :ref:`Codings <Coding>`.
+
+**Information Model**
+
+Some MappableConcept attributes are inherited from :ref:`Entity`.
+
+.. list-table::
+   :class: clean-wrap
+   :header-rows: 1
+   :align: left
+   :widths: auto
+
+   *  - Field
+      - Type
+      - Limits
+      - Description
+   *  - id
+      - 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.
+   *  - type
+      - string
+      - 1..1
+      - The name of the class that is instantiated by a data object representing the Entity.
+   *  - label
+      - string
+      - 0..1
+      - A primary name for the entity.
+   *  - description
+      - string
+      - 0..1
+      - A free-text description of the Entity.
+   *  - alternativeLabels
+      - string
+      - 0..m
+      - Alternative name(s) for the Entity.
+   *  - extensions
+      - :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.
+   *  - mappings
+      - :ref:`ConceptMapping`
+      - 0..m
+      - A list of mappings to concepts in terminologies or code systems. Each mapping should include a coding and a relation.

schema/core-im/def/RecordMetadata.rst

@@ -4,6 +4,7 @@ A reusable structure that encapsulates provenance metadata about a serialized da
 
 **Information Model**
 
+Some RecordMetadata attributes are inherited from :ref:`Element`.
 
 .. list-table::
    :class: clean-wrap
@@ -15,6 +16,10 @@ A reusable structure that encapsulates provenance metadata about a serialized da
       - Type
       - Limits
       - Description
+   *  - id
+      - string
+      - 0..1
+      - The 'logical' identifier of the data element 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.
    *  - recordIdentifier
       - string
       - 0..1

schema/core-im/json/Characteristic

@@ -7,6 +7,10 @@
    "description": "An object holding a name-value pair used to describe a trait or role of an individual member of a StudyGroup.",
    "$comment": "This flexible key-value like object is where specific inclusion or exclusion criteria for membership in a StudyGroup are formally defined. It should be used to capture characteristics that inhere in individual members of the StudyGroup (e.g. inherent traits like their sex, race, or age, or roles assigned to them in a particular context such as being a control in a study).",
    "properties": {
+      "id": {
+         "type": "string",
+         "description": "The 'logical' identifier of the data element 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."
+      },
       "name": {
          "type": "string",
          "description": "The type of the trait  or role described by the trait (e.g. 'ethnicity', 'sex', 'age', 'disease status')."

schema/core-im/json/Coding

@@ -6,6 +6,10 @@
    "maturity": "draft",
    "description": "A structured representation of a code for a defined concept in a terminology or code system.",
    "properties": {
+      "id": {
+         "type": "string",
+         "description": "The 'logical' identifier of the data element 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": {
          "type": "string",
          "description": "The human-readable name for the coded concept, as defined by the code system."

schema/core-im/json/ConceptMapping

@@ -6,6 +6,10 @@
    "maturity": "draft",
    "description": "A mapping to a concept in a terminology or code system.",
    "properties": {
+      "id": {
+         "type": "string",
+         "description": "The 'logical' identifier of the data element 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."
+      },
       "coding": {
          "$ref": "/ga4gh/schema/gks-common/1.x/core-im/json/Coding",
          "description": "A structured representation of a code for a defined concept in a terminology or code system."

schema/core-im/json/Extension

@@ -3,9 +3,13 @@
    "$id": "https://w3id.org/ga4gh/schema/gks-common/1.x/core-im/json/Extension",
    "title": "Extension",
    "type": "object",
-   "maturity": "draft",
+   "maturity": "trial use",
    "description": "The Extension class provides entities with a means to include additional attributes that are outside of the specified standard but needed by a given content provider or system implementer. These extensions are not expected to be natively understood, but may be used for pre-negotiated exchange of message attributes between systems.",
    "properties": {
+      "id": {
+         "type": "string",
+         "description": "The 'logical' identifier of the data element 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."
+      },
       "name": {
          "type": "string",
          "description": "A name for the Extension. Should be indicative of its meaning and/or the type of information it value represents."

schema/core-im/json/IRI

@@ -3,7 +3,7 @@
    "$id": "https://w3id.org/ga4gh/schema/gks-common/1.x/core-im/json/IRI",
    "title": "IRI",
    "type": "string",
-   "maturity": "draft",
+   "maturity": "trial use",
    "description": "An IRI Reference (either an IRI or a relative-reference), according to [RFC3986 section 4.1](https://datatracker.ietf.org/doc/html/rfc3986#section-4.1>`_ and `RFC3987 section 2.1 <https://datatracker.ietf.org/doc/html/rfc3987#section-2.1>`_. MAY be a JSON Pointer as an IRI fragment, as described by `RFC6901 section 6 <https://datatracker.ietf.org/doc/html/rfc6901#section-6).",
    "format": "iri-reference"
 }

schema/core-im/json/MappableConcept

@@ -0,0 +1,56 @@
+{
+   "$schema": "https://json-schema.org/draft/2020-12/schema",
+   "$id": "https://w3id.org/ga4gh/schema/gks-common/1.x/core-im/json/MappableConcept",
+   "title": "MappableConcept",
+   "type": "object",
+   "maturity": "trial use",
+   "description": "A concept label that may be mapped to one or more Codings.",
+   "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."
+      },
+      "type": {
+         "type": "string",
+         "description": "The name of the class that is instantiated by a data object representing the Entity.",
+         "$comment": "MUST be the label of a concrete class from the data model."
+      },
+      "label": {
+         "type": "string",
+         "description": "A primary name for the entity."
+      },
+      "description": {
+         "type": "string",
+         "description": "A free-text description of the Entity."
+      },
+      "alternativeLabels": {
+         "type": "array",
+         "ordered": false,
+         "items": {
+            "type": "string"
+         },
+         "description": "Alternative name(s) for the Entity."
+      },
+      "extensions": {
+         "type": "array",
+         "ordered": false,
+         "items": {
+            "$ref": "/ga4gh/schema/gks-common/1.x/core-im/json/Extension"
+         },
+         "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."
+      },
+      "mappings": {
+         "type": "array",
+         "ordered": false,
+         "items": {
+            "$ref": "/ga4gh/schema/gks-common/1.x/core-im/json/ConceptMapping"
+         },
+         "description": "A list of mappings to concepts in terminologies or code systems. Each mapping should include a coding and a relation."
+      }
+   },
+   "required": [
+      "type"
+   ]
+}

schema/core-im/json/RecordMetadata

@@ -7,6 +7,10 @@
    "description": "A reusable structure that encapsulates provenance metadata about a serialized data record or object in a particular dataset (as opposed to provenance about the real world entity this record or object represents).",
    "$comment": "Record-level metadata applies to a specific concrete encoding/serialization of information (e.g as a record in a specific data/knowlegebase, or an online digital resource). A RecordMetadata object can capture when, how, and by whom a specific 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. RecordMetadata objects should not be used to describe provenance of the abstract information content or knowledge captured in a data record or object - other properties in the model are defined to support this use case.",
    "properties": {
+      "id": {
+         "type": "string",
+         "description": "The 'logical' identifier of the data element 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."
+      },
       "recordIdentifier": {
          "type": "string",
          "description": "The identifier of the data record or object described in this RecordMetadata object."