VA-Spec 1.1.0 Community Review Ballot

[larrybabb]

This is the ballot pre-release of the VA-Spec 1.1 specification, open for community review following the GA4GH Product Development and Approval process.

Important Links

Documentation: https://va-spec.ga4gh.org/en/1.1.0-ballot.2026-09
Release log: https://va-spec.ga4gh.org/en/1.1.0-ballot.2026-09/releases/1.1.html
Schemas: https://github.com/ga4gh/va-spec/tree/1.1.0-ballot.2026-09.1/schema/va-spec/json
Discussion: this page!

Design Decisions and Rationale: https://docs.google.com/document/d/1UIp0Xnwo_zrGCJdBE3oKjLdW23cBHonAJn66G9zUzj4/edit?usp=sharing

Full Changelog: 1.0.1...1.1.0-ballot.2026-09.1

---

This discussion was created from the release 1.1.0-ballot.2026-09.1.

What's Changed

Version 1.1.0 consolidates the core EvidenceLine class into Statement: a "discrete evidence-based argument" is now a Statement referenced through another Statement's hasEvidenceLines. It also has Proposition/StudyResult subclasses narrow subject/predicate/object/focus in place instead of renaming them per subclass. It restructures the domain entities around GKM Core's MappableConcept/ConceptSet (Therapeutic is renamed Therapy) and renames the abstract ClinicalVariantProposition. The release also adds several draft propositions, substantially revises the draft AAC-2017, ACMG-2015, and CCV-2022 community profiles, modernizes the schema-generation pipeline, and refreshes the imported dependencies to the 2026-09 ballot line.

Changes are categorized per the GA4GH TASC Technical Specification Development policy, based on the maturity of each class touched, and compared against the last full release, 1.0.1. See the release log for full detail.

Minor Version Increment

Backwards-incompatible changes and additions to trial use classes:

• Evidence Line consolidated into Statement. EvidenceLine is removed.
  • Statement gains hasEvidenceItems, and its hasEvidenceLines now holds Statement | iriReference (was EvidenceLine | iriReference).
  • EvidenceLine's attributes move onto Statement: targetProposition → proposition, which is now optional; directionOfEvidenceProvided → direction; strengthOfEvidenceProvided → strength; evidenceOutcome and Statement's classification merge into outcome; qualityOfEvidenceProvided → quality.
• Subject / object / focus. Proposition declares subject/predicate/object and StudyResult declares focus, and every subclass narrows them in place: subjectVariant → subject; objectCondition/objectTumorType/objectSequenceFeature/objectTherapeutic → object; focusAllele/focusVariant → focus. The abstract Proposition, StudyResult, and SubjectVariantProposition bases are now open, so implementers can define their own subclasses.
• Domain entities restructured.
  • Therapeutic is renamed Therapy.
  • Condition and Therapy are now single MappableConcept specializations, and the single-or-set union moves to where they're used (e.g. object: Condition | ConditionSet | iriReference).
  • ConditionSet and TherapyGroup now specialize ConceptSet, with conditions/therapies renamed concepts.
• Adopts GKM Core 1.2.0 MappableConcept/ConceptSet. Both now require a type discriminator, which propagates to Condition, Therapy, ConditionSet, and TherapyGroup.
• Adopts GKM Core 1.3.0. ConditionSet and TherapyGroup now accept the optional conceptSetType.
• Renames ClinicalVariantProposition → GeneticContextVariantProposition.
• Renames CohortAlleleFrequencyStudyResult focusAlleleCount → focusCount, locusAlleleCount → locusCount, and focusAlleleFrequency → alleleFrequency.
• Allows an iriReference in place of an inline object on attributes that reference independently-identifiable entities. Examples: Contribution.contributor, Statement.proposition/.strength/.outcome/.quality, StudyResult.sourceDataSet, and VariantPathogenicityProposition's qualifiers.

Patch Version Increment

New draft features, changes to draft classes, and supporting changes:

• adds GeneDiseaseValidityProposition, VariantMolecularConsequenceProposition, VariantClinicalSignificanceProposition, and DataItem (all draft).
• revises the draft community profiles:
  • AAC-2017: AmpAscoCapStatement and its Diagnostic/Prognostic/TherapeuticStatement subclasses.
  • ACMG-2015 and CCV-2022: evidence lines and statements now compose Statement; methodType codes are normalized to snake_case; no_criteria_met outcomes are added; the if/then tier constraints are fixed; and hasEvidenceLines accepts IRIs.
