From 7b2c07a6ff1488b77e5733cb2a4bcb69cbdd4d86 Mon Sep 17 00:00:00 2001 From: James Stevenson Date: Fri, 20 Dec 2024 10:55:08 -0500 Subject: [PATCH 1/7] hm... --- schema/vrs/def/Adjacency.rst | 39 ++++++-------------- schema/vrs/def/Allele.rst | 37 ++++++------------- schema/vrs/def/CisPhasedBlock.rst | 37 ++++++------------- schema/vrs/def/CopyNumberChange.rst | 37 ++++++------------- schema/vrs/def/CopyNumberCount.rst | 37 ++++++------------- schema/vrs/def/DerivativeMolecule.rst | 37 ++++++------------- schema/vrs/def/Ga4ghIdentifiableObject.rst | 31 ++++------------ schema/vrs/def/LengthExpression.rst | 29 ++++----------- schema/vrs/def/LiteralSequenceExpression.rst | 29 ++++----------- schema/vrs/def/ReferenceLengthExpression.rst | 33 +++++------------ schema/vrs/def/SequenceExpression.rst | 27 +++----------- schema/vrs/def/SequenceLocation.rst | 37 ++++++------------- schema/vrs/def/SequenceReference.rst | 37 ++++++------------- schema/vrs/def/Terminus.rst | 35 +++++------------- schema/vrs/def/TraversalBlock.rst | 31 ++++------------ schema/vrs/def/Variation.rst | 35 +++++------------- schema/vrs/json/Adjacency | 5 +-- schema/vrs/json/Allele | 5 +-- schema/vrs/json/CisPhasedBlock | 5 +-- schema/vrs/json/CopyNumberChange | 5 +-- schema/vrs/json/CopyNumberCount | 5 +-- schema/vrs/json/DerivativeMolecule | 5 +-- schema/vrs/json/LengthExpression | 5 +-- schema/vrs/json/LiteralSequenceExpression | 5 +-- schema/vrs/json/ReferenceLengthExpression | 5 +-- schema/vrs/json/SequenceExpression | 7 +++- schema/vrs/json/SequenceLocation | 7 ++-- schema/vrs/json/Terminus | 5 +-- 28 files changed, 183 insertions(+), 429 deletions(-) diff --git a/schema/vrs/def/Adjacency.rst b/schema/vrs/def/Adjacency.rst index 348cdb84..8fb386f6 100644 --- a/schema/vrs/def/Adjacency.rst +++ b/schema/vrs/def/Adjacency.rst @@ -6,21 +6,6 @@ The `Adjacency` class represents the adjoining of the end of a sequence with the beginning of an adjacent sequence, potentially with an intervening linker sequence. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - AJ - - ['adjoinedSequences', 'linker', 'type'] - - **Information Model** Some Adjacency attributes are inherited from :ref:`Variation`. @@ -37,22 +22,22 @@ Some Adjacency attributes are inherited from :ref:`Variation`. - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some Adjacency attributes are inherited from :ref:`Variation`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,25 +53,25 @@ Some Adjacency attributes are inherited from :ref:`Variation`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - digest - - + - - string - 0..1 - A sha512t24u digest created using the VRS Computed Identifier algorithm. * - expressions - - + - .. raw:: html ⋮ - :ref:`Expression` - 0..m - - + - * - type - - + - - string - 1..1 - MUST be "Adjacency". * - adjoinedSequences - - + - .. raw:: html ↓ @@ -94,12 +79,12 @@ Some Adjacency attributes are inherited from :ref:`Variation`. - 2..2 - The terminal sequence or pair of adjoined sequences that defines in the adjacency. * - linker - - + - - :ref:`SequenceExpression` - 0..1 - The sequence found between adjoined sequences. * - homology - - + - .. raw:: html D diff --git a/schema/vrs/def/Allele.rst b/schema/vrs/def/Allele.rst index 1373e901..a2ee0025 100644 --- a/schema/vrs/def/Allele.rst +++ b/schema/vrs/def/Allele.rst @@ -6,21 +6,6 @@ The state of a molecule at a :ref:`Location`. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - VA - - ['location', 'state', 'type'] - - **Information Model** Some Allele attributes are inherited from :ref:`Variation`. @@ -37,22 +22,22 @@ Some Allele attributes are inherited from :ref:`Variation`. - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some Allele attributes are inherited from :ref:`Variation`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,30 +53,30 @@ Some Allele attributes are inherited from :ref:`Variation`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - digest - - + - - string - 0..1 - A sha512t24u digest created using the VRS Computed Identifier algorithm. * - expressions - - + - .. raw:: html ⋮ - :ref:`Expression` - 0..m - - + - * - type - - + - - string - 1..1 - MUST be "Allele" * - location - - + - - :ref:`iriReference` | :ref:`Location` - 1..1 - The location of the Allele * - state - - + - - :ref:`SequenceExpression` - 1..1 - An expression of the sequence state diff --git a/schema/vrs/def/CisPhasedBlock.rst b/schema/vrs/def/CisPhasedBlock.rst index 1d1a5da7..b27b7f52 100644 --- a/schema/vrs/def/CisPhasedBlock.rst +++ b/schema/vrs/def/CisPhasedBlock.rst @@ -6,21 +6,6 @@ An ordered set of co-occurring :ref:`variants ` on the same molecule. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - CPB - - ['members', 'type'] - - **Information Model** Some CisPhasedBlock attributes are inherited from :ref:`Variation`. @@ -37,22 +22,22 @@ Some CisPhasedBlock attributes are inherited from :ref:`Variation`. - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some CisPhasedBlock attributes are inherited from :ref:`Variation`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,25 +53,25 @@ Some CisPhasedBlock attributes are inherited from :ref:`Variation`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - digest - - + - - string - 0..1 - A sha512t24u digest created using the VRS Computed Identifier algorithm. * - expressions - - + - .. raw:: html ⋮ - :ref:`Expression` - 0..m - - + - * - type - - + - - string - 1..1 - MUST be "CisPhasedBlock" * - members - - + - .. raw:: html ⋮ @@ -94,7 +79,7 @@ Some CisPhasedBlock attributes are inherited from :ref:`Variation`. - 2..m - A list of :ref:`Alleles ` that are found in-cis on a shared molecule. * - sequenceReference - - + - - :ref:`SequenceReference` - 0..1 - An optional Sequence Reference on which all of the in-cis Alleles are found. When defined, this may be used to implicitly define the `sequenceReference` attribute for each of the CisPhasedBlock member Alleles. diff --git a/schema/vrs/def/CopyNumberChange.rst b/schema/vrs/def/CopyNumberChange.rst index 94a206ef..6f1c3367 100644 --- a/schema/vrs/def/CopyNumberChange.rst +++ b/schema/vrs/def/CopyNumberChange.rst @@ -6,21 +6,6 @@ An assessment of the copy number of a :ref:`Location` within a system (e.g. genome, cell, etc.) relative to a baseline ploidy. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - CX - - ['copyChange', 'location', 'type'] - - **Information Model** Some CopyNumberChange attributes are inherited from :ref:`Variation`. @@ -37,22 +22,22 @@ Some CopyNumberChange attributes are inherited from :ref:`Variation`. - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some CopyNumberChange attributes are inherited from :ref:`Variation`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,30 +53,30 @@ Some CopyNumberChange attributes are inherited from :ref:`Variation`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - digest - - + - - string - 0..1 - A sha512t24u digest created using the VRS Computed Identifier algorithm. * - expressions - - + - .. raw:: html ⋮ - :ref:`Expression` - 0..m - - + - * - type - - + - - string - 1..1 - MUST be "CopyNumberChange" * - location - - + - - :ref:`iriReference` | :ref:`Location` - 1..1 - The location of the subject of the copy change. * - copyChange - - + - - :ref:`MappableConcept` - 1..1 - MUST use a `primaryCode` representing one of "EFO:0030069" (complete genomic loss), "EFO:0020073" (high-level loss), "EFO:0030068" (low-level loss), "EFO:0030067" (loss), "EFO:0030064" (regional base ploidy), "EFO:0030070" (gain), "EFO:0030071" (low-level gain), "EFO:0030072" (high-level gain). diff --git a/schema/vrs/def/CopyNumberCount.rst b/schema/vrs/def/CopyNumberCount.rst index a61532bd..f24f20a2 100644 --- a/schema/vrs/def/CopyNumberCount.rst +++ b/schema/vrs/def/CopyNumberCount.rst @@ -6,21 +6,6 @@ The absolute count of discrete copies of a :ref:`Location` within a system (e.g. genome, cell, etc.). -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - CN - - ['copies', 'location', 'type'] - - **Information Model** Some CopyNumberCount attributes are inherited from :ref:`Variation`. @@ -37,22 +22,22 @@ Some CopyNumberCount attributes are inherited from :ref:`Variation`. - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some CopyNumberCount attributes are inherited from :ref:`Variation`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,30 +53,30 @@ Some CopyNumberCount attributes are inherited from :ref:`Variation`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - digest - - + - - string - 0..1 - A sha512t24u digest created using the VRS Computed Identifier algorithm. * - expressions - - + - .. raw:: html ⋮ - :ref:`Expression` - 0..m - - + - * - type - - + - - string - 1..1 - MUST be "CopyNumberCount" * - location - - + - - :ref:`iriReference` | :ref:`Location` - 1..1 - The location of the subject of the copy count. * - copies - - + - - integer | :ref:`Range` - 1..1 - The integral number of copies of the subject in a system diff --git a/schema/vrs/def/DerivativeMolecule.rst b/schema/vrs/def/DerivativeMolecule.rst index f05a6683..76bcaec0 100644 --- a/schema/vrs/def/DerivativeMolecule.rst +++ b/schema/vrs/def/DerivativeMolecule.rst @@ -6,21 +6,6 @@ A molecule derived from segments of multiple adjoined molecular sequences, typically resulting from structural variation. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - DM - - ['components', 'type'] - - **Information Model** Some DerivativeMolecule attributes are inherited from :ref:`Variation`. @@ -37,22 +22,22 @@ Some DerivativeMolecule attributes are inherited from :ref:`Variation`. - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some DerivativeMolecule attributes are inherited from :ref:`Variation`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,25 +53,25 @@ Some DerivativeMolecule attributes are inherited from :ref:`Variation`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - digest - - + - - string - 0..1 - A sha512t24u digest created using the VRS Computed Identifier algorithm. * - expressions - - + - .. raw:: html ⋮ - :ref:`Expression` - 0..m - - + - * - type - - + - - string - 1..1 - MUST be "DerivativeMolecule". * - components - - + - .. raw:: html ↓ @@ -94,7 +79,7 @@ Some DerivativeMolecule attributes are inherited from :ref:`Variation`. - 2..m - The molecular components that constitute the derivative molecule. * - circular - - + - - boolean - 0..1 - A boolean indicating whether the molecule represented by the sequence is circular (true) or linear (false). diff --git a/schema/vrs/def/Ga4ghIdentifiableObject.rst b/schema/vrs/def/Ga4ghIdentifiableObject.rst index 7acf6779..ac647fad 100644 --- a/schema/vrs/def/Ga4ghIdentifiableObject.rst +++ b/schema/vrs/def/Ga4ghIdentifiableObject.rst @@ -6,21 +6,6 @@ An object for which a GA4GH computed identifier can be created. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - None - - ['type'] - - **Information Model** Some Ga4ghIdentifiableObject attributes are inherited from :ref:`gks-core:Entity`. @@ -37,27 +22,27 @@ Some Ga4ghIdentifiableObject attributes are inherited from :ref:`gks-core:Entity - 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 - - + - * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -65,7 +50,7 @@ Some Ga4ghIdentifiableObject attributes are inherited from :ref:`gks-core:Entity - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -73,7 +58,7 @@ Some Ga4ghIdentifiableObject attributes are inherited from :ref:`gks-core:Entity - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - digest - - + - - string - 0..1 - A sha512t24u digest created using the VRS Computed Identifier algorithm. diff --git a/schema/vrs/def/LengthExpression.rst b/schema/vrs/def/LengthExpression.rst index 25c8bfde..0377dd16 100644 --- a/schema/vrs/def/LengthExpression.rst +++ b/schema/vrs/def/LengthExpression.rst @@ -6,21 +6,6 @@ A sequence expressed only by its length. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - None - - ['length', 'type'] - - **Information Model** Some LengthExpression attributes are inherited from :ref:`SequenceExpression`. @@ -37,22 +22,22 @@ Some LengthExpression attributes are inherited from :ref:`SequenceExpression`. - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some LengthExpression attributes are inherited from :ref:`SequenceExpression`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,12 +53,12 @@ Some LengthExpression attributes are inherited from :ref:`SequenceExpression`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - type - - + - - string - 1..1 - MUST be "LengthExpression" * - length - - + - - :ref:`Range` | integer - 0..1 - The length of the sequence. diff --git a/schema/vrs/def/LiteralSequenceExpression.rst b/schema/vrs/def/LiteralSequenceExpression.rst index 8a374181..b7543165 100644 --- a/schema/vrs/def/LiteralSequenceExpression.rst +++ b/schema/vrs/def/LiteralSequenceExpression.rst @@ -6,21 +6,6 @@ An explicit expression of a Sequence. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - None - - ['sequence', 'type'] - - **Information Model** Some LiteralSequenceExpression attributes are inherited from :ref:`SequenceExpression`. @@ -37,22 +22,22 @@ Some LiteralSequenceExpression attributes are inherited from :ref:`SequenceExpre - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some LiteralSequenceExpression attributes are inherited from :ref:`SequenceExpre - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,12 +53,12 @@ Some LiteralSequenceExpression attributes are inherited from :ref:`SequenceExpre - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - type - - + - - string - 1..1 - MUST be "LiteralSequenceExpression" * - sequence - - + - - :ref:`sequenceString` - 1..1 - the literal sequence diff --git a/schema/vrs/def/ReferenceLengthExpression.rst b/schema/vrs/def/ReferenceLengthExpression.rst index 9b940929..80987e58 100644 --- a/schema/vrs/def/ReferenceLengthExpression.rst +++ b/schema/vrs/def/ReferenceLengthExpression.rst @@ -6,21 +6,6 @@ An expression of a sequence that is derived from repeating a subsequence of an associated :ref:`SequenceLocation`. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - None - - ['length', 'repeatSubunitLength', 'type'] - - **Information Model** Some ReferenceLengthExpression attributes are inherited from :ref:`SequenceExpression`. @@ -37,22 +22,22 @@ Some ReferenceLengthExpression attributes are inherited from :ref:`SequenceExpre - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some ReferenceLengthExpression attributes are inherited from :ref:`SequenceExpre - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,22 +53,22 @@ Some ReferenceLengthExpression attributes are inherited from :ref:`SequenceExpre - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - type - - + - - string - 1..1 - MUST be "ReferenceLengthExpression" * - length - - + - - integer | :ref:`Range` - 1..1 - The number of residues in the expressed sequence. * - sequence - - + - - :ref:`sequenceString` - 0..1 - the literal :ref:`Sequence` encoded by the Reference Length Expression. * - repeatSubunitLength - - + - - integer - 1..1 - The number of residues in the repeat subunit. diff --git a/schema/vrs/def/SequenceExpression.rst b/schema/vrs/def/SequenceExpression.rst index e1694e44..48367476 100644 --- a/schema/vrs/def/SequenceExpression.rst +++ b/schema/vrs/def/SequenceExpression.rst @@ -6,21 +6,6 @@ An expression describing a :ref:`Sequence`. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - None - - ['type'] - - **Information Model** Some SequenceExpression attributes are inherited from :ref:`gks-core:Entity`. @@ -37,22 +22,22 @@ Some SequenceExpression attributes are inherited from :ref:`gks-core:Entity`. - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some SequenceExpression attributes are inherited from :ref:`gks-core:Entity`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,7 +53,7 @@ Some SequenceExpression attributes are inherited from :ref:`gks-core:Entity`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - type - - + - - string - 1..1 - The SequenceExpression class type. MUST match child class type. diff --git a/schema/vrs/def/SequenceLocation.rst b/schema/vrs/def/SequenceLocation.rst index b70f7cf6..40e02707 100644 --- a/schema/vrs/def/SequenceLocation.rst +++ b/schema/vrs/def/SequenceLocation.rst @@ -6,21 +6,6 @@ A :ref:`Location` defined by an interval on a referenced :ref:`Sequence`. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - SL - - ['end', 'sequenceReference', 'start', 'type'] - - **Information Model** Some SequenceLocation attributes are inherited from :ref:`Ga4ghIdentifiableObject`. @@ -37,22 +22,22 @@ Some SequenceLocation attributes are inherited from :ref:`Ga4ghIdentifiableObjec - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some SequenceLocation attributes are inherited from :ref:`Ga4ghIdentifiableObjec - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,32 +53,32 @@ Some SequenceLocation attributes are inherited from :ref:`Ga4ghIdentifiableObjec - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - digest - - + - - string - 0..1 - A sha512t24u digest created using the VRS Computed Identifier algorithm. * - type - - + - - string - 1..1 - MUST be "SequenceLocation" * - sequenceReference - - + - - :ref:`iriReference` | :ref:`SequenceReference` - 0..1 - A reference to a :ref:`Sequence` on which the location is defined. * - start - - + - - integer | :ref:`Range` - 0..1 - The start coordinate or range of the SequenceLocation. The minimum value of this coordinate or range is 0. For locations on linear sequences, this MUST represent a coordinate or range less than or equal to the value of `end`. For circular sequences, `start` is greater than `end` when the location spans the sequence 0 coordinate. * - end - - + - - integer | :ref:`Range` - 0..1 - The end coordinate or range of the SequenceLocation. The minimum value of this coordinate or range is 0. For locations on linear sequences, this MUST represent a coordinate or range grater than or equal to the value of `start`. For circular sequences, `end` is less than `start` when the location spans the sequence 0 coordinate. * - sequence - - + - - :ref:`sequenceString` - 0..1 - The literal sequence encoded by the `sequenceReference` at these coordinates. diff --git a/schema/vrs/def/SequenceReference.rst b/schema/vrs/def/SequenceReference.rst index d5e9b814..b51eb244 100644 --- a/schema/vrs/def/SequenceReference.rst +++ b/schema/vrs/def/SequenceReference.rst @@ -6,21 +6,6 @@ A sequence of nucleic or amino acid character codes. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - None - - ['refgetAccession', 'type'] - - **Information Model** Some SequenceReference attributes are inherited from :ref:`gks-core:Entity`. @@ -37,22 +22,22 @@ Some SequenceReference attributes are inherited from :ref:`gks-core:Entity`. - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some SequenceReference attributes are inherited from :ref:`gks-core:Entity`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,32 +53,32 @@ Some SequenceReference attributes are inherited from :ref:`gks-core:Entity`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - type - - + - - string - 1..1 - MUST be "SequenceReference" * - refgetAccession - - + - - string - 1..1 - A `GA4GH RefGet `_ identifier for the referenced sequence, using the sha512t24u digest. * - residueAlphabet - - + - - string - 0..1 - The interpretation of the character codes referred to by the refget accession, where "aa" specifies an amino acid character set, and "na" specifies a nucleic acid character set. * - sequence - - + - - :ref:`sequenceString` - 0..1 - A :ref:`sequenceString` that is a literal representation of the referenced sequence. * - moleculeType - - + - - string - 0..1 - Molecule types as `defined by RefSeq `_ (see Table 1). MUST be one of "genomic", "RNA", "mRNA", or "protein". * - circular - - + - - boolean - 0..1 - A boolean indicating whether the molecule represented by the sequence is circular (true) or linear (false). diff --git a/schema/vrs/def/Terminus.rst b/schema/vrs/def/Terminus.rst index be7e2305..67cdb42a 100644 --- a/schema/vrs/def/Terminus.rst +++ b/schema/vrs/def/Terminus.rst @@ -6,21 +6,6 @@ The `Terminus` data class provides a structure for describing the end (terminus) of a molecule. Structurally similar to Adjacency, but used for describing where a molecule terminates (instead of adjoining another molecule). -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - TM - - ['location', 'type'] - - **Information Model** Some Terminus attributes are inherited from :ref:`Variation`. @@ -37,22 +22,22 @@ Some Terminus attributes are inherited from :ref:`Variation`. - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some Terminus attributes are inherited from :ref:`Variation`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,25 +53,25 @@ Some Terminus attributes are inherited from :ref:`Variation`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - digest - - + - - string - 0..1 - A sha512t24u digest created using the VRS Computed Identifier algorithm. * - expressions - - + - .. raw:: html ⋮ - :ref:`Expression` - 0..m - - + - * - type - - + - - string - 1..1 - MUST be "Terminus". * - location - - + - - :ref:`iriReference` | :ref:`Location` - 1..1 - The location of the terminus. diff --git a/schema/vrs/def/TraversalBlock.rst b/schema/vrs/def/TraversalBlock.rst index f5e72f2a..84f80bc6 100644 --- a/schema/vrs/def/TraversalBlock.rst +++ b/schema/vrs/def/TraversalBlock.rst @@ -6,21 +6,6 @@ A component used to describe the orientation of applicable molecular variation within a DerivativeMolecule. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - None - - ['type', 'component', 'orientation'] - - **Information Model** Some TraversalBlock attributes are inherited from :ref:`gks-core:Entity`. @@ -37,22 +22,22 @@ Some TraversalBlock attributes are inherited from :ref:`gks-core:Entity`. - 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. * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -60,7 +45,7 @@ Some TraversalBlock attributes are inherited from :ref:`gks-core:Entity`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -68,17 +53,17 @@ Some TraversalBlock attributes are inherited from :ref:`gks-core:Entity`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - type - - + - - string - 1..1 - MUST be "TraversalBlock". * - component - - + - - :ref:`Adjacency` - 0..1 - The unoriented molecular variation component. * - orientation - - + - - string - 0..1 - The orientation of the molecular variation component. diff --git a/schema/vrs/def/Variation.rst b/schema/vrs/def/Variation.rst index df42b05c..df836bf4 100644 --- a/schema/vrs/def/Variation.rst +++ b/schema/vrs/def/Variation.rst @@ -6,21 +6,6 @@ A representation of the state of one or more biomolecules. -**GA4GH Digest** - -.. list-table:: - :class: clean-wrap - :header-rows: 1 - :align: left - :widths: auto - - * - Prefix - - Inherent - - * - None - - ['type'] - - **Information Model** Some Variation attributes are inherited from :ref:`Ga4ghIdentifiableObject`. @@ -37,27 +22,27 @@ Some Variation attributes are inherited from :ref:`Ga4ghIdentifiableObject`. - 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 - - + - * - label - - + - - string - 0..1 - A primary name for the entity. * - description - - + - - string - 0..1 - A free-text description of the Entity. * - alternativeLabels - - + - .. raw:: html ⋮ @@ -65,7 +50,7 @@ Some Variation attributes are inherited from :ref:`Ga4ghIdentifiableObject`. - 0..m - Alternative name(s) for the Entity. * - extensions - - + - .. raw:: html ⋮ @@ -73,15 +58,15 @@ Some Variation attributes are inherited from :ref:`Ga4ghIdentifiableObject`. - 0..m - A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model. * - digest - - + - - string - 0..1 - A sha512t24u digest created using the VRS Computed Identifier algorithm. * - expressions - - + - .. raw:: html ⋮ - :ref:`Expression` - 0..m - - + - diff --git a/schema/vrs/json/Adjacency b/schema/vrs/json/Adjacency index 6903ec45..4a844304 100644 --- a/schema/vrs/json/Adjacency +++ b/schema/vrs/json/Adjacency @@ -8,8 +8,7 @@ "prefix": "AJ", "inherent": [ "adjoinedSequences", - "linker", - "type" + "linker" ] }, "description": "The `Adjacency` class represents the adjoining of the end of a sequence with the beginning of an adjacent sequence, potentially with an intervening linker sequence.", @@ -111,4 +110,4 @@ "type" ], "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/vrs/json/Allele b/schema/vrs/json/Allele index 537daca3..ea571670 100644 --- a/schema/vrs/json/Allele +++ b/schema/vrs/json/Allele @@ -8,8 +8,7 @@ "prefix": "VA", "inherent": [ "location", - "state", - "type" + "state" ] }, "description": "The state of a molecule at a Location.", @@ -94,4 +93,4 @@ "type" ], "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/vrs/json/CisPhasedBlock b/schema/vrs/json/CisPhasedBlock index bbe0765d..816c91f7 100644 --- a/schema/vrs/json/CisPhasedBlock +++ b/schema/vrs/json/CisPhasedBlock @@ -7,8 +7,7 @@ "ga4gh": { "prefix": "CPB", "inherent": [ - "members", - "type" + "members" ] }, "description": "An ordered set of co-occurring variants on the same molecule.", @@ -88,4 +87,4 @@ "type" ], "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/vrs/json/CopyNumberChange b/schema/vrs/json/CopyNumberChange index 39997509..1380ca0b 100644 --- a/schema/vrs/json/CopyNumberChange +++ b/schema/vrs/json/CopyNumberChange @@ -6,9 +6,8 @@ "maturity": "draft", "ga4gh": { "inherent": [ - "copyChange", "location", - "type" + "copyChange" ], "prefix": "CX" }, @@ -84,4 +83,4 @@ "type" ], "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/vrs/json/CopyNumberCount b/schema/vrs/json/CopyNumberCount index 10ec1cff..5f57b2a4 100644 --- a/schema/vrs/json/CopyNumberCount +++ b/schema/vrs/json/CopyNumberCount @@ -6,9 +6,8 @@ "maturity": "trial use", "ga4gh": { "inherent": [ - "copies", "location", - "type" + "copies" ], "prefix": "CN" }, @@ -91,4 +90,4 @@ "type" ], "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/vrs/json/DerivativeMolecule b/schema/vrs/json/DerivativeMolecule index fb810c3c..4f822e3c 100644 --- a/schema/vrs/json/DerivativeMolecule +++ b/schema/vrs/json/DerivativeMolecule @@ -7,8 +7,7 @@ "ga4gh": { "prefix": "DM", "inherent": [ - "components", - "type" + "components" ] }, "description": "A molecule derived from segments of multiple adjoined molecular sequences, typically resulting from structural variation.", @@ -97,4 +96,4 @@ "type" ], "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/vrs/json/LengthExpression b/schema/vrs/json/LengthExpression index ec133eae..f4475d41 100644 --- a/schema/vrs/json/LengthExpression +++ b/schema/vrs/json/LengthExpression @@ -6,8 +6,7 @@ "maturity": "draft", "ga4gh": { "inherent": [ - "length", - "type" + "length" ] }, "description": "A sequence expressed only by its length.", @@ -65,4 +64,4 @@ "type" ], "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/vrs/json/LiteralSequenceExpression b/schema/vrs/json/LiteralSequenceExpression index 033bdadf..f12e32f5 100644 --- a/schema/vrs/json/LiteralSequenceExpression +++ b/schema/vrs/json/LiteralSequenceExpression @@ -6,8 +6,7 @@ "maturity": "trial use", "ga4gh": { "inherent": [ - "sequence", - "type" + "sequence" ] }, "description": "An explicit expression of a Sequence.", @@ -59,4 +58,4 @@ "type" ], "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/vrs/json/ReferenceLengthExpression b/schema/vrs/json/ReferenceLengthExpression index d550e0ad..c20d10b6 100644 --- a/schema/vrs/json/ReferenceLengthExpression +++ b/schema/vrs/json/ReferenceLengthExpression @@ -7,8 +7,7 @@ "ga4gh": { "inherent": [ "length", - "repeatSubunitLength", - "type" + "repeatSubunitLength" ] }, "description": "An expression of a sequence that is derived from repeating a subsequence of an associated SequenceLocation.", @@ -76,4 +75,4 @@ "type" ], "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/vrs/json/SequenceExpression b/schema/vrs/json/SequenceExpression index 2f58952f..66041d3a 100644 --- a/schema/vrs/json/SequenceExpression +++ b/schema/vrs/json/SequenceExpression @@ -4,6 +4,11 @@ "title": "SequenceExpression", "type": "object", "maturity": "trial use", + "ga4gh": { + "inherent": [ + "type" + ] + }, "description": "An expression describing a Sequence.", "oneOf": [ { @@ -19,4 +24,4 @@ "discriminator": { "propertyName": "type" } -} \ No newline at end of file +} diff --git a/schema/vrs/json/SequenceLocation b/schema/vrs/json/SequenceLocation index e115dfc6..303f20bc 100644 --- a/schema/vrs/json/SequenceLocation +++ b/schema/vrs/json/SequenceLocation @@ -6,10 +6,9 @@ "maturity": "trial use", "ga4gh": { "inherent": [ - "end", - "sequenceReference", "start", - "type" + "end", + "sequenceReference" ], "prefix": "SL" }, @@ -98,4 +97,4 @@ "type" ], "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/vrs/json/Terminus b/schema/vrs/json/Terminus index b3682127..91b4048f 100644 --- a/schema/vrs/json/Terminus +++ b/schema/vrs/json/Terminus @@ -7,8 +7,7 @@ "ga4gh": { "prefix": "TM", "inherent": [ - "location", - "type" + "location" ] }, "description": "The `Terminus` data class provides a structure for describing the end (terminus) of a molecule. Structurally similar to Adjacency, but used for describing where a molecule terminates (instead of adjoining another molecule).", @@ -78,4 +77,4 @@ "type" ], "additionalProperties": false -} \ No newline at end of file +} From d089e4233f5715b931f69f0749b1189a8f942673 Mon Sep 17 00:00:00 2001 From: James Stevenson Date: Fri, 20 Dec 2024 11:03:22 -0500 Subject: [PATCH 2/7] cicd: add precommit to actions --- .github/workflows/cqa.yaml | 22 ++++++++++++++++++++++ .pre-commit-config.yaml | 2 ++ 2 files changed, 24 insertions(+) create mode 100644 .github/workflows/cqa.yaml diff --git a/.github/workflows/cqa.yaml b/.github/workflows/cqa.yaml new file mode 100644 index 00000000..c3d6d48c --- /dev/null +++ b/.github/workflows/cqa.yaml @@ -0,0 +1,22 @@ +name: checks +on: [push, pull_request] +jobs: + precommit_hooks: + runs-on: ubuntu-latest + strategy: + matrix: + - cmd: "end-of-file-fixer" + - cmd: "trailing-whitespace" + - cmd: "mixed-line-ending" + - cmd: "update-json-def-files" + steps: + - uses: actions/checkout@v4 + + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: 3.12 + + - uses: pre-commit/action@v3.0.1 + with: + extra_args: ${{ matrix.cmd }} --all-files diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index adc166be..bc77fdec 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -6,6 +6,8 @@ repos: - id: detect-private-key - id: trailing-whitespace - id: end-of-file-fixer + - id: mixed-line-ending + args: [ --fix=lf ] - repo: local hooks: - id: update-json-def-files From 27cd74a436cb0e8f90b25d1f25af92b3db124a21 Mon Sep 17 00:00:00 2001 From: James Stevenson Date: Fri, 20 Dec 2024 11:11:08 -0500 Subject: [PATCH 3/7] omg --- .github/workflows/cqa.yaml | 3 +- CONTRIBUTING.md | 16 +- CONTRIBUTORS.md | 2 +- README.md | 2 +- TODO | 4 +- docs/source/appendices/design_decisions.rst | 27 ++- docs/source/appendices/ga4gh_identifiers.rst | 6 +- docs/source/appendices/maturity_model.rst | 154 +++++++++--------- .../appendices/resource_identifiers.rst | 8 +- .../concepts/AdditionalDataTypes/index.rst | 2 +- .../LocationAndReference/SequenceLocation.rst | 8 +- .../SequenceReference.rst | 2 +- .../concepts/LocationAndReference/index.rst | 4 +- .../MolecularVariation/DerivativeMolecule.rst | 2 +- .../ReferenceLengthExpression.rst | 2 +- .../concepts/SystemicVariation/CopyNumber.rst | 6 +- docs/source/concepts/index.rst | 1 - .../conventions/computed_identifiers.rst | 2 +- docs/source/conventions/index.rst | 1 - docs/source/images/GA-logo.svg | 70 ++++---- docs/source/releases/index.rst | 4 +- examples/sv_derivative_molecule.yaml | 11 +- schema/vrs/def/SequenceLocation.rst | 4 +- schema/vrs/json/SequenceLocation | 4 +- schema/vrs/vrs-source.yaml | 6 +- tests/test_examples.py | 2 +- validation/models.yaml | 2 +- 27 files changed, 174 insertions(+), 181 deletions(-) diff --git a/.github/workflows/cqa.yaml b/.github/workflows/cqa.yaml index c3d6d48c..241d2d20 100644 --- a/.github/workflows/cqa.yaml +++ b/.github/workflows/cqa.yaml @@ -5,8 +5,9 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - - cmd: "end-of-file-fixer" + - cmd: "check-added-large-files" - cmd: "trailing-whitespace" + - cmd: "end-of-file-fixer" - cmd: "mixed-line-ending" - cmd: "update-json-def-files" steps: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a64d80d..d43d95fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,17 +1,17 @@ # Contributing Contributions to this repository are intended to follow the VRS [development process](https://vrs.ga4gh.org/en/stable/appendices/development_process.html). -The additional information presented here are guidelines for issues, -branches, commits, and pull requests. Before adding documentation, +The additional information presented here are guidelines for issues, +branches, commits, and pull requests. Before adding documentation, please also review the [docs style guide](docs/source/style.rst). ## Discussions -[Discussions](https://github.com/ga4gh/vrs/discussions) are for feature +[Discussions](https://github.com/ga4gh/vrs/discussions) are for feature requests, release candidate discussions, and questions. ## Issues [Issues](https://github.com/ga4gh/vrs/issues) are for bug -reports, and planned feature descriptions. When creating an issue, use +reports, and planned feature descriptions. When creating an issue, use sentence case for the issue title and avoid the use of periods at the end of titles. @@ -25,12 +25,12 @@ branch for [issue 250](https://github.com/ga4gh/vrs/issues/250) could be `250-contributing`. ## Pull Requests -[Pull Requests](https://github.com/ga4gh/vrs/pulls) (PRs) for new -features should target the `main` branch. For version +[Pull Requests](https://github.com/ga4gh/vrs/pulls) (PRs) for new +features should target the `main` branch. For version patches, the PR should target the appropriate minor version branch. PRs must be approved by at least one project maintainer before they may be merged. PR titles must reflect the issue associated with the PR. For -example, the associated PR title for +example, the associated PR title for [issue 250](https://github.com/ga4gh/vrs/issues/250) would be -`#250: Add CONTRIBUTING.md`, as seen in +`#250: Add CONTRIBUTING.md`, as seen in [PR #253](https://github.com/ga4gh/vrs/pull/253). diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 8a056944..363dc00f 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -42,7 +42,7 @@ |Brian Walsh | [[10](#10)] | |Andrew D Yates | [[8](#8)] | -See also +See also [VRS contributors](https://github.com/ga4gh/vrs/graphs/contributors) and [VRS Python contributors](https://github.com/ga4gh/vrs-python/graphs/contributors). diff --git a/README.md b/README.md index 53a17394..fa606841 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ The VRS model is the product of the [GA4GH Variation Representation group](https ## Using the schema -The schema is available in the [schema/](./schema/) directory, in both yaml and json versions. +The schema is available in the [schema/](./schema/) directory, in both yaml and json versions. It conforms to JSON Schema Draft 2020-12. For a list of libraries that support JSON schema, see [JSONSchema>Tools](https://json-schema.org/tools). diff --git a/TODO b/TODO index 43d60131..6eac6d15 100644 --- a/TODO +++ b/TODO @@ -1,5 +1,5 @@ # Docs see doc-updates branch * Standardize quoting: '**blah**' → ``blah`` -* Investigate -https://pypi.org/project/sphinx-jsonschema/ \ No newline at end of file +* Investigate +https://pypi.org/project/sphinx-jsonschema/ diff --git a/docs/source/appendices/design_decisions.rst b/docs/source/appendices/design_decisions.rst index 1a53bbb8..d7d386a0 100644 --- a/docs/source/appendices/design_decisions.rst +++ b/docs/source/appendices/design_decisions.rst @@ -9,14 +9,14 @@ GA4GH Inherent Properties over Value Objects -------------------------------------------- In VRS 1.0 we operated under the principle that all identifiable objects in VRS (e.g. Allele, SequenceLocation, etc.) -would be *value objects*. This meant that they should be immutable and contain only required fields that are +would be *value objects*. This meant that they should be immutable and contain only required fields that are necessary to uniquely identify the object. This approach somewhat simplified the ability to genertate the digests by allowing the computation of the digest to be based on the entire object. An exception was made for properties with a leading underscore (namely, the *_id* property), which was removed from the object before a digest was calculated. In VRS 2.0 we extended the principle of excepting designated attributes by explicitly defining *inherent properties* -that constitute the properties used to compute an object digest. This was done to enable expressivity of VRS, -enabling implementations to pass common, descriptive metadata as part of the identifiable objects without sacrificing +that constitute the properties used to compute an object digest. This was done to enable expressivity of VRS, +enabling implementations to pass common, descriptive metadata as part of the identifiable objects without sacrificing the ability to create globally unique, federated identifiers from VRS 1.3. As a result, we had to introduce a new field in the digest model called *ga4gh.inherent* which is described in detail @@ -25,13 +25,13 @@ in the section on :ref:`ga4gh-inherent-properties`. IRIs over CURIEs ---------------- -In VRS 2.0 we moved away from the use of CURIEs in favor of :ref:`iriReference`. Several factors played a role in +In VRS 2.0 we moved away from the use of CURIEs in favor of :ref:`iriReference`. Several factors played a role in this decision. -JSON Schema, the default data model for GKS specifications, does not allow for encoding of CURIE namespaces as is done -in other frameworks such as JSON-LD or XML. As a result, namespaces must be captured from custom data structures, API +JSON Schema, the default data model for GKS specifications, does not allow for encoding of CURIE namespaces as is done +in other frameworks such as JSON-LD or XML. As a result, namespaces must be captured from custom data structures, API endpoints, or documentation that may not persist as messages are exchanged between systems. To address this, references -in GKS specs now use IRIs to reference objects explicitly. +in GKS specs now use IRIs to reference objects explicitly. IRI-References over IRIs ------------------------ @@ -44,7 +44,7 @@ VRS identifier syntax and versioning The :ref:`versioning` section describes the versioning and release naming conventions for the VRS product. Approved releases will be assigned to the version number alone, but connect, ballot and snapshot releases will -include the context term and date in addition to the target version number. +include the context term and date in addition to the target version number. During the GA4GH Connect April 2023 meeting the maturity model was discussed at length and the following proposal was presented for instance and class GKS identifiers. @@ -64,13 +64,13 @@ As an example, the Github JSON Schema URL ($id) for the VRS 2.0.0 Allele is: } During the **release and versioning** discussion at the GA4GH Connect April 2023 meeting the proposal -delved into the idea of including the major version number in the VRS identifier itself. Proponents of -this approach cited concern for the change in digests (and their derived identifiers) between major -versions of the same VRS object, which would become clearly visible in the identifier itself if the +delved into the idea of including the major version number in the VRS identifier itself. Proponents of +this approach cited concern for the change in digests (and their derived identifiers) between major +versions of the same VRS object, which would become clearly visible in the identifier itself if the major version was included. -Opponents of this approach argued that new identifiers would be required for every type of VRS object -for every major version release. Meaning that even if a given type of object has no change that would +Opponents of this approach argued that new identifiers would be required for every type of VRS object +for every major version release. Meaning that even if a given type of object has no change that would result in a new digest, a new identifier would still be required for the new major version. After much discussion, the decision was made to NOT include the major version number in the VRS identifier @@ -88,4 +88,3 @@ the following syntax: .. code-block:: https://w3id.org/ga4gh/vrs/VA.Oop4kjdTtKcg1kiZjIJAAR3bp7qi4aNT - diff --git a/docs/source/appendices/ga4gh_identifiers.rst b/docs/source/appendices/ga4gh_identifiers.rst index ca4e9445..b15401ce 100644 --- a/docs/source/appendices/ga4gh_identifiers.rst +++ b/docs/source/appendices/ga4gh_identifiers.rst @@ -79,8 +79,8 @@ GA4GH Inherent Properties implementations. VRS 2.0 addresses this limitation with the designation of inherent properties for use with the computed identifier algorithm. -When creating computed identifiers from objects, VRS uses a custom schema attribute, -*ga4gh.inherent*, that contains the property names used for computing digests. For example, +When creating computed identifiers from objects, VRS uses a custom schema attribute, +*ga4gh.inherent*, that contains the property names used for computing digests. For example, the Allele JSON Schema: .. parsed-literal:: @@ -105,7 +105,7 @@ the Allele JSON Schema: .. note:: - The `ga4gh` JSON Schema namespace is aligned with the Sequence Collections effort + The `ga4gh` JSON Schema namespace is aligned with the Sequence Collections effort (see `SeqCol#84 `_). GA4GH Type Prefixes diff --git a/docs/source/appendices/maturity_model.rst b/docs/source/appendices/maturity_model.rst index d677fe9d..cdaedf6e 100644 --- a/docs/source/appendices/maturity_model.rst +++ b/docs/source/appendices/maturity_model.rst @@ -3,44 +3,44 @@ GKS Maturity Model !!!!!!!!!!!!!!!!!! -The Genomic Knowledge Standards work stream is developing semantic data exchange -standards for federated genomic knowledge sharing. To address this, new technical -specifications are required, such as the VRS standard, which must be developed -and iterated upon through application across community implementations. This -creates a tension between the need to create products with enough stability for -initial community adoption, while ensuring that they can evolve with minimal -disruption to interoperate smoothly across a diverse set of genomic knowledge -resources. Mechanisms for communicating the stability, uptake, and development -of technical specifications are therefore of paramount importance to addressing +The Genomic Knowledge Standards work stream is developing semantic data exchange +standards for federated genomic knowledge sharing. To address this, new technical +specifications are required, such as the VRS standard, which must be developed +and iterated upon through application across community implementations. This +creates a tension between the need to create products with enough stability for +initial community adoption, while ensuring that they can evolve with minimal +disruption to interoperate smoothly across a diverse set of genomic knowledge +resources. Mechanisms for communicating the stability, uptake, and development +of technical specifications are therefore of paramount importance to addressing this balance. -A maturity model is a useful mechanism for communicating varying stability across -product features (e.g. data classes or protocols) of a GKS standard. This is -needed to help data producers at each stage of the adoption lifecycle -decide on the appropriate time to engage and implement the standard. Product -features that have progressed through the maturity model should have an associated -progression of support from the GKS specification maintainers for message +A maturity model is a useful mechanism for communicating varying stability across +product features (e.g. data classes or protocols) of a GKS standard. This is +needed to help data producers at each stage of the adoption lifecycle +decide on the appropriate time to engage and implement the standard. Product +features that have progressed through the maturity model should have an associated +progression of support from the GKS specification maintainers for message generation, translation, and validation tooling. -Here we define the maturity model and release process for developing and -maintaining GKS standards, with the goal of enabling timely specification +Here we define the maturity model and release process for developing and +maintaining GKS standards, with the goal of enabling timely specification adoption by the community. .. figure:: ../images/adoption_lifecycle.png :width: 800 - The Innovation Adoption Lifecycle. - - *The Innovation Adoption Lifecycle illustrates adoption rates (y-axis) for - new technologies over time (x-axis). Innovators (leftmost on the time axis) - are among the first to adopt a new technology, and laggards (rightmost) are - among the last, reflecting the differing needs for innovation and stability - by these community groups. Adopters in every category along the innovation - adoption lifecycle benefit from communication about the maturity of technical - specification components generated by the Genomic Knowledge Standards work - stream. Communicating when a component is ready for implementation by groups - along the innovation / stability spectrum is a primary goal of the maturity - model, enabling adopters to engage at a time that is appropriate for their + The Innovation Adoption Lifecycle. + + *The Innovation Adoption Lifecycle illustrates adoption rates (y-axis) for + new technologies over time (x-axis). Innovators (leftmost on the time axis) + are among the first to adopt a new technology, and laggards (rightmost) are + among the last, reflecting the differing needs for innovation and stability + by these community groups. Adopters in every category along the innovation + adoption lifecycle benefit from communication about the maturity of technical + specification components generated by the Genomic Knowledge Standards work + stream. Communicating when a component is ready for implementation by groups + along the innovation / stability spectrum is a primary goal of the maturity + model, enabling adopters to engage at a time that is appropriate for their organizational needs.* .. _feature-maturity-levels: @@ -48,7 +48,7 @@ adoption by the community. Feature Maturity levels @@@@@@@@@@@@@@@@@@@@@@@ -It may be helpful to visualize the application of maturity levels by viewing the +It may be helpful to visualize the application of maturity levels by viewing the current :ref:`classDiagram`. .. figure:: ../images/maturity_levels.png @@ -56,11 +56,11 @@ current :ref:`classDiagram`. Product feature maturity level criteria and commitments. -Product feature maturity levels are to be reviewed and advanced by consensus among -defined decision-makers following Work Stream and GA4GH processes, in consultation -with the associated product group membership. Factors to be considered for product -feature maturity advancement include the criteria specified in the above table, the -degree of adoption observed in the community, feedback provided by adopters, and +Product feature maturity levels are to be reviewed and advanced by consensus among +defined decision-makers following Work Stream and GA4GH processes, in consultation +with the associated product group membership. Factors to be considered for product +feature maturity advancement include the criteria specified in the above table, the +degree of adoption observed in the community, feedback provided by adopters, and availability of specification maintainers to provide the level of support required. Developing a Draft Product Feature @@ -68,15 +68,15 @@ Developing a Draft Product Feature **Decision-makers**: :ref:`feature-developers`, :ref:`product-leads` -**Criteria**: Draft product feature development work should be based on real use -cases across multiple environments (aligned with `GA4GH Product Development 14.5`_). -Requirements may result directly from a `landscape analysis of the problem domain`_, -or may emerge in the course of technical specification development. It is expected -that the need for product features are first discussed in a community forum (e.g. +**Criteria**: Draft product feature development work should be based on real use +cases across multiple environments (aligned with `GA4GH Product Development 14.5`_). +Requirements may result directly from a `landscape analysis of the problem domain`_, +or may emerge in the course of technical specification development. It is expected +that the need for product features are first discussed in a community forum (e.g. GitHub Discussions, GKS Work Stream calls). -**Process**: Follow the GKS :ref:`development-process`. As part of this process, -it is expected that consensus among the decision-makers was reached and major design +**Process**: Follow the GKS :ref:`development-process`. As part of this process, +it is expected that consensus among the decision-makers was reached and major design decisions documented. Disagreements are resolved per Work Stream and GA4GH processes. Advancing from Draft to Trial Use @@ -84,17 +84,17 @@ Advancing from Draft to Trial Use **Decision-makers**: :ref:`feature-developers`, :ref:`product-leads`, :ref:`product-implementers` -**Criteria**: Advancing a draft product feature to trial use should include at least two -independent product implementers that commit to supporting the draft product feature once -it has been advanced to trial use. At least one of these implementations must be open (aligned -with `GA4GH Product Development 14.8.3`_). Advancing a product feature to trial use also mandates -a minor version increment at the next release. As part of this process, it is expected that -consensus among the decision-makers was reached and major design decisions documented. Disagreement +**Criteria**: Advancing a draft product feature to trial use should include at least two +independent product implementers that commit to supporting the draft product feature once +it has been advanced to trial use. At least one of these implementations must be open (aligned +with `GA4GH Product Development 14.8.3`_). Advancing a product feature to trial use also mandates +a minor version increment at the next release. As part of this process, it is expected that +consensus among the decision-makers was reached and major design decisions documented. Disagreement resolution is handled per Work Stream and GA4GH processes. -**Process**: A ballot release is created that describes draft models under evaluation for -advancement to trial use. A survey is sent to all Product Implementers that have indicated -they are implementing one or more features under evaluation for advance to Trial Use. This +**Process**: A ballot release is created that describes draft models under evaluation for +advancement to trial use. A survey is sent to all Product Implementers that have indicated +they are implementing one or more features under evaluation for advance to Trial Use. This survey includes: 1. Name of Product Implementer @@ -103,7 +103,7 @@ survey includes: #. Comments on response (e.g. explicit endorsement or description of gaps) There is a minimum 1-week review period for Product Implementers to respond, though this may -be longer at the discretion of the product leads. More time for individual contributors may +be longer at the discretion of the product leads. More time for individual contributors may be permitted on request. Advancing from Trial Use to Normative @@ -112,12 +112,12 @@ Advancing from Trial Use to Normative **Decision-makers**: :ref:`feature-developers`, :ref:`product-leads`, :ref:`product-implementers`, :ref:`ws-leads` -**Criteria**: A normative model should have demonstrated interoperability of multiple data -generation and data consumption implementations, and should include implementations beyond -those used to advance a model to Trial Use. Advancing a product feature to normative also -mandates a minor version increment at the next release. As part of this process, it is -expected that consensus among the decision-makers was reached and major design decisions -documented. Community consultation and disagreement resolution are handled per Work Stream +**Criteria**: A normative model should have demonstrated interoperability of multiple data +generation and data consumption implementations, and should include implementations beyond +those used to advance a model to Trial Use. Advancing a product feature to normative also +mandates a minor version increment at the next release. As part of this process, it is +expected that consensus among the decision-makers was reached and major design decisions +documented. Community consultation and disagreement resolution are handled per Work Stream and GA4GH processes. .. _GA4GH Product Development 14.5: https://www.ga4gh.org/our-products/development-and-approval-process/#section_5:~:text=14.5%20Development%20work%20should%20be%20based%20on%20real%20use%20cases%20across%20multiple%20environments. @@ -129,14 +129,14 @@ and GA4GH processes. Product Versioning and Releases @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ -Versions are used to identify releases of the entire specification, not to individual product features. -Technical specification development is intrinsically linked to policy surrounding major and minor version +Versions are used to identify releases of the entire specification, not to individual product features. +Technical specification development is intrinsically linked to policy surrounding major and minor version identification, which follow `semantic versioning v2 `__ practices for API versioning. Versioning examples ################### -Version syntax follows SemVer syntax. Examples of how product features at different maturity levels are +Version syntax follows SemVer syntax. Examples of how product features at different maturity levels are applied to the SemVer major/minor/patch syntax as follows: Major Version Increment @@ -167,17 +167,17 @@ $$$$$$$$$$$$$$$$$$$$$$$ - Addition of implementation guidance, tests, or other supporting product features that do not directly affect data compatibility -Versioning of approved GA4GH standards additionally follow the procedures for `GA4GH Product Updates `__. -Specifically, advancement of data classes to the trial use or normative levels must be accompanied by a -minor release increment, and therefore may only be included in a release following an appropriate community +Versioning of approved GA4GH standards additionally follow the procedures for `GA4GH Product Updates `__. +Specifically, advancement of data classes to the trial use or normative levels must be accompanied by a +minor release increment, and therefore may only be included in a release following an appropriate community and PRC consultation process (`GA4GH Product Development 32 `__). Releases ######## -In order to support continuous development of a technical specification, pre-release snapshots are -allowed and must use the SemVer syntax for pre-releases. Pre-release snapshots may be created for -purpose at any time by the product leads. Pre-release snapshots should use the following pre-release -labels as version suffixes for the indicated purposes: +In order to support continuous development of a technical specification, pre-release snapshots are +allowed and must use the SemVer syntax for pre-releases. Pre-release snapshots may be created for +purpose at any time by the product leads. Pre-release snapshots should use the following pre-release +labels as version suffixes for the indicated purposes: - connect.-[.] - for pre-releases to be evaluated at an upcoming GA4GH Connect meeting @@ -192,16 +192,16 @@ labels as version suffixes for the indicated purposes: - for use as needed for all other purposes - N increments for successive snapshots -These pre-release labels are appended to the major, minor, and patch components to create -a pre-release version following the SemVer ..-