Finding model format evolution

What this document collects

The released Open Imaging Finding Model (OIFM) record format is described in the finding model format. This document collects the goals that have been stated for changing it, with the source that states each one. Nothing here is implemented on main of any repository, and nothing here is a proposal by this knowledgebase.

Four separate threads are in play, and they are not coordinated with each other: a metadata rewrite on a findingmodel branch, a source schema version 2 draft circulating in the common data element work, relationship and graph ideas coming out of the next-generation CDE vocabulary, and a versioning plan for packages and database artifacts.

The canonical structured-metadata rewrite

The most advanced thread. The design document on feature/metadata-cleanup states the goal as making structured metadata “canonical FindingModel state rather than disposable enrichment output,” supporting structured browse and related-model retrieval on top of it, and keeping review and provenance artifacts out of the canonical model JSON.¹

It adds eight optional fields to both finding model classes: body_regions, subspecialties, etiologies, entity_type, applicable_modalities, expected_time_course, age_profile, and sex_specificity. Their permitted values are listed in the format document; the pipeline that populates them is described in the enrichment pipeline.

Two constraints ride with it. Canonical index_codes are narrowed to exact or clinically substitutable matches, with broader, narrower, and merely related candidates diverted to a separate review artifact. And model-level entries in index_codes and anatomic_locations are rejected when display is empty.¹

Status as the branch reports it. The execution plan on dev records slices 1 through 8 and 9-A complete, with slice 9-B, migrating the MCP and command-line callers plus a bulk backfill, and slice 10, backfill, fixtures, and final documentation, remaining.² The branch’s own readiness assessment fails: the 2026-06-03 prompt-improvement document raises expected time course to between 0.76 and 0.78 and etiologies to between 0.91 and 0.93, then states that overall readiness remains a failure because age profile and index codes are below the quality floor.³

The source schema version 2 draft

A separate and broader draft, dated 2026-04-20 and marked “a proposed authoring schema, not an implementation-complete contract yet,” is kept in the next-gen-2026 branch of ACR-RSNA-CDEs as a copy of an upstream gist.⁴ It proposes a different decomposition of the format than the metadata rewrite does, and the two have not been reconciled.

Proposal	What the draft says
Source against hydrated models	A source .fm.json is authored; a hydrated model is the fully resolved form after canonical references expand. Runtime APIs and indexing operate on hydrated models
Canonical attribute reuse	presence and change from prior are defined once in <OIFMA_ID>.attribute.json files and referenced, not redefined. A reference may override the description and value descriptions, not the structure
Authored relationships	related_models holds only the assertions authored on that model, each naming a relationship_type from a registry. Tooling derives inverses; authors do not maintain both sides
Lifecycle	status of active or deprecated, with deprecated_reason, replaced_by_oifm_id, and deprecated_at
History sidecars	A per-model .history.jsonl with typed events carrying actor kind, actor identifier, source system and tool, model version, summary, target schema version, and a content hash
Registries	relationship_types.json and quantity_kinds.json alongside the corpus
schema_version on the record	Required, "2.0" for version 2 source files

The draft also lists explicit removals and changes against the current shape: drop required; replace the numeric unit with quantity_kind plus optional common_units; add synonyms to attributes and choice values; add model-level references; add lifecycle and related_models; allow canonical attribute references; and keep hydrated output close to the current structure.⁴

Five decisions are left open in the draft itself, including whether runtime APIs expose both the authored and the effective relationship views, where registry files live, and whether canonical attributes may be numeric or carry index codes.⁴

Relationships and the graph, from the CDE work

The project lead’s stated goal for the format, recorded in the knowledgebase build plan, is increased metadata plus the relationship and graph work coming out of the common data element effort.⁵

That effort is described in the next-generation vocabulary. Three of its ideas bear directly on the finding model format.

• Typed, identified relationships. Eight relationship pairs plus a catch-all, each carrying its own identifier so a report-level assertion can cite the standing potential it expresses.⁶
• The differential as a derived view. Computed by traversing manifestation edges and filtering by context, with no DIFFERENTIAL_OF edge type.⁶
• Properties on edges. Typicality on the HPO and Orphanet frequency scale, and a three-value specificity, both optional and independent.⁶

The relationship documents record the gap plainly: the registry exists only in the version 2 draft, and the live findingmodels repository implements no relationship mechanism at all.⁶

Versioning

Two open issues cover versioning, and both are about packages and database artifacts rather than about the record format.