• migrates the metaschema processor to ga4gh.gkm.metaschema 0.4.8 and its source conventions, and emits a JSON Schema for every abstract class.
• reorganizes schema/va-spec/ into a flat folder using the processor's profile sub-namespace convention, and makes the docs self-contained.
• refreshes dependencies to the 2026-09 ballot line: Cat-VRS 1.1.1, VRS 2.1.1, and GKM Core 1.3.0 (Repin VRS to 2.1.1 and Cat-VRS to 1.1.1 ballots (were 2.2.0 / 1.2.0) #446).
• various documentation, example, test-fixture, and tooling updates.

[ByungwoongYoo]

Hi, I have one question about Statement.proposition becoming optional in 1.1.0.
I understand the motivation for nested Statements used through hasEvidenceLines: if the nested evidence-line Statement is evaluating the same proposition as its parent Statement, repeating the proposition may be unnecessary.
What I’m less clear about is the standalone case. In the ballot schema, Statement requires type and direction, but not proposition, so a standalone Statement can validate without identifying what the supports / disputes / neutral direction refers to.
Is that intentional? Or is omission of proposition mainly intended for nested evidence-line Statements where the proposition is clear from the enclosing Statement?
If the latter, I think it would be helpful to state that explicitly in the documentation or implementation guidance so producers and consumers don’t interpret proposition-less Statements differently.

[larrybabb]

It is an omission. The statement.proposition should be Conditional in that it is REQUIRED when it is used standalone.

[larrybabb]

We reversed the collapsing of EvidenceLine into Statement which should clarify the distinction you are requesting. Please refer to PR #449 for the changes that should help resolve this concern. If you feel there is still more content and description needed please let us know more specifically what is needed.

[ByungwoongYoo]

One small documentation issue I noticed:
The Examples page currently links readers to tests/fixtures at the 1.0.0 tag:
https://github.com/ga4gh/va-spec/tree/1.0.0/tests/fixtures
The 1.1.0 ballot has updated fixtures that reflect the model changes in this release, including the EvidenceLine → Statement changes and other renamed/restructured fields. So following the current link can show readers examples from the previous model version rather than the ballot they are reviewing.
Would it make sense for this link to point to the fixtures for the matching documentation version (or otherwise avoid pinning it specifically to 1.0.0)?

[larrybabb]

Good catch. Thank you. We will fix this.

[tnavatar]

My understanding based on the VA call today is that the changes to EvidenceLine were intended to be reverted, I see this in PR #449, although this has not been merged and the description of changes above has not been modified to incorporate this.

With the exception of the hopefully soon-to-be-removed changes to EvidenceLine--the rest of these changes seem generally appropriate. That said, they are significant, breaking changes to a release that affect all implementations of the spec. Only a week was originally given to review these changes. Effectively twelve hours has been given to review the changes after the change to EvidenceLine (still not reflected in the documentation or code, perhaps it would be more accurate to say no time at all has been given). It is hard to believe an appropriate review of these changes could occur in this timeframe. I suggest withdrawing and resubmitting this ballot proposal incorporating #449, and allowing a reasonable period for review (I don't see how this could be less than two weeks).

I do consider the remaining changes to be necessary and acceptable, but I would appreciate an understanding of the process for release and review from the GKM leads and whether what happened with this fits within that process. I would also appreciate an understanding of what one should expect with regards to the stability and usability of this model, or any of the models in GKM. There is a tension between having a v1 model and also having every class be labeled as 'trial use' and subject to change with potentially no notice.

[larrybabb]

#449 is up to date now. It will reflect the changes. We do not typically create a new ballot when we receive feedback but instead create a PR off of the current ballot that includes those changes. We can use this lesson to improve our process going forward for sure.

[larrybabb]

From @mbrush https://docs.google.com/document/d/1ZnF6OquX0qauFfNrqttWonB4mlwcHp4dQaOXK2Oyp3k/edit?tab=t.rtp10ycgyrxp

Modeling and Docs

• A couple new attributes that you added that we never discussed/agreed on - Statement.quality and EvidenceLine.qualityOfEvidenceProvided.

  • Guessing this is how you resolved the requirements / issues we were discussing in Slack here, which follows from the ticket here? We never finished/resolved this conversation - and I would like to do so next time we talk - I was never entirely clear on the use case / requirements that informed these additions.
  • I think I am ok with the use of quality on Statement, but I don't think you need qualityOfEvidenceProvided on EvidenceLine . . .I think that capturing the ClinVar review status on the Statement using the quality attribute would be the most accurate representation of what is being reported.
  • Let's discuss, and in the meantime maybe you can share a couple data examples from the ClinVar data?

• Can you review the DomainEntities page and confirm it accurately reflects any changes you guys made to how these are represented (I am not sure if it was updated correctly from its previous version:)

• Re: the following line in the Review Ballot here:

• "The abstract Proposition, StudyResult, and SubjectVariantProposition bases are now open, so implementers can define their own subclasses"

  . . . how is the 'openness' of these abstract classes signified/formally encoded in the schema? Or is this an external convention?

Diagrams
Address before release if possible (think that seem incomplete or wrong):

• It seems like many of the Class diagram boxes in the core class hierarchy diagram here are missing attributes (e.g. Statement is missing many fields like proposition, strength. MappableConcept is missing conceptType, mappings) . And many of the attributes shown are missing their range/data type. Can you check the code/agent that generates these to be sure they are complete.

• We need a dedicated Evidence Line data structure diagram for the general Data Structures page, and the EvidenceLine page . . . Like the one in older docs herel. Larry - can you have your agent workflow generate and insert such a diagram?

• The quality attribute is not shown in the Core Class Hierarchy diagram here, or the Statement Data Structure diagram here, but it does show up in the "Role of Propositions" diagram here.

OK to address after the release:

• Statement Data Structure diagram here - the free text notes under the Statement attributes describe outcome - why was this called out to discuss? The text then starts to describe hasEvidence but doesn’t. Also, the hasEvidence attribute in the Statement box says "omitted" - but the line for this is shown in the diagram.

• In the Data Structure diagrams for the Statement, EvidenceLine, and StudyResult classes - previous versions had italicized text in each object that gave examples of the type of info that would be represented in each object. e.g. the old Statement structure diagram:

I think this is one of the most informative things about these diagrams, that helps users understand what each class is for. Can the agentic tooling that generates the updated docs include such text? The tool is clearly capable of adding text to these boxes - as we see below describing the focus attribute:

I would rather have text with examples of content each class collects, than an explanation of how to use an arbitrarily selected attribute (this guidance can go elsewhere)

[larrybabb]

• Can you review the DomainEntities page and confirm it accurately reflects any changes you guys made to how these are represented (I am not sure if it was updated correctly from its previous version:)

I looked through the Domain Entities pages and feel like they are sufficiently correct for now. We should have a dedicated discussion on how we move forward with the concept of Domain Entities at some point, but I'm content with this for now.

[larrybabb]

Diagrams Address before release if possible (think that seem incomplete or wrong):

• It seems like many of the Class diagram boxes in the core class hierarchy diagram here are missing attributes (e.g. Statement is missing many fields like proposition, strength. MappableConcept is missing conceptType, mappings) . And many of the attributes shown are missing their range/data type. Can you check the code/agent that generates these to be sure they are complete.
• We need a dedicated Evidence Line data structure diagram for the general Data Structures page, and the EvidenceLine page . . . Like the one in older docs herel. Larry - can you have your agent workflow generate and insert such a diagram?
• The quality attribute is not shown in the Core Class Hierarchy diagram here, or the Statement Data Structure diagram here, but it does show up in the "Role of Propositions" diagram here.

@mbrush I believe I have made all these corrections at this point. Please review asap if you find any egregious oversights or mistakes that need immediate attention. Feel free to put any smaller or "non-urgent" changes in as a GitHub issue so we can deal with them when we come up for air.

[larrybabb]

• Statement Data Structure diagram here - the free text notes under the Statement attributes describe outcome - why was this called out to discuss? The text then starts to describe hasEvidence but doesn’t. Also, the hasEvidence attribute in the Statement box says "omitted" - but the line for this is shown in the diagram.

This has been changed completely and returned to its original representation but with clickable class boxes.

[larrybabb]

• In the Data Structure diagrams for the Statement, EvidenceLine, and StudyResult classes - previous versions had italicized text in each object that gave examples of the type of info that would be represented in each object. e.g. the old Statement structure diagram:

This has been changed completely and returned to its original representation but with clickable class boxes.

[larrybabb]

@mbrush I think I have addressed 100% of the issues you pointed out. Please review asap. The key is that we seem to now be aligned on the schema work, that was truly the only thing holding up the release. The documentation changes can continue even after the release, but it would be great if you can make a final pass and identify anything significant for now or give it the thumbs up. 👍

[Mrinal-Thomas-Epic]

@larrybabb Combining EvidenceLine and Statement makes sense to me as a simplification. I think the use of nested Statements in either hasEvidenceItems or hasEvidenceLines could be confusing though. When should the nested statement go in one place vs the other?