Discriminating types of Constraints within the specification

[brendanreardon]

I would like to propose organizing constraints into two categories, though the exact naming like needs workshopping. They are:

• Required constraints. These primarily define the Categorical Variant, are broadly based on VRS objects, and include our "Defining (blank)" constraints. For example:
  • Defining Allele Constraint
  • Defining Location Constraint
  • Adjacency Constraint (potentially renamed as Defining Adjacency Constraint?)
  • Feature Context Constraint (potentially renamed as Defining Concept Constraint?)
• Optional constraints. These refine the Categorical Variant and largely seem based on ConceptMappings. These can be thought of as the "annotative" constraints. For example:
  • CopyCountConstraint
  • CopyChangeConstraint
  • FunctionConstraint
  • (Planned) Oncogenicity / Pathogenicity Constraint

Documentation would organize constraints into these categories and state something along the lines of:

All constraints contribute to defining a categorical variant; however, at least one Required constraint MUST be present to establish categorical membership and Optional constraints MAY be used to further refine that definition.

Alternative naming may be:

• Primary and Refining constraints
• Core and Additional constraints
• Mandatory and Supplementary constraints
• Defining vs Annotative constraints. While this aligns with how we have colloquially described constraints within the working group, this would be alienating and misleading to newcomers, I think.

Technically this is a relatively straight forward implementation. The definition of CategoricalVariant is revised as follows, with additions bolded:

CategoricalVariant:
  type: object
  inherits: gks-core:Entity
  maturity: trial use
  description: >-
    A representation of a categorically-defined domain for variation, in which individual
    Constraintual variation instances may be members of the domain.
  properties:
    type:
      extends: type
      const: CategoricalVariant
      default: CategoricalVariant
      description: 'MUST be "CategoricalVariant"'
    members:
      type: array
      ordered: false
      description: >-
        A non-exhaustive list of VRS Variations that satisfy the constraints of
        this categorical variant.
      items:
        oneOf:
          - $refCurie: vrs:Variation
          - $refCurie: gks.core:iriReference
    constraints:
      type: array
      ordered: false
      items:
        $ref: "#/$defs/Constraint"
+    if:
+      minItems: 1
+    then:       
+      contains:
+       anyOf:
+          - $ref: "#/$defs/DefiningAlleleConstraint"
+          - $ref: "#/$defs/DefiningLocationConstraint"
+          - $ref: "#/$defs/FeatureContextConstraint"
+        minContains: 1
    mappings:
      type: array
      ordered: false
      items:
        $refCurie: gks.core:ConceptMapping
      description: >-
        A list of mappings to concepts in terminologies or code systems. Each mapping should
        include a coding and a relation.
  required:
    - name
    - type

I have tested this locally and, indeed, examples will not validate without one of the Required constraints included.

Daniel and I have had a few conversations over the past year circling around the need for something like this. It particularly came up when reading a comment from Daniel and James, discussing that a CategoricalVariant could theoretically be defined with only the FunctionConstraint.

What do people think?

Note: revised codeblock to support empty constraint arrays by including an if statement.

[ahwagner]

What do people think?

This is going to block one of @korikuzma's favorite tricks 😂. I like the direction this is headed, but noting that we have had experiences with categorical variants for which there is no appropriate constraint, and the empty CatVar allows us to put labels etc. on it without those constraints. It is very flexible but lends itself to abuse. This tightens that up at the cost of flexibility. I imagine this would adversely impact @larrybabb's work on ClinVar-GKS.

[jsstevenson]

noting that we have had experiences with categorical variants for which there is no appropriate constraint, and the empty CatVar allows us to put labels etc. on it without those constraints

👍 This is also something we do during MetaKB data preprocessing

[brendanreardon]

Ah darn, nice catch. I missed this because the describedVariant-ex1 is not in our test definitions. Making the following adjustment accounts for this. Though, as is, describedVariant will also still validate against my prior suggestion because the constraints property just isn't there. With this version, describedVariant validates against CategoricalVariant when either no constraints property is provided or when constraints is specified to be an empty array.

  CategoricalVariant:
    type: object
    inherits: gks-core:Entity
    maturity: trial use
    description: >-
      A representation of a categorically-defined domain for variation, in which individual
      Constraintual variation instances may be members of the domain.
    properties:
      type:
        extends: type
        const: CategoricalVariant
        default: CategoricalVariant
        description: 'MUST be "CategoricalVariant"'
      members:
        type: array
        ordered: false
        description: >-
          A non-exhaustive list of VRS Variations that satisfy the constraints of
          this categorical variant.
        items:
          oneOf:
            - $refCurie: vrs:Variation
            - $refCurie: gks.core:iriReference
      constraints:
        type: array
        ordered: false
        items:
          $ref: "#/$defs/Constraint"
+        if:
+          minItems: 1
+        then:
+          contains:
+            anyOf:
+              - $ref: "#/$defs/DefiningAlleleConstraint"
+              - $ref: "#/$defs/DefiningLocationConstraint"
+              - $ref: "#/$defs/FeatureContextConstraint"
+              - $ref: "#/$defs/AdjacencyConstraint"
+            minContains: 1
      mappings:
        type: array
        ordered: false
        items:
          $refCurie: gks.core:ConceptMapping
        description: >-
          A list of mappings to concepts in terminologies or code systems. Each mapping should
          include a coding and a relation.
    required:
      - name
      - type

[brendanreardon]

This was discussed at the 2026-01-07 meeting and we decided to not pursue this route. Instead, documentation should be revised to put Recipes forward first. The problem that this Idea addresses is an onboarding one. People like that Constraints are modular and independent, and adding a hierarchy may add additional complexity to the onboarding process.