documentation updates

Author: larrybabb

docs/source/appendices/design_decisions.rst

@@ -59,7 +59,7 @@ As an example, the Github JSON Schema URL ($id) for the VRS 2.0.0 Allele is:
 
   {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://w3id.org/ga4gh/schema/vrs/2.0.0/json/Allele",
+    "$id": "https://w3id.org/ga4gh/schema/vrs/2.0/json/Allele",
     ...
   }
 

docs/source/concepts/AdditionalDataTypes/Element.rst

@@ -4,6 +4,8 @@ Additional Data Types
 !!!!!!!!!!!!!!!!!!!!!
 
 Below are the additional data types used by the VRS models.
+Any classes with the *imported* tag are used by VRS but maintained by the GA4GH GKS
+Work Stream as common data classes.
 
 Abstract Classes
 @@@@@@@@@@@@@@@@
@@ -56,6 +58,62 @@ represent variants using other syntaxes, including HGVS and SPDI.
 
 .. include::  ../../def/vrs/Expression.rst
 
+.. _gks-core:Entity:
+.. _Entity:
+
+Entity
+######
+*imported*
+
+.. include::  ../../def/gks-core/Entity.rst
+
+.. _gks-core:Element:
+.. _Element:
+
+Element
+#######
+*imported*
+
+.. include::  ../../def/gks-core/Element.rst
+
+General Purposes Types
+@@@@@@@@@@@@@@@@@@@@@@
+
+General purpose data types.
+
+.. _Extension:
+
+Extension
+#########
+*imported*
+
+.. include::  ../../def/gks-core/Extension.rst
+
+.. _MappableConcept:
+
+Mappable Concept
+################
+*imported*
+
+.. include::  ../../def/gks-core/MappableConcept.rst
+
+.. _ConceptMapping:
+
+Concept Mapping
+###############
+*imported*
+
+.. include::  ../../def/gks-core/ConceptMapping.rst
+
+.. _Coding:
+
+Coding
+######
+*imported*
+
+.. include::  ../../def/gks-core/Coding.rst
+
+
 Primitive Types
 @@@@@@@@@@@@@@@
 
@@ -83,16 +141,18 @@ sequenceString
 
 .. include:: ../../def/vrs/sequenceString.rst
 
-Imported Classes
-@@@@@@@@@@@@@@@@
+.. _code:
 
-The following classes are used by VRS but maintained by the GA4GH GKS
-Work Stream as common data classes.
+code
+####
+*imported*
+
+.. include::  ../../def/gks-core/Code.rst
+
+.. _iriReference:
 
-.. toctree::
-   :titlesonly:
+iriReference
+############
+*imported*
 
-   Entity
-   Element
-   Extension
-   iriReference
+.. include::  ../../def/gks-core/iriReference.rst

docs/source/concepts/AdditionalDataTypes/Entity.rst

@@ -57,7 +57,7 @@ In some variant representation formats (e.g. HGVS, VCF) sequence variants are de
 (ref) and "alternate" (alt) alleles. When representing an Allele with VRS v2, it is also possible to describe the
 ref sequence (derived from the :ref:`SequenceReference` at the location) using the *sequence* property.
 
-The ``sequence`` property is **for describing the sequence derived from the SequenceLocation**, and is not a
+The *sequence* property is **for describing the sequence derived from the SequenceLocation**, and is not a
 substitute for the ``sequenceReference`` property that references the sequence on which the location is defined.
 
 .. admonition:: New in v2
@@ -68,7 +68,7 @@ substitute for the ``sequenceReference`` property that references the sequence o
 Linear and Circular Sequence Coordinates
 ########################################
 
-When representing a linear sequence, it is expected that for a :ref:`Sequence` of length *n*, ``0 ≤ start ≤ end ≤ n``
+When representing a linear sequence, it is expected that for a :ref:`SequenceReference` of length *n*, ``0 ≤ start ≤ end ≤ n``
 
 For a circular sequence, ``0 ≤ end ≤ start ≤ n`` is also allowed. In cases where ``end < start``, this represents
 a location that spans the circular sequence origin coordinate.

docs/source/concepts/AdditionalDataTypes/Extension.rst

