Merge pull request #348 from ga4gh/yaml-tools-rst

Auto documentation

.requirements.txt

@@ -1,3 +1,4 @@
 pytest
 python-jsonschema-objects>=0.3,<=0.3.10
+jsonschema==3.2.0
 pyyaml

docs/source/defs

@@ -0,0 +1 @@
+../../schema/defs

docs/source/terms_and_model.rst

@@ -110,9 +110,7 @@ subclass <utilityvariation>`. Types of variation are widely varied, and
 there are several :ref:`planned-variation` currently under consideration
 to capture this diversity.
 
-**Computational Definition**
-
-A representation of the state of one or more biomolecules.
+.. include:: defs/variation.rst
 
 .. _MolecularVariation:
 
@@ -142,38 +140,7 @@ genetic locus. In the genetics community, *allele* may also refer to a
 specific haplotype. In the context of biological sequences, "allele" refers
 to a distinct state of a molecule at a location.
 
-**Computational Definition**
-
-A state of a molecule at a :ref:`Location`.
-
-**Information Model**
-
-.. list-table::
-   :class: reece-wrap
-   :header-rows: 1
-   :align: left
-   :widths: auto
-
-   * - Field
-     - Type
-     - Limits
-     - Description
-   * - _id
-     - :ref:`CURIE`
-     - 0..1
-     - Variation Id; MUST be unique within document
-   * - type
-     - string
-     - 1..1
-     - MUST be "Allele"
-   * - location
-     - :ref:`Location` | :ref:`CURIE`
-     - 1..1
-     - Where Allele is located
-   * - state
-     - :ref:`SequenceExpression` | :ref:`SequenceState` (deprecated)
-     - 1..1
-     - An expression of the sequence state
+.. include:: defs/Allele.rst
 
 **Implementation Guidance**
 

schema/Makefile

@@ -1,4 +1,4 @@
-.PHONY: FORCE
+.PHONY: defs FORCE
 .SUFFIXES:
 .DELETE_ON_ERROR:
 
@@ -10,6 +10,10 @@ all: ${JSONS} defs
 %.json: %.yaml
 	./y2j.py <$< >$@
 
+defs:
+	rm -rf defs
+	./y2t.py
+
 ## # npm install -g json-dereference-cli
 ## %.json: %.yaml
 ## 	json-dereference -s $< -o $@

schema/defs/Allele.rst

@@ -0,0 +1,34 @@
+**Computational Definition**
+
+The state of a molecule at a :ref:`Location`.
+
+**Information Model**
+
+Some Allele attributes are inherited from :ref:`MolecularVariation`.
+
+.. list-table::
+   :class: reece-wrap
+   :header-rows: 1
+   :align: left
+   :widths: auto
+
+   *  - Field
+      - Type
+      - Limits
+      - Description
+   *  - _id
+      - :ref:`CURIE`
+      - 0..1
+      - Variation Id. MUST be unique within document.
+   *  - type
+      - string
+      - 1..1
+      - MUST be "Allele"
+   *  - location
+      - :ref:`CURIE` | :ref:`Location`
+      - 1..1
+      - Where Allele is located
+   *  - state
+      - :ref:`SequenceExpression` | :ref:`SequenceState` (deprecated)
+      - 1..1
+      - An expression of the sequence state

schema/defs/Variation.rst

@@ -0,0 +1,24 @@
+**Computational Definition**
+
+A representation of the state of one or more biomolecules.
+
+**Information Model**
+
+.. list-table::
+   :class: reece-wrap
+   :header-rows: 1
+   :align: left
+   :widths: auto
+
+   *  - Field
+      - Type
+      - Limits
+      - Description
+   *  - _id
+      - :ref:`CURIE`
+      - 0..1
+      - Variation Id. MUST be unique within document.
+   *  - type
+      - string
+      - 1..1
+      - 

schema/vrs.json

@@ -35,7 +35,7 @@
          }
       },
       "UtilityVariation": {
-         "description": "A collection of :ref:`Variation` subclasses that cannot be constrained to a specific class of biological variation, but are necessary for some applications of VRS.",
+         "description": "A collection of Variation subclasses that cannot be constrained to a specific class of biological variation, but are necessary for some applications of VRS.",
          "oneOf": [
             {
                "$ref": "#/definitions/Text"
@@ -60,19 +60,21 @@
          }
       },
       "Allele": {
-         "description": "The sequence state at a Location.",
+         "description": "The state of a molecule at a Location.",
          "additionalProperties": false,
          "type": "object",
          "properties": {
             "_id": {
-               "$ref": "#/definitions/CURIE"
+               "$ref": "#/definitions/CURIE",
+               "description": "Variation Id. MUST be unique within document."
             },
             "type": {
                "type": "string",
                "enum": [
                   "Allele"
                ],
-               "default": "Allele"
+               "default": "Allele",
+               "description": "MUST be \"Allele\""
             },
             "location": {
                "oneOf": [
@@ -82,7 +84,8 @@
                   {
                      "$ref": "#/definitions/Location"
                   }
-               ]
+               ],
+               "description": "Where Allele is located"
             },
             "state": {
                "oneOf": [
@@ -92,10 +95,17 @@
                   {
                      "$ref": "#/definitions/SequenceExpression"
                   }
+               ],
+               "description": "An expression of the sequence state",
+               "deprecated": [
+                  {
+                     "$ref": "#/definitions/SequenceState"
+                  }
                ]
             }
          },
          "required": [
+            "id",
             "location",
             "state",
             "type"
@@ -133,6 +143,7 @@
             }
          },
          "required": [
+            "id",
             "members",
             "type"
          ]
@@ -159,6 +170,7 @@
          },
          "required": [
             "definition",
+            "id",
             "type"
          ]
       },
@@ -193,6 +205,7 @@
             }
          },
          "required": [
+            "id",
             "members",
             "type"
          ]
@@ -313,6 +326,7 @@
          ],
          "required": [
             "copies",
+            "id",
             "subject",
             "type"
          ]
@@ -400,7 +414,7 @@
          ]
       },
       "SequenceInterval": {
-         "description": "A SequenceInterval represents a span of sequence. Positions are always represented by contiguous spans using interbase coordinates.\nSequenceInterval is intended to be compatible with that in Sequence Ontology ([SO:0000001](http://www.sequenceontology.org/browser/current_svn/term/SO:0000001)), with the exception that the GA4GH VRS SequenceInterval may be zero-width. The SO definition is for an \"extent greater than zero\".",
+         "description": "A SequenceInterval represents a span of sequence. Positions are always represented by contiguous spans using interbase coordinates. SequenceInterval is intended to be compatible with that in Sequence Ontology (SO:0000001), with the exception that the GA4GH VRS SequenceInterval may be zero-width. The SO definition is for an \"extent greater than zero\".",
          "type": "object",
          "additionalProperties": false,
          "properties": {
@@ -796,7 +810,7 @@
          }
       },
       "Gene": {
-         "description": "A gene is an authoritative representation of one or more heritable :ref:`Locations <Location>` that includes all sequence elements necessary to perform a biological function. A gene may include regulatory, transcribed, and/or other functional Locations.",
+         "description": "A gene is an authoritative representation of one or more heritable Locations  that includes all sequence elements necessary to perform a biological function. A gene may include regulatory, transcribed, and/or other functional Locations.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
@@ -899,7 +913,7 @@
       },
       "CURIE": {
          "additionalProperties": false,
-         "description": "A string that refers to an object uniquely.  The lifetime and scope of an id is defined by the sender.\nVRS does not impose any contraints on strings used as ids in messages. However, to maximize sharability of data, VRS RECOMMENDS that implementations use [W3C Compact URI (CURIE)](https://www.w3.org/TR/curie/) syntax.\nString CURIEs are represented as `prefix`:`reference` (W3C terminology), but often referred to as `namespace`:`accession` or `namespace`:`local id` colloquially.\nVRS also RECOMMENDS that `prefix` be defined in identifiers.org.\nThe `reference` component is an unconstrained string.\nA CURIE is a URI.  URIs may *locate* objects (i.e., specify where to retrieve them) or *name* objects conceptually.  VRS uses CURIEs primarily as a naming mechanism.\nImplementations MAY provide CURIE resolution mechanisms for prefixes to make these objects locatable.\nUsing internal ids in public messages is strongly discouraged.",
+         "description": "A string that refers to an object uniquely.  The lifetime and scope of an id is defined by the sender. VRS does not impose any contraints on strings used as ids in messages. However, to maximize sharability of data, VRS RECOMMENDS that implementations use W3C Compact URI syntax. String CURIEs are represented as `prefix`:`reference` (W3C terminology), but often referred to as `namespace`:`accession` or `namespace`:`local id` colloquially. VRS also RECOMMENDS that `prefix` be defined in identifiers.org. The `reference` component is an unconstrained string. A CURIE is a URI.  URIs may *locate* objects (i.e., specify where to retrieve them) or *name* objects conceptually.  VRS uses CURIEs primarily as a naming mechanism. Implementations MAY provide CURIE resolution mechanisms for prefixes to make these objects locatable. Using internal ids in public messages is strongly discouraged.",
          "type": "string",
          "pattern": "^\\w[^:]*:.+$",
          "example": "ensembl:ENSG00000139618"
@@ -913,7 +927,7 @@
       },
       "SequenceState": {
          "deprecated": true,
-         "description": "DEPRECATED: An assertion of the state of a sequence, typically at a Sequence Location within an Allele.\nThis class is deprecated. Use LiteralSequenceExpression instead.",
+         "description": "DEPRECATED: An assertion of the state of a sequence, typically at a Sequence Location within an Allele. This class is deprecated. Use LiteralSequenceExpression instead.",
          "additionalProperties": false,
          "type": "object",
          "properties": {
@@ -939,7 +953,7 @@
       },
       "SimpleInterval": {
          "deprecated": true,
-         "description": "DEPRECATED: A SimpleInterval represents a span of sequence. Positions are always represented by contiguous spans using interbase coordinates.\nThis class is deprecated. Use SequenceInterval instead.",
+         "description": "DEPRECATED: A SimpleInterval represents a span of sequence. Positions are always represented by contiguous spans using interbase coordinates. This class is deprecated. Use SequenceInterval instead.",
          "additionalProperties": false,
          "type": "object",
          "properties": {

schema/vrs.yaml

@@ -28,12 +28,21 @@ definitions:
       - $ref: "#/definitions/MolecularVariation"
       - $ref: "#/definitions/SystemicVariation"
       - $ref: "#/definitions/UtilityVariation"
+    heritable_properties:
+      _id:
+        $ref: "#/definitions/CURIE"
+        description: >-
+          Variation Id. MUST be unique within document.
+      type:
+        type: string
+    heritable_required: ["id", "type"]
+
     discriminator:
       propertyName: type
 
   MolecularVariation:
     description: >-
-      A variation on a contiguous molecule.
+      A :ref:`variation` on a contiguous molecule.
     oneOf:
       - $ref: "#/definitions/Allele"
       - $ref: "#/definitions/Haplotype"
@@ -70,24 +79,30 @@ definitions:
 
   Allele:
     description: >-
-      The sequence state at a Location.
+      The state of a molecule at a :ref:`Location`.
     additionalProperties: false
     type: object
     properties:
-      _id:
-        $ref: "#/definitions/CURIE"
       type:
         type: string
         enum: ["Allele"]
         default: "Allele"
+        description: >-
+          MUST be "Allele"
       location:
         oneOf:
           - $ref: "#/definitions/CURIE"
           - $ref: "#/definitions/Location"
+        description: >-
+          Where Allele is located
       state:
         oneOf:
           - $ref: "#/definitions/SequenceState" # DEPRECATED; remove in 2.0
           - $ref: "#/definitions/SequenceExpression"
+        description: >-
+          An expression of the sequence state
+        deprecated:
+          - $ref: "#/definitions/SequenceState"
     required: [ "type", "location", "state" ]
 
   Haplotype:
@@ -293,7 +308,7 @@ definitions:
       always represented by contiguous spans using interbase coordinates.
 
       SequenceInterval is intended to be compatible with that in Sequence Ontology
-      ([SO:0000001](http://www.sequenceontology.org/browser/current_svn/term/SO:0000001)),
+      (`SO:0000001<http://www.sequenceontology.org/browser/current_svn/term/SO:0000001>`_),
       with the exception that the GA4GH VRS SequenceInterval may be zero-width. The SO
       definition is for an "extent greater than zero".
     type: object
@@ -625,8 +640,8 @@ definitions:
 
       VRS does not impose any contraints on strings used as ids in
       messages. However, to maximize sharability of data, VRS
-      RECOMMENDS that implementations use [W3C Compact URI
-      (CURIE)](https://www.w3.org/TR/curie/) syntax.
+      RECOMMENDS that implementations use
+      `W3C Compact URI<https://www.w3.org/TR/curie/>`_ syntax.
 
       String CURIEs are represented as `prefix`:`reference` (W3C
       terminology), but often referred to as `namespace`:`accession`