---
title: "2026-08-28 vxData domain representation compatibility review"
description: "Reviewed mono PR #350 for schema, API, SDK, migration, versioning, tests, and consumer compatibility."
image: "https://docs.virdx.dev/img/virdx-social-card.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.virdx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026-08-28 vxData domain representation compatibility review

## Work Done

- Reviewed every changed file in mono PR #350 in full, without editing the PR branch or posting comments.
- Regenerated the vxData schema families and SDK typed namespaces in a temporary worktree; the committed generated files were exact.
- Verified the Alembic revision follows the current head and matches the SQLModel additions.
- Reproduced that vxdata-schemas 3.1 response models reject the new `HistoMap.task` and `HistoDomainRep.type` literals, so the 3.2 minor release is not wire-compatible for older SDK consumers.
- Verified that `HistoDomainRep(type="TISSUE_GLEASON_CELL")` accepts all new v2 map references as `None`, despite the model docstring treating the bundle as the completeness marker.
- Confirmed the PR adds no committed regression test for the new schema values or API persistence round trip.

## Lessons Learned: Pitfalls

- The PR description still mentioned an older histo SDK pin, while current `virdx/histo` main pins `vxdata-sdk >=3,<4`; consumer claims should be checked against the live consumer.
- An additive enum member is not necessarily backward compatible in a response model: older Pydantic `Literal` validators reject newly emitted values.

## Lessons Learned: Improvements

- Document vxData wire-compatibility rules for response-side `Literal` expansion and require a major version or tolerant response schema when adding values.
- Add committed API round-trip tests for each schema migration and conditional validation tests for discriminator-like fields such as `HistoDomainRep.type`.

Source: https://docs.virdx.dev/knowledge/inbox/2026-08-28-infrastructure-vxdata-domainrep-compatibility-review/index.mdx