1.1

1.1.0

This release adds a hasEvidence attribute to Statement, for evidence that is associated with a Statement without saying how it supports or disputes the proposition. The dedicated Evidence Line class (referenced via hasEvidenceLines, as in 1.0) remains the way to represent how evidence was weighed, as a nested, scored, directional argument. It also reworks how Proposition/StudyResult subclasses declare their subject/predicate/object/focus attributes, so they inherit under their canonical names instead of being renamed per subclass. It restructures the domain entities around GKM Core’s MappableConcept/ConceptSet: Therapeutic is renamed Therapy, and single concepts and sets are now separate classes. It also renames the abstract ClinicalVariantProposition class. The latter three are backwards-incompatible changes to trial use classes; the hasEvidence addition is not. The release also adds several new draft classes and substantially revises the draft community profiles. Finally, it modernizes the schema-generation pipeline and refreshes the imported dependencies to Cat-VRS 1.1.1, VRS 2.1.1, and GKM Core 1.3.0.

Minor Version Increment

Backwards-incompatible changes to previously-released trial use product features, and additions/changes to trial use or normative data classes, per the GA4GH Maturity Model versioning rules:

  • renames the abstract ClinicalVariantProposition class (trial use) to Genetic Context Variant Proposition, and updates its definition to describe knowledge that depends on a variant’s genetic context

  • adopts the GKM Core (formerly GKS-Core) 1.2.0 MappableConcept and ConceptSet changes (both trial use in GKM Core). Both classes now inherit Entity and require a type discriminator field, which is a backwards-incompatible addition of a required field to these previously-released trial use classes. This propagates to the VA-Spec trial use classes that specialize them: Condition and Therapy (specializations of MappableConcept), and Condition Set and Therapy Group (specializations of ConceptSet)

  • restructures the trial use domain entities. In 1.0, Condition and Therapeutic were each a union of a single MappableConcept or a set. Now:

    • Condition and Therapy (renamed from Therapeutic) are single concepts that specialize MappableConcept, with suggested conceptType values that default to Condition/Therapy.

    • the single-or-set union moves to the attributes that use these classes. For example, a proposition’s object is now Condition | ConditionSet | iriReference, as is Variant Therapeutic Response Proposition conditionQualifier. These attributes already accepted either a single concept or a set in 1.0, through the Condition/Therapeutic union.

    • Condition Set and Therapy Group now specialize GKM Core’s Concept Set. Their required conditions/therapies arrays are renamed concepts, and a member may now also be given as an iriReference. A Therapy Group may now contain nested Therapy Groups; a Condition Set could already contain nested Condition Sets as of 1.0.1.

  • adopts GKM Core 1.3.0, which adds an optional conceptSetType to Concept Set. Because Condition Set and Therapy Group specialize ConceptSet, both trial use classes now accept this optional field.

Subject / object / focus model change

Backwards-incompatible. VA-Spec 1.0 renamed the abstract triple attributes in each subclass (e.g. subject \(\rightarrow\) subjectVariant, object \(\rightarrow\) objectCondition, focus \(\rightarrow\) focusAllele). The 0.4.x metaschema processor inherits properties by name and does not permit renaming, so the model has been made consistent with that rule:

  • The abstract Proposition declares subject, predicate, and object (all required); the abstract Study Result declares focus (required). Every subclass now narrows these in place under the same name rather than renaming them. Affected serialized property names change: subjectVariant \(\rightarrow\) subject; objectCondition / objectTumorType / objectSequenceFeature / objectTherapeutic \(\rightarrow\) object; focusAllele / focusVariant \(\rightarrow\) focus. The draft propositions added in this release follow the same rule; their subjectGene and objectConsequence attributes appeared only in 1.1.0 pre-releases, never in a 1.0.x release. All examples and test fixtures were updated accordingly.

  • Cohort Allele Frequency Study Result also renames focusAlleleCount \(\rightarrow\) focusCount, locusAlleleCount \(\rightarrow\) locusCount, and focusAlleleFrequency \(\rightarrow\) alleleFrequency.

  • The abstract base classes (Proposition, Study Result, Subject Variant Proposition) are open and no longer carry a closed oneOf of their built-in subtypes. Being open means a reference to one of these bases is not restricted to the schema’s own subtypes and – as with any sealed and abstract class – carries no additionalProperties: false, so any object that satisfies the base’s required properties validates against it, including subclasses the schema does not itself declare (see the metaschema appendix for how open vs. closed is encoded). Implementers can therefore define and validate their own subclasses of Proposition and Study Result against these bases. The draft CustomProposition class, briefly introduced in an earlier 1.1.0 pre-release for the same purpose, is superseded by this and was removed before this release. Statement remains concrete and closed, as before.

  • allows an iriReference as an alternative to an inline object on attributes that reference other, independently-identifiable Information Entities or concepts, so implementers can reference instead of inline them: Contribution.contributor, Variant Pathogenicity Proposition.modeOfInheritanceQualifier/ .penetranceQualifier, Statement.proposition/ .strength/.classification, Evidence Line.targetProposition/ .strengthOfEvidenceProvided/.evidenceOutcome, Study Result.sourceDataSet, Cohort Allele Frequency Study Result.cohort, Tumor Variant Frequency Study Result (draft).sampleGroup, Data Set.license, and Study Group.characteristics. Attributes that are new in this release follow the same pattern, including Statement.quality and the sourceDataSet redeclared by the draft Computational Variant Functional Impact Analysis Result.