@@ -1,11 +1,18 @@
 Locations and References
 !!!!!!!!!!!!!!!!!!!!!!!!
 
-All VRS variation objects are built on :ref:`Sequence Locations<SequenceLocation>`, and
-by extension, :ref:`Sequence References<SequenceReference>`.
+.. _Location:
+
+Location
+@@@@@@@@
+
+.. include::  ../../def/vrs/Location.rst
+
+All VRS variation objects are built on :ref:`Sequence Locations<SequenceLocation>`
+and, by extension all references are built on, :ref:`Sequence References<SequenceReference>`.
 
 .. toctree::
-   :titlesonly:
+   :maxdepth: 1
 
    SequenceLocation
-   SequenceReference
+   SequenceReference

docs/source/concepts/AdditionalDataTypes/index.rst

@@ -76,5 +76,5 @@ Expressions
 
 .. admonition:: New in v2
 
-    The v2 :ref:`variation` classes now support :ref:`expressions`. This is a convenient mechanism for annotating Alleles using
+    The v2 :ref:`Variation` classes now support :ref:`Expression`. This is a convenient mechanism for annotating Alleles using
     string syntaxes following the conventions other variant standards (e.g. HGVS, SPDI) and resources (e.g. ClinVar, gnomAD).

docs/source/concepts/AdditionalDataTypes/iriReference.rst

@@ -5,6 +5,9 @@ Length Expression
 
 .. admonition:: New in V2
 
+    The `LengthExpression` class is new in VRS v2, and was designed as a means for
+    handling unknown sequence content with known length.  
+
 A length expression is used to represent molecular sequences with known length
 but unknown sequence content, typically as determined by molecular weight assays
 (e.g. gel electrophoresis).

docs/source/concepts/LocationAndReference/SequenceLocation.rst

@@ -12,8 +12,6 @@ Definition and Information Model
 
 .. include::  ../../def/vrs/CopyNumberCount.rst
 
-.. _CopyNumberCount:
-
 Example
 @@@@@@@
 

docs/source/concepts/LocationAndReference/index.rst

