Clarifying and refining usage of Recipes

[brendanreardon]

Hi gang. @DanielPuthawala and I have identified some areas of friction with how Recipes are being used and interpreted relative to Constraints. Thus, we put together this Discussion to explore how to alleviate some of this. We'll also discuss this at an upcoming call.

First, we discuss a major design decision with Cat-VRS that the specification does not have explicit top-down typology of genomic alterations. Following this assumption, we raise the following questions along with some thoughts around them:

1. What is the intent of Recipes?
2. Should a single Categorical Variant be able to satisfy multiple Recipes?
3. When should we adopt implementation-specific Recipes?
4. When should we draft general purpose Recipes?
5. Should Recipes be able to put additional… constraints… on modeled constraints? Where should we put additional constraints on Constraints? Recipes currently do this.
6. What do our current Recipes represent?

For each item, please share if you agree or disagree that this is an area of friction, as well as share your thoughts on how to alleviate it. If we missed any areas, please add them!

Assumption: Cat-VRS does not have explicitly typed genomic alteration types

Thus far, Cat-VRS has adopted two Major Impact Design Decisions, defined as “Decisions that significantly alter the structure, functionality, or core principles of the product”. These two were:

• Treatment of CatVars as ((Hyper)Intensional) Set-Theoretic Objects, and
• Adoption of a Constraint-Based Model instead of a top-down typology of data classes

Cat-VRS, unlike systems like HGVS, does not pre-define categorical variant types in a top-down fashion, but rather represents categorical variants as a combination of semantic properties, which can be more or less freely composed and combined to define a flexible variety of genomic alteration types.

What is the intent of Recipes?

Although we do not want to pre-specify variant categories a priori in a top-down fashion, it is useful to illustrate how common types of variation can be expressed when using cat-vrs. In other words, we want to be able to represent common types of genomic alterations and implementation-specific “packets” of information that are expected with a type of genomic alteration. These two use cases are quasi-equivalent to having a “typed” typology, but less paternalistic.

Both are specifying expected information. Constraints are filters on genomic variants to match to the given categorical variant, and Recipes are combinations of Constraints that are expected within certain circumstances. In other words, Constraints are ingredients and Recipes are instructions, hence the adoption of “Recipes” as the name for this feature.

Should a single categorical variant be able to satisfy multiple Recipes?

Yes! A single categorical variant should be able to match to multiple Recipes.

When should we adopt implementation-specific Recipes?

Recipes often represent specific packets of information expected by implementations. For example, ClinGen’s Canonical Allele has a specific definition of what information it wants to receive, and importantly, it does not want to receive any additional information beyond that. In these circumstances, we can write a Recipe to show how a Canonical Allele would be expressed with Cat-VRS.

Perhaps we should adopt these “implementation-specific” Recipes after either a “high impact” implementation adopts GKS representations (e.g., ClinGen / ClinVar), or a few implementations are using the same Recipe? This would be great to discuss with the group.

When should we draft general purpose Recipes?

There are several types of genomic alterations that are colloquially used throughout the genomics community but may not have a ubiquitous representation. Likewise, we would like to be able to have some Recipes to illustrate how these types of genomic alterations would be expressed through cat-vrs. For example, Protein Sequence Consequence or categorical CNVs.

However, by writing a Recipe and not pointing to an external implementation, Cat-VRS is (maybe) functionally entering the variant typology space and defining how types of genomic alterations should be represented. Recipes are the area of the schema that implementers are able to monkey around with on their own safely without breaking compatibility with other folks using Cat-VRS. They don't even have to register their recipes with us if they're just for internal use. The main value in folks having us publish their recipes is sort of a proxy for their API frontend to show what sort of Cat-VRS-structured data they are willing to send, receive, or work with.

Instead, would we be better off to not draft these general purpose Recipes, and instead simply show Examples? We could instead hyperlink to Recipes being used by implementations and, based on When should we adopt implementation specific Recipes, officially adopt them when appropriate. This likewise would be great to discuss with the group.

What do our current Recipes represent?

Recipe	Maturity	Type	Description
CanonicalAllele	Trial Use	Implementer specific	ClinGen’s Canonical Allele
CategoricalCnv	Draft	General purpose	Combining CopyChange or CopyCount constraints with a defining location or feature context.
FunctionVariant	Draft	General purpose	How to pair a FunctionConstraint with an Allele or FeatureContext.
ProteinSequenceConsequence	Trial Use	General Purpose	Sequence variants on an amino acid sequence

Should Recipes put additional… constraints on constraints..?

In addition to showing the expected combination of constraints, Recipes also currently further restrict how Constraints are represented. For example, CanonicalAllele expects two Codings within the `relations` array.

Recently, I figured out how to add expectations of the underlying VRS objects. For example, requiring the sequenceReference residueAlpha to be “aa” for Protein Sequence Consequences.

$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

Both of these – adding expectations to the relations array and allele – are further specifying matching criteria against categorical variants. Generally, we want to be the least-restrictive as possible in the Constraints and let people be more restrictive in the Recipes. Continuing with the cooking analogies, this usage of Recipes adds specificity to ingredients; for example, requiring “1 onion, diced” instead of “1 onion” and likewise a “Defining Allele Constraint with these additional conditions” instead of just a “Defining Allele Constraint”.

[brendanreardon]

This was discussed at the Oct 21st 2025 meeting. In short:

The group tended to disagree with the differentiation between "implementer-specific" and "general purpose" Recipes. Because GKS is implementer driven, they should all be implementer-specific Recipes that represent common types of variation. Furthermore, the Canonical Allele Recipe was not specifically written for ClinGen.

People generally quite liked making Recipes more specifically defined. One suggestion was that Recipes state "What is going to be provided by data generators? What is definable by Cat-VRS within these Recipes?". When the Recipes were first being implemented, they did consider adding genomic residueAlphabet type for Canonical Allele but opted not to because this is an optional argument within the VRS data model.

[brendanreardon]

At the at the 2026-01-07 meeting, the group decided to emphasize Recipes in documentation and onboarding, perhaps presenting Cat-VRS as a Recipes-first. Documentation will be refactored to address this decision. As part of this, we likely need to return to the #172 Developing implementation guidance of and recommendations for the relations property.