IRI Reference usage

docs/source/appendices/index.rst

@@ -7,5 +7,6 @@ Appendices
    class_diagram
    maturity_model
    ga4gh_identifiers
+   resource_identifiers
    truncated_digest_collision_analysis
    glossary

docs/source/appendices/resource_identifiers.rst

@@ -0,0 +1,104 @@
+.. _resource-identifiers:
+
+Resource Identifiers
+!!!!!!!!!!!!!!!!!!!!
+
+.. admonition:: New in v2
+
+    In VRS v1, references to VRS objects by :ref:`GA4GH Identifiers<ga4gh-identifiers>` 
+    were allowed in some data classes. In VRS v2, such references have been expanded to 
+    include any :ref:`iriReference`, and consequently VRS now also supports references to 
+    objects from classes that do not have GA4GH Identifiers.
+
+Some VRS data classes, such as the :ref:`Allele`, may reference other classes by an
+:ref:`iriReference`. This enables data producers to reference other objects following
+the `rfc3987`_ standard. :ref:`GA4GH Identifiers<ga4gh-identifiers>` may serve as IRI
+references in VRS.
+
+.. _rfc3987: https://datatracker.ietf.org/doc/html/rfc3987
+
+**Example:**
+
+The three Alleles below share a :ref:`SequenceLocation` and define it by reference:
+
+.. code-block:: json
+
+    {
+        "alleles": [
+            {
+                "type": "Allele",
+                "state": {
+                    "type": "LiteralSequenceExpression",
+                    "sequence": "A"
+                },
+                "location": "ga4gh:SL.4t6JnYWqHwYw9WzBT_lmWBb3tLQNalkT"
+            },{
+                "type": "Allele",
+                "state": {
+                    "type": "LiteralSequenceExpression",
+                    "sequence": "G"
+                },
+                "location": "ga4gh:SL.4t6JnYWqHwYw9WzBT_lmWBb3tLQNalkT"
+            },{
+                "type": "Allele",
+                "state": {
+                    "type": "LiteralSequenceExpression",
+                    "sequence": "C"
+                },
+                "location": "ga4gh:SL.4t6JnYWqHwYw9WzBT_lmWBb3tLQNalkT"
+            }]
+    }
+
+This Sequence Location may be defined elsewhere (e.g. another API endpoint, document, or 
+internal data structure) and retrievable by ID:
+
+.. code-block:: json
+
+    {
+        "id": "ga4gh:SL.4t6JnYWqHwYw9WzBT_lmWBb3tLQNalkT",
+        "type": "SequenceLocation",
+        "sequenceReference": "GRCh38.chr7",
+        "start": 44908821,
+        "end": 44908822,
+        "sequence": "T"
+    }
+
+And in turn, the :ref:`SequenceReference` object referenced by the Sequence Location:
+
+.. code-block:: json
+
+    {
+        "id": "GRCh38.chr7",
+        "label": "Chromosome 7 (build GRCh38)",
+        "type": "SequenceReference",
+        "refgetAccession": "SQ.F-LrLMe1SRpfUZHkQmvkVKFEGaoDeHul",
+        "residueAlphabet": "na",
+        "moleculeType": "genomic"
+    }
+
+A dereferenced Allele would include all of the above, nested components:
+
+.. code-block:: json
+
+    {
+        "type": "Allele",
+        "state": {
+            "type": "LiteralSequenceExpression",
+            "sequence": "A"
+        },
+        "location": {
+            "id": "ga4gh:SL.4t6JnYWqHwYw9WzBT_lmWBb3tLQNalkT",
+            "type": "SequenceLocation",
+            "sequenceReference": {
+                "id": "GRCh38.chr7",
+                "label": "Chromosome 7 (build GRCh38)",
+                "type": "SequenceReference",
+                "refgetAccession": "SQ.F-LrLMe1SRpfUZHkQmvkVKFEGaoDeHul",
+                "residueAlphabet": "na",
+                "moleculeType": "genomic"
+            }
+            "start": 44908821,
+            "end": 44908822,
+            "sequence": "T"
+        }
+    }

docs/source/concepts/AdditionalDataTypes/Code.rst

@@ -1,6 +1,6 @@
 .. _code:
 
-code
+Code
 !!!!
 
 .. include::  ../../def/gks-core/code.rst

docs/source/concepts/AdditionalDataTypes/Element.rst

@@ -1,6 +1,6 @@
 .. _Element:
 
 Element
-!!!!!!
+!!!!!!!
 
 .. include::  ../../def/gks-core/Element.rst

docs/source/concepts/AdditionalDataTypes/iriReference.rst

@@ -1,6 +1,6 @@
 .. _iriReference:
 
-iriReference
-!!!!!!!!!!!!
+IRI Reference
+!!!!!!!!!!!!!
 
 .. include::  ../../def/gks-core/iriReference.rst

schema/vrs/def/SequenceReference.rst

@@ -91,7 +91,7 @@ Some SequenceReference attributes are inherited from :ref:`gks-core:Entity`.
       - 
       - string
       - 0..1
-      - Molecule types as `defined by RefSeq <https://www.ncbi.nlm.nih.gov/books/NBK21091/>`_ (see Table 1).
+      - Molecule types as `defined by RefSeq <https://www.ncbi.nlm.nih.gov/books/NBK21091/>`_ (see Table 1). MUST be one of "genomic", "RNA", "mRNA", or "protein".
    *  - circular
       - 
       - boolean

schema/vrs/json/SequenceReference

@@ -68,7 +68,7 @@
       },
       "moleculeType": {
          "type": "string",
-         "description": "Molecule types as [defined by RefSeq](https://www.ncbi.nlm.nih.gov/books/NBK21091/) (see Table 1).",
+         "description": "Molecule types as [defined by RefSeq](https://www.ncbi.nlm.nih.gov/books/NBK21091/) (see Table 1). MUST be one of \"genomic\", \"RNA\", \"mRNA\", or \"protein\".",
          "enum": [
             "genomic",
             "RNA",

schema/vrs/vrs-source.yaml

@@ -355,6 +355,7 @@ $defs:
         type: string
         description: >-
           Molecule types as `defined by RefSeq <https://www.ncbi.nlm.nih.gov/books/NBK21091/>`_ (see Table 1).
+          MUST be one of "genomic", "RNA", "mRNA", or "protein".
         enum:
           - genomic
           - RNA