Associating evidence with a Statement

Statement gains a hasEvidence attribute for evidence that is associated with the Statement. It complements the distinct Evidence Line class rather than replacing it: hasEvidence gives no indication of how an item supports or disputes the proposition, whereas Evidence Lines (in hasEvidenceLines, as in 1.0) carry that information, as direction and strength or score, and are what a classification rests on. The changes in this subsection are additive, so, unlike the changes above, none of them by itself invalidates data that was valid in 1.0:

  • Statement gains the hasEvidence attribute and a draft quality attribute. hasEvidence associates evidence with a Statement without indicating how it supports or disputes the proposition. It is declared immediately before hasEvidenceLines, and its items are a Statement | StudyResult | DataItem | iriReference (a prior Statement, Study Result, or Data Item); structured, scored, directional arguments are attached separately via hasEvidenceLines. For example, in a CIViC oncogenicity assertion the ClinGen/CGC/VICC criteria codes that drive the classification are Evidence Lines, while the associated CIViC evidence items, which are not part of that code system, go in hasEvidence.

  • Statement’s direction, strength, score, and classification attributes were already present in 1.0, so a Statement could already report its own assessment.

  • Statement’s hasEvidenceLines still holds EvidenceLine | iriReference, as in 1.0: a Statement is not itself usable as an Evidence Line, so a nested, scored, directional argument is always a dedicated Evidence Line.

  • the Evidence Line class keeps its 1.0 attributes: targetProposition, directionOfEvidenceProvided, strengthOfEvidenceProvided, scoreOfEvidenceProvided, evidenceOutcome, and hasEvidenceItems. hasEvidenceItems is widened from StudyResult | Statement | EvidenceLine | iriReference to any InformationEntity | iriReference, so it also accepts the new Data Item. As in 1.0, because an Evidence Line is itself an Information Entity, Evidence Lines nest by listing subordinate Evidence Lines there (there is no separate hasEvidenceLines on Evidence Line).

  • all examples and test fixtures were updated accordingly.

Patch Version Increment