Issue 30, versioning, packaging, and publishing, asks for a semantic versioning policy across the monorepo packages, a build and publish pipeline covering tags, changelog, and release notes, and maintainer documentation.⁷

Issue 29, schema versioning future plan, depends on issue 30 and covers the DuckDB artifacts: add a _metadata table carrying schema version, content version, build time, and record count; upgrade the manifest format to version 2 with an entries array per package; add a REQUIRED_SCHEMA constant per package with selection logic; and update the publish flow to write the correct manifest entry.⁸ The task plan behind it states the governing rule: “A package version requires exactly ONE schema version,” with backward compatibility coming from the manifest keeping old schema databases available. It is marked deferred until after an initial release.⁹

Record-format versioning appears only in the version 2 draft’s schema_version field, and in the dual-database release plan described in the enrichment pipeline, which avoids a breaking migration by publishing a legacy-compatible artifact alongside a metadata-aware one.

Superseded, and still open as an issue

The original eight-facet classification specification is superseded. Two task documents on main carry it, the task status summary marks it “Blocked - needs 4 design decisions” covering scope, required against optional, markdown representation, and search indexing,¹⁰ and the canonical metadata implementation plan states that it supersedes the facets plan for this workstream.² Issue 25 remains open against the old design.¹¹

Four other open findingmodel issues shape the format rather than the tooling. Issue 5 asks for three model variants: a content-only form for language model extraction, a draft form carrying everything but identifiers and contributors, and the full saveable form.¹² Issue 3 asks for a human-editable markdown form without identifiers or codes, issue 4 for a tool that folds edits to that markdown back into the JSON while preserving identifiers, and issue 8 for a FindingObservation concept holding worked examples of a finding model in use.

Identifier lifecycle, which no thread covers

Identifier stability is enforced today only against duplicates. Nothing in any repository documents deprecation, retirement, supersession, or versioning of a published OIFM or OIFMA identifier, and the released format carries no version field. The version 2 draft’s lifecycle object is the only stated mechanism for retiring a model, and it is a draft.

Meanwhile the opposite problem is open as a defect. Issue 42, filed 2026-04-18, records that loading a registered definition through the base class silently discards its identifiers, after which the identifier-adding helper mints fresh ones, which the issue calls “a silent data-integrity hazard” for any workflow that mutates an existing file. Four candidate fixes are proposed in the issue and none has been chosen.¹³

Three uncoordinated schema extensions on content branches

The findingmodels content repository carries the schema files that mirror the format, and three unmerged branches extend them independently. The metadata branch adds 347 lines to finding_model.schema.json and a new section to the prose mirror.¹⁴ The CT chest branch and its ancestor add 200 lines to the same file plus a new 522-line findingmodel_full_schema.json.¹⁵ The older CDE-to-finding branch adds a different 200 lines. None has landed on main, and no document reconciles them.

Discrepancies a revision would have to settle

Two are recorded in the format documentation and are carried in open questions rather than resolved here.

• Choice value code indexing. The prose mirror on main numbers the first choice value .1; the validator in the released code writes .0, and the stored corpus follows the code.¹⁶
• Omissions in the prose mirror. It omits anatomic_locations from the full model entirely, and states none of the length and cardinality constraints the code enforces.¹⁶

The content-side direction, which is separate from the format, is in the content direction roadmap.

Footnotes

1. Canonical Structured Metadata and Enrichment Rewrite, feature/metadata-cleanup branch ↩ ↩²

2. Canonical structured metadata implementation plan, findingmodel dev branch ↩ ↩²

3. Holistic etiology and tempo prompt improvement, 2026-06-03 ↩

4. FindingModel Source Schema v2 Draft, 2026-04-20 ↩ ↩² ↩³

5. Knowledgebase build plan ↩

6. The finding and diagnosis relationship family, next-gen-2026 branch ↩ ↩² ↩³ ↩⁴

7. findingmodel issue 30, “Versioning, packaging, and publishing” ↩

8. findingmodel issue 29, “Schema versioning future plan” ↩

9. Schema versioning future work plan, findingmodel main branch ↩

10. Task status summary, findingmodel main branch ↩

11. findingmodel issue 25, “Facets implementation” ↩

12. findingmodel issue 5, “Expand to multiple versions of FindingModel” ↩

13. findingmodel issue 42, identifiers regenerated on round trip ↩

14. Finding model schema prose mirror with metadata fields, findingmodels-metadata branch ↩

15. findingmodel_full_schema.json, findingmodels content/chestcts branch ↩

16. Finding Model Schema, prose mirror, findingmodels main branch ↩ ↩²