@@ -259,15 +259,13 @@ For example, the identifier for the allele example under :ref:`digest-serializat
 
    ga4gh\:VA.0AePZIWZUNsUlQTamyLrjm2HWUw2opLt\_
 
-.. warning::
-
-GA4GH Computed Identifiers are a key mechanism for globally unique federated identification of variants.
-However, as described here, these identifiers are dependent upon the structure of the object from which
-the identifier is constructed. Consequently, there is no guarantee that VRS computed identifiers will
-remain stable across major version releases of VRS; for example, all VRS v1.x computed identifiers are
-distinct from all VRS v2.x identifiers. It is recommended that implementers heed the maturity level of
-data classes as defined by the :ref:`maturity-model` when gauging the stability of data classes-and
-therefore object identifiers from those classes-across releases of VRS.
+.. warning:: GA4GH Computed Identifiers are a key mechanism for globally unique federated identification of variants. \
+    However, as described here, these identifiers are dependent upon the structure of the object from which \
+    the identifier is constructed. Consequently, there is no guarantee that VRS computed identifiers will \
+    remain stable across major version releases of VRS; for example, all VRS v1.x computed identifiers are \
+    distinct from all VRS v2.x identifiers. It is recommended that implementers heed the maturity level of \
+    data classes as defined by the :ref:`maturity-model` when gauging the stability of data classes-and \
+    therefore object identifiers from those classes-across releases of VRS.
 
 References
 @@@@@@@@@@

docs/source/concepts/MolecularVariation/Allele.rst

@@ -103,7 +103,7 @@ VRS JSON Schema.
 
 
 Generate a computed identifier
-@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
 A key feature of VRS is an easily-implemented algorithm to
 generate computed, digest-based identifiers for variation objects.

docs/source/concepts/SequenceExpression/LengthExpression.rst

@@ -39,6 +39,3 @@ The machine readable schema definitions and example code are available online at
 repository (https://github.com/ga4gh/vrs).
 
 Readers may wish to view a :ref:`complete example <example>` before reading the specification.
-
-For a discussion of VRS with respect to existing standards, such as HGVS, SPDI, and VCF, see
-:ref:`relationships`.

docs/source/concepts/SystemicVariation/CopyNumberCount.rst

@@ -41,7 +41,7 @@ Some Adjacency attributes are inherited from :ref:`Variation`.
       - 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
+   *  - name
       - 
       - string
       - 0..1
@@ -51,7 +51,7 @@ Some Adjacency attributes are inherited from :ref:`Variation`.
       - string
       - 0..1
       - A free-text description of the Entity.
-   *  - alternativeLabels
+   *  - aliases
       - 
                         .. raw:: html
 

docs/source/conventions/computed_identifiers.rst

@@ -41,7 +41,7 @@ Some Allele attributes are inherited from :ref:`Variation`.
       - 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
+   *  - name
       - 
       - string
       - 0..1
@@ -51,7 +51,7 @@ Some Allele attributes are inherited from :ref:`Variation`.
       - string
       - 0..1
       - A free-text description of the Entity.
-   *  - alternativeLabels
+   *  - aliases
       - 
                         .. raw:: html
 

docs/source/conventions/example.rst

@@ -41,7 +41,7 @@ Some CisPhasedBlock attributes are inherited from :ref:`Variation`.
       - 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
+   *  - name
       - 
       - string
       - 0..1
@@ -51,7 +51,7 @@ Some CisPhasedBlock attributes are inherited from :ref:`Variation`.
       - string
       - 0..1
       - A free-text description of the Entity.
-   *  - alternativeLabels
+   *  - aliases
       - 
                         .. raw:: html
 

docs/source/introduction.rst

@@ -41,7 +41,7 @@ Some CopyNumberChange attributes are inherited from :ref:`Variation`.
       - 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
+   *  - name
       - 
       - string
       - 0..1
@@ -51,7 +51,7 @@ Some CopyNumberChange attributes are inherited from :ref:`Variation`.
       - string
       - 0..1
       - A free-text description of the Entity.
-   *  - alternativeLabels
+   *  - aliases
       - 
                         .. raw:: html
 

schema/vrs/def/Adjacency.rst

@@ -41,7 +41,7 @@ Some CopyNumberCount attributes are inherited from :ref:`Variation`.
       - 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
+   *  - name
       - 
       - string
       - 0..1
@@ -51,7 +51,7 @@ Some CopyNumberCount attributes are inherited from :ref:`Variation`.
       - string
       - 0..1
       - A free-text description of the Entity.
-   *  - alternativeLabels
+   *  - aliases
       - 
                         .. raw:: html
 

schema/vrs/def/Allele.rst

@@ -41,7 +41,7 @@ Some DerivativeMolecule attributes are inherited from :ref:`Variation`.
       - 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
+   *  - name
       - 
       - string
       - 0..1
@@ -51,7 +51,7 @@ Some DerivativeMolecule attributes are inherited from :ref:`Variation`.
       - string
       - 0..1
       - A free-text description of the Entity.
-   *  - alternativeLabels
+   *  - aliases
       - 
                         .. raw:: html
 

schema/vrs/def/CisPhasedBlock.rst

@@ -46,7 +46,7 @@ Some Ga4ghIdentifiableObject attributes are inherited from :ref:`gks-core:Entity
       - string
       - 1..1
       - 
-   *  - label
+   *  - name
       - 
       - string
       - 0..1
@@ -56,7 +56,7 @@ Some Ga4ghIdentifiableObject attributes are inherited from :ref:`gks-core:Entity
       - string
       - 0..1
       - A free-text description of the Entity.
-   *  - alternativeLabels
+   *  - aliases
       - 
                         .. raw:: html
 

schema/vrs/def/CopyNumberChange.rst

@@ -41,7 +41,7 @@ Some LengthExpression attributes are inherited from :ref:`SequenceExpression`.
       - 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
+   *  - name
       - 
       - string
       - 0..1
@@ -51,7 +51,7 @@ Some LengthExpression attributes are inherited from :ref:`SequenceExpression`.
       - string
       - 0..1
       - A free-text description of the Entity.
-   *  - alternativeLabels
+   *  - aliases
       - 
                         .. raw:: html