New product features at the draft maturity level, changes to existing draft features, and supporting changes that do not affect data compatibility:

  • adds Gene Disease Validity Proposition (draft), a new proposition type for gene-disease validity assertions

  • adds Variant Molecular Consequence Proposition (draft), for representing the predicted molecular consequences of a variant

  • adds Variant Clinical Significance Proposition (draft), for describing the clinical significance of a variant with respect to a condition

  • adds Computational Variant Functional Impact Analysis Result (draft), a Study Result (so it requires focus) that reports the output of an in silico tool’s analysis of a variant’s functional impact

  • updates the AAC 2017 Aligned Profiles (draft) to better reflect the source guidelines

  • enforces enum validation in primaryCodings across the AAC/ACMG/CCV (draft) profiles

  • updates the Condition Set VA-Spec version reference

  • resolves a typo (“Oncoogenicity” \(\rightarrow\) “Oncogenicity”) in the CCV oncogenicity evidence line profile

  • fixes typos in the allele origin description

  • updates descriptions for the Variant Clinical Significance Statement profile

  • updates the VRS and Cat-VRS submodule references (see the GKM Core items under Minor above for the substantive changes pulled in via these bumps)

  • adds Quick Start guidance

  • adds documentation for the TumorVariantFrequencyStudyResult (draft) profile to the Study Result profiles page

  • adds a README to the Modeling subdirectory

  • updates the repository README to include contributing information

  • adds a CITATION file

  • various documentation fixes and copyright year updates

  • adds test examples and fixtures for CIViC oncogenicity assertions and propositions

  • adds a pre-commit hook to detect and stage VA-Spec schema updates

  • corrects the core model class diagram to show Data Set inheriting from Entity rather than InformationEntity, matching the source schema (closes #380)

  • the 0.4.x metaschema processor now emits a JSON Schema for every abstract class (previously only unions were emitted).

Draft classes and community profiles

Changes to classes at draft maturity, including every AAC-2017, ACMG-2015, and CCV-2022 community profile class. Some of these changes are backwards-incompatible, but draft classes carry no compatibility guarantee, so they are patch-level:

  • adds a new draft Data Item class (an Information Entity subclass wrapping a structured, string, or IRI-reference value) as one of the concrete types citable as evidence (via a Statement’s hasEvidence or an Evidence Line’s hasEvidenceItems).

  • restructures the AAC-2017 profiles. The 1.0 VariantDiagnosticStudyStatement, VariantPrognosticStudyStatement, and VariantTherapeuticResponseStudyStatement classes are replaced by a single top-level Variant Clinical Significance Statement (AAC 2017), which composes Statement and constrains its classification attribute, and by four new classes that compose the Evidence Line class (using its directionOfEvidenceProvided/strengthOfEvidenceProvided attributes): Variant Amp/Asco/Cap Evidence Line (AAC 2017), Variant Diagnostic Evidence Line (AAC 2017), Variant Prognostic Evidence Line (AAC 2017), and Variant Therapeutic Evidence Line (AAC 2017). Earlier 1.1.0 pre-releases declared the last three as type: array (an array of itself-or-iriReference) rather than as plain allOf-composed objects, so the tier i/ii hasEvidenceLines narrowing that referenced them (via a bare oneOf, with no type: array/items wrapper of its own) required the whole hasEvidenceLines array to itself match one of these array-typed branches, rather than letting each item independently be one of the three types. That array-wrapping defect never shipped in a 1.0.x release, and is fixed here: the array wrapping lives at the narrowing site, matching Variant Amp/Asco/Cap Evidence Line (AAC 2017)’s composition pattern.

  • Variant Pathogenicity Evidence Line (ACMG 2015) and Variant Oncogenicity Evidence Line (CCV 2022) still compose the Evidence Line class and use its directionOfEvidenceProvided/ strengthOfEvidenceProvided/evidenceOutcome attribute names, as in 1.0. Each class’s own methodType enumeration is redefined. In 1.0 it listed the individual criterion codes (PVS1, PS1, … for ACMG-2015; OVS1, OS1, … for CCV-2022). It now lists snake_case codes for the type of assessment performed (17 for ACMG-2015, 8 for CCV-2022), and new per-methodType if/then constraints restrict the criterion codes that evidenceOutcome may report for each one. Earlier 1.1.0 pre-releases used other names for these codes (e.g. ACMG-2015’s "Population Data Assessment" \(\rightarrow\) population_data_assessment and "De Novo Data Assessment" \(\rightarrow\) de_novo_occurrence_assessment; CCV-2022’s population_frequency \(\rightarrow\) population_data_assessment, functional_assay \(\rightarrow\) functional_data_assessment, functional_domain_location \(\rightarrow\) functional_domain_assessment, amino_acid_or_residue_analogy \(\rightarrow\) amino_acid_analogy_assessment, somatic_hotspot_recurrence \(\rightarrow\) somatic_hotspot_assessment, computational_prediction \(\rightarrow\) in_silico_impact_assessment, and single_genetic_etiology_context \(\rightarrow\) single_genetic_etiology_assessment). The CCV-2022 statement profile is renamed from VariantOncogenicityStudyStatement to Variant Oncogenicity Statement (CCV 2022). It and Variant Pathogenicity Statement (ACMG 2015) constrain the core Statement classification attribute, as in 1.0.

  • both Variant Pathogenicity Evidence Line (ACMG 2015) and Variant Oncogenicity Evidence Line (CCV 2022) add no_criteria_met as an allowed evidenceOutcome code, alongside the existing {criterion_code} and {criterion_code}_not_met forms. Use it to report that the criteria associated with the evidence line’s methodType were assessed, but none of them were met. It is accepted both by each class’s overall outcome pattern and by every per-methodType pattern. Backwards-incompatible: both classes now also constrain the direction and strength that may accompany a negative outcome: when evidenceOutcome is no_criteria_met or any {criterion_code}_not_met code, directionOfEvidenceProvided MUST be neutral and strengthOfEvidenceProvided MUST NOT be present. Previously a not-met outcome could be paired with a supports/disputes direction and a strength value.

  • the 17 ACMG-2015 per-methodType conditions on Variant Pathogenicity Evidence Line (ACMG 2015) check the correctly-nested specifiedBy.methodType (matching the equivalent pattern on Variant Oncogenicity Evidence Line (CCV 2022)). The 1.1.0 pre-releases that introduced these conditions checked a non-existent top-level methodType property instead, so none of them could ever be satisfied by a valid instance. That defect never shipped in a 1.0.x release.

  • constrains hasEvidenceLines in the ACMG-2015 (draft) and CCV-2022 (draft) statement profiles to the profile’s own evidence line class or an iriReference. In 1.0 these profiles did not narrow hasEvidenceLines, which therefore accepted any EvidenceLine | iriReference. The AAC-2017 Variant Clinical Significance Statement (AAC 2017) narrows it the same way, to its three evidence line classes or an iriReference, for tier i and tier ii classifications.

Pipeline modernization

Supporting changes to the schema-generation tooling and repository layout that do not, by themselves, change the meaning of VA-Spec data:

  • migrates the metaschema processor from ga4gh.gks.metaschema (0.3.2) to the renamed ga4gh.gkm.metaschema (0.4.8) package (the GKS \(\rightarrow\) GKM “Genomic Knowledge Models” rebrand). The console entrypoints (source2classes, source2splitjs, y2t) are unchanged, so make all still drives generation. 0.4.6 tightens $ref handling: a $ref must be a local #/$defs/... reference, so the bare-class-name and full-URL $refs previously used to reach classes in an imported module (domain-entities, and the base va-spec classes referenced from the community profiles) were converted to $refCurie: <namespace>:<Class>. 0.4.7 adds two purely additive generated-docs features: an allOf-composed class’s def page now carries a Composes: line naming the class it composes onto (mirroring the existing Inherits:/Subclasses: lines for inherits:-based classes), and a composed class with if/then constraints now renders a table summarizing them (e.g. the AAC-2017 tier-based rules on VariantClinicalSignificanceStatement). 0.4.8 renames that table from “Conditional Constraints” to Additional Constraints, adds italic/bold styling to the property/value cells, and gives anyOf/oneOf compositions whose only constraint is “at least one of” a plain-language sentence instead of a duplicated placeholder bullet list (see Mappable Concept, which requires at least one of name or primaryCoding).

  • adopts the 0.4.x source conventions in every VA-Spec module source: abstract classes are marked abstract: true (left open by omitting additionalProperties: false), concrete classes are closed and drop the explicit type: object (the processor injects it), heritableProperties / heritableRequired become plain properties / required on abstract bases, and the removed extends: key is dropped.

  • renames the nested gks-core import to gkm-core throughout the schema sources, imported $refCurie namespaces (gks.core \(\rightarrow\) gkm.core), and the documentation.

  • makes the imported schema/{cat-vrs,vrs,gkm-core} directories real folders that symlink only to the imported *-source.yaml and json/ (no def/); VA-Spec now generates the imported-class def/ locally via y2t and the docs include those local defs.

  • checks out submodules recursively in the pre-commit CI job so make all can resolve the imported source symlinks on a fresh checkout.

  • reorganizes schema/va-spec/: the former base/ module moves up to the va-spec/ root (va-core-source.yaml is renamed va-spec-source.yaml), and the build now produces a single json/ and def/ under va-spec/. Each community profile writes its own classes into json/<community>/ and def/<community>/ subfolders (the base classes’ output sits at the json/ and def/ root). Base-class namespaces change from va-spec.base to va-spec; community namespaces (va-spec.aac-2017 etc.) are unchanged.

  • flattens the three community profile sources — aac-2017/profile-source.yaml, acmg-2015/profile-source.yaml, ccv-2022/profile-source.yaml — out of their own subdirectories, into schema/va-spec/<community>-profile-source.yaml, alongside va-spec-source.yaml and domain-entities-source.yaml. This adopts the gks-metaschema processor’s native profile sub-namespace convention (an XXX-profile-source.yaml file contributes XXX as a sub-namespace of the folder it lives in): outputs land at json/<community>/ and def/<community>/, and each profile class’s $id is now .../va-spec/<version>/json/<community>/<Class> (in 1.0 it was .../va-spec/<version>/<community>/json/<Class>), computed natively by the processor. The four per-directory Makefiles/prune.mk are replaced by one flat schema/va-spec/Makefile/prune.mk that builds every source in the folder. A side benefit: cross-reference (“Used in:”) lists in the generated docs are computed across every source in a folder together, so base classes now correctly show community profile classes that reference them (previously invisible across the old subdirectory boundaries).

  • makes the documentation fully self-contained: docs/source no longer references anything outside itself. Generated class defs are synced into docs/source/def/ (via tools/sync-docs-def.sh, wired into the pre-commit hook), and the Maturity Model page and its images are materialized locally rather than included from the vrs submodule.

Dependency / version refresh

  • bumps the cat-vrs submodule to 1.1.1, which pulls in vrs 2.1.1 and gkm-core 1.3.0.

  • retargets the imported namespace mappings in every VA-Spec source to the new imported $id tokens (cat-vrs/1.1.1, vrs/2.1.1, gkm-core/1.3.0).

  • sets VA-Spec’s own $id token to 1.1.0.