Clarify Recipes documentation

[brendanreardon]

Feature description

There have been discussions about the scope of Recipes within cat-vrs, and the specification may benefit from more clarification about what Recipes are meant to do. This specifically came up in the context of the maxItems property on constraints for some Recipes. We may want to create a separate Discussions to discuss Recipes, but here we outline some specific action items.

At minimum, we should probably do the following:

• Update Recipe documentation to state that they (usually) follow definitions from other representation standards.
• Update the CanonicalAllele Recipe documentation to state that this Recipe is intended to model a CanonicalAllele as expected by ClinGen's definition.
• Create a table of expected relations with appropriate concept mappings, descriptions, and examples.
• Emphasize that anyone can create a Recipe, and encourage implementers to share their Recipes.
• Detail the above guidance in CONTRIBUTING.md

Contribution

Yes, I can create a PR for this feature.

[brendanreardon]

Adding here that I am working on being able to modify recipes-source.yaml to add additional constraints within vrs objects for use within Recipes. In particular, it would be useful to specify the residueAlphabet for both CanonicalAllele and ProteinSequenceConsequence. Tests do successfully validate (or not validate) examples if they are tested against one of these Recipes that enforce a SequenceReference residueAlphabet. Hmm... Here are modified versions of the Recipes that as a work in progress:

Note that the following needs to be added to the top of the .yaml file to import vrs

  vrs: ../vrs/vrs-source.yaml

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://w3id.org/ga4gh/schema/cat-vrs/1.0.0/recipes-source.yaml"
title: GA4GH-Cat-VRS-Recipe-Definitions
type: object

imports:
  cat-vrs: ./cat-vrs-source.yaml
  vrs: ../vrs/vrs-source.yaml

namespaces:
  gks.core: /ga4gh/schema/gks-core/1.0.0/json/
  vrs: /ga4gh/schema/vrs/2.0.1/json/

$defs:
  ProteinSequenceConsequence:
    maturity: trial use
    description: >-
      A change that occurs in a protein sequence as a result of genomic changes. Due to the degenerate nature
      of the genetic code, there are often several genomic changes that can cause a protein sequence consequence.
      The protein sequence consequence, like a :ref:`CanonicalAllele`, is defined by an
      :ref:`Allele` that is representative of a collection of congruent Protein Alleles that share the same altered codon(s).
    allOf:
      - $ref: CategoricalVariant
      - properties:
          constraints:
            contains:
              allOf:
                - $ref: DefiningAlleleConstraint
                - type: object
                  properties:
                    allele:
                      allOf:
                        - $refCurie: vrs:Allele
                        - type: object
                          properties:
                            location:
                              allOf:
                                - $refCurie: vrs:SequenceLocation
                                - type: object
                                  properties:
                                    sequenceReference:
                                      allOf:
                                        - $refCurie: vrs:SequenceReference
                                        - type: object
                                          properties:
                                            residueAlphabet:
                                              const: "aa"
                                          required:
                                            - residueAlphabet
                                  required:
                                    - sequenceReference
                          required:
                            - location
                    relations:
                      allOf:
                        - contains:
                            type: object
                            properties:
                              primaryCoding:
                                code:
                                  const: translation_of
                                system:
                                  const: http://www.sequenceontology.org
                      maxContains: 1

  CanonicalAllele:
    maturity: trial use
    description: >-
      A canonical allele is defined by an :ref:`Allele` that is representative of a collection of congruent
      Alleles, each of which depict the same nucleic acid on different underlying reference sequences.
      Congruent representations of an Allele often exist across different genome assemblies and associated
      cDNA transcript representations.
    allOf:
      - $ref: CategoricalVariant
      - properties:
          constraints:
            minItems: 1
            maxItems: 1
            contains:
              allOf:
                - $ref: DefiningAlleleConstraint
                - type: object
                  properties:
                    allele:
                      allOf:
                        - $refCurie: vrs:Allele
                        - type: object
                          properties:
                            location:
                              allOf:
                                - $refCurie: vrs:SequenceLocation
                                - type: object
                                  properties:
                                    sequenceReference:
                                      allOf:
                                        - $refCurie: vrs:SequenceReference
                                        - type: object
                                          properties:
                                            residueAlphabet:
                                              const: "na"
                                          required:
                                            - residueAlphabet
                                  required:
                                    - sequenceReference
                          required:
                            - location
                    relations:
                      allOf:
                        - contains:
                            type: object
                            properties:
                              primaryCoding:
                                code:
                                  const: liftover_to
                                system:
                                  const: ga4gh-gks-term:allele-relation
                        - contains:
                            type: object
                            properties:
                              primaryCoding:
                                code:
                                  const: transcribed_to
                                system:
                                  const: http://www.sequenceontology.org
                      maxContains: 2

[DanielPuthawala]

This is awesome. Great work Brendan! It didn't even occur to me that this would work, but I can think of cases where this level of control would be very useful to implementors.

[jsstevenson]

@brendanreardon VRS SequenceReferences can also define a moleculeType property as protein if you want to constrain sequence type for ProteinSequenceConsequences that way

[brendanreardon]

@brendanreardon VRS SequenceReferences can also define a moleculeType property as protein if you want to constrain sequence type for ProteinSequenceConsequences that way

Ah yeah good point. As far as I can tell though, these are both optional properties of VRS Sequence References and there are not any required properties that make it.... self evident about the Allele that lets you figure out what type of reference sequence the Allele is relative to. Even though they are not required, I always add the id and name to try to make it easier for people.

I guess this may be a design decision. Are we okay imposing additional requirements / restrictions on VRS within Recipes? 🤷