CDISC ODM 2.0 Migration: API and JSON/XML Compatibility

CDISC ODM 2.0 migration should be treated as a change to an exchange contract, with compatibility demonstrated for each producer and consumer. The Clinical Data Interchange Standards Consortium (CDISC) published the Operational Data Model (ODM) 2.0 on 23 August 2023, while ODM 1.3.2 was published on 1 December 2013. (^[1]) (^[2]) The newer standard is final, and CDISC explicitly states that it breaks backward compatibility. A successful migration therefore requires more evidence than changing a version attribute or accepting a schema-valid file. (^[3]) (^[4])

The principal implementation changes include nested item groups and the replacement of the earlier form definition by an item group classified as a form. (^[5]) The choice between Extensible Markup Language (XML) and JavaScript Object Notation (JSON) is a separate contract decision: system conformity requires support for at least one of those media, rather than both. (^[6]) The final-release announcement placed the JSON schema and application programming interface (API) specification among supplements to be developed. Searches for this report did not establish a later final ODM-specific endpoint specification. Consequently, generic Hypertext Transfer Protocol (HTTP) routes, error responses, and JSON mappings below are explicitly implementation choices, not claimed universal ODM API requirements. (^[7])

Controlled coexistence is appropriate when consumers require different structures or media, provided that identifiers, metadata versions, history, and rollback behavior remain traceable. Clinical migration evidence should address content and meaning, not merely file counts: the European Medicines Agency (EMA) advises keeping data, context, and audit trails connected, while the International Council for Harmonisation (ICH) recommends validated or otherwise appropriate reconciliation processes for electronic exchange and migration. (^[8]) (^[9]) The US Food and Drug Administration (FDA) also addresses validation of data transfers and interfaces. None of those sources certifies an ODM implementation or establishes a universal upgrade deadline. (^[10])

Available quantified implementation evidence is narrower than a modern migration benchmark. A historical portal paper reported more than 250 forms and approximately 8,000 items; another ODM assessment used one National Institutes of Health (NIH) protocol. These are contextual observations, not ODM 2.0 adoption rates. (^[11]) (^[12]) This report supplies a capability matrix, a consumer cutover matrix, and a contract-test checklist. Its project metrics are consumer coverage, round-trip preservation, and extension retirement, with explicitly hypothetical inputs. Teams can retain established contracts, adopt selected new capabilities, or retire a legacy path after their own evidence supports the decision.

ODM connects clinical data to the metadata needed to interpret it. The official repository describes interchange and archive roles, while identifying the newer model as replacing the earlier release. Those roles should be evaluated separately: an exchange sufficient for a downstream calculation can be insufficient for reconstructing a study record. (^[13]) Archive-oriented preservation also concerns significant properties, not merely readability in a new format. (^[14])

For electronic data capture (EDC) integrations, the central question is which contract changes affect an actual consumer. A metadata repository may need reusable nested structures; an operational service may need targeted transactions; an archive reader may need a complete linked history. The final specification distinguishes syntactic from semantic conformity, which explains why parser success alone cannot settle those decisions. (^[15]) Similarly, XML Schema identity constraints supply generic uniqueness mechanisms, but their correct application depends on the model's actual identifier scope. (^[16])

This is an implementation reference for clinical data architects, integration leads, metadata repository owners, and validation teams, current to 4 October 2026 as a research cutoff. The specification and release sources retain their own publication dates. The official release is final; descriptions of planned supplements are historical release statements, not evidence that every planned artifact subsequently shipped. (^[3]) (^[7])

The analytical perspective is that of an adjacent integration advisor. IntuitionLabs describes enterprise implementation and integration services; it is not presented here as an ODM software option. (^[17]) The report excludes vendor support assumptions, product rankings, and inferred conversion performance.

A baseline inventory should identify producers, consumers, payload profiles, extension schemas, metadata dependencies, and archive obligations. Processing modes and limitations belong in that inventory because ODM system conformity explicitly calls for their documentation. (^[18]) Existing parser configuration should be inventoried too: Apache Xerces, for example, documents that schema-validation errors depend on enabling the general validation feature. Merely naming a validator does not demonstrate that validation actually ran. (^[19])

Forms, item groups, and clinical structure

ODM 2.0 introduces nested ItemGroups, and an ItemGroupDef with Type="Form" replaces the earlier FormDef. The documented group types also cover sections, datasets, and concepts. This changes the structural contract for consumers whose navigation assumes a form layer. (^[5]) Repeating="Simple" corresponds to the earlier Repeating="Yes"; dynamic and static repetition introduce codelist-related behavior that should be tested independently. (^[20])

A mapping specification should state how it represents a former form, preserves its identifier, and handles nested groups. A flattening adapter needs an explicit rule for retaining parent relationships. These are implementation recommendations, not a universal conversion algorithm. The historical portal study's distinction between technical form models and layout information is useful here: preservation of field definitions does not establish preservation of rendering behavior. (^[21])

Study events now reference item groups, and the clinical-data keys documentation describes both subject-oriented and dataset-oriented hierarchies. A consumer must know which hierarchy it receives before interpreting repeated records or constructing a display. (^[22]) (^[23])

Identifier scope and metadata versions

An object identifier (OID) is unique within specified ODM contexts, rather than globally by default. SubjectKey identifies a subject within a study and is not intended as a cross-study subject identifier. (^[24]) (^[25]) An integration should therefore retain enough context to resolve identifiers, using an explicit internal composite key where necessary.

MetaDataVersion supports incremental study changes and inheritance through Include. A receiver should resolve the metadata version before interpreting values, preserve override behavior, and reject an unresolved dependency according to its documented contract. (^[26]) For partial exchange, maintain a dependency manifest rather than assuming that every incoming payload is self-contained. Preservation manifests offer an established pattern for documenting ingest actions and associated files. (^[27])

Audit context and signatures

The ODM AuditRecord definition makes history additive: it cannot be changed, only added to. The Signature definition concerns static content at a particular time and distinguishes that element from an embedded XML-based electronic signature. (^[28]) (^[29]) (^[30]) An adapter must not equate a preserved signature label with a newly verified cryptographic signature.

XML canonicalization can make digest computation insensitive to specified physical XML changes, but that does not establish signature survival after conversion to JSON. (^[31]) FDA guidance describes signature execution date and time among required signed-record information. Migration tests should separately inspect identity, meaning, time, signed scope, and any cryptographic evidence used by the implementation. (^[32]) Hashes can detect byte changes; they do not themselves prove preservation of clinical meaning. (^[33]) (^[34])

Localization and missing values

ODM TranslatedText requires a plain-text rendition even when enhanced text is supplied and specifies language/type behavior. Tests should include fallback and missing-rendition cases. (^[35]) Unicode compatibility normalization can remove meaningful distinctions, so a normalization policy needs explicit review. (^[36])

A JSON null is different from an absent property, while ODM null flavors have their own annotation-based representation and declared handling. Treat absent, empty, null, and qualified missingness as separate fixtures until the mapping contract establishes otherwise. (^[37]) (^[38]) JSON encoding and numeric precision require independent checks as well. (^[39]) (^[40])

API status, resources, and operation boundaries

The final release lists the API specification, JSON schema, and ODMPath among planned supplements; its non-normative changes page states that ODMPath is outside that specification. This report did not establish a later final ODM-specific REST contract. Representational State Transfer (REST) describes an architectural approach; it does not supply an ODM endpoint inventory by itself. (^[7]) (^[41])

The practical requirement is to obtain the producer's documented endpoints, returned resources, limitations, and processing modes. (^[18]) An OpenAPI document can express response content by media type, providing a reviewable service description without creating new ODM requirements. (^[42]) The separate Dataset-JSON API is based on Dataset-JSON and makes full create, read, update, and delete (CRUD) support optional. Its routes must not be substituted for an ODM metadata API. (^[43]) (^[44])

The implementation contract should specify:

• Resource boundaries: whether the service exchanges complete documents, definitions, subjects, transactions, or another agreed unit. Describe each response payload in the API contract. (^[42])
• Creation and replacement: distinguish append behavior from replacement. HTTP PUT is defined in terms of creating or replacing target state. (^[45])
• Partial updates: specify atomicity and failure behavior; HTTP PATCH requires an entire change set to be applied atomically. (^[46])
• Removal semantics: avoid mapping clinical missingness mechanically to JSON Merge Patch null, which has a removal meaning. (^[47]) (^[37])
• Concurrency and retry: document conditional-write requirements and rate-limit behavior. HTTP 428 Precondition Required and 429 Too Many Requests supply optional mechanisms for these concerns; the latter permits a Retry-After header. (^[48]) (^[49])
• Error payloads: choose stable machine-readable errors. Problem Details provides JSON and XML formats but is not automatically an ODM error model. (^[50])

Do not assume that an ODM Update transaction and an HTTP PUT request are interchangeable. ODM's transaction definition leaves unmentioned properties unchanged, whereas PUT describes replacement of target state. A service combining them must document precisely which resource is replaced. (^[51]) (^[45])

XML, JSON, and content negotiation

Content-Type identifies the representation's media type; Accept communicates response preferences. Test request and response behavior separately. (^[52]) (^[53]) The Internet Assigned Numbers Authority (IANA) registers application/json against the JSON specification, but that registration does not establish an ODM-specific JSON mapping. (^[54]) (^[55])

An implementation should publish supported media, unsupported-media behavior, and exact mapping rules. It should also distinguish the XML document namespace from the HTTP media type: namespace URI comparison is case-sensitive. (^[56]) A schema can constrain structure and identities; it does not replace a negotiation contract. (^[16]) (^[42])

For healthcare integration, Fast Healthcare Interoperability Resources (FHIR) provides a useful comparison, not an implied equivalence. FHIR R5 requires supported formats to be declared in its Capability Statement. (^[57]) It also gives decimal precision presentation significance, illustrating why a generic numeric parser can lose information a healthcare consumer expects. Apply each standard's own rules rather than borrowing them silently. (^[58]) (^[40])

Backward and forward compatibility experiments

Backward compatibility asks whether a newer consumer accepts the established producer contract; forward compatibility asks whether an established consumer accepts a newer producer's output. CDISC's compatibility warning means neither direction should be assumed without an experiment. (^[4])

• Established producer to established consumer: retain the baseline interpretation and comparison output. (^[34])
• Established producer to newer consumer: compare approved mappings against the exact target schema dependencies. (^[59])
• Newer producer to established consumer: test an adapter or documented rejection path; accepting parsable input does not establish semantic correctness. (^[16])
• Newer producer to newer consumer: exercise values and their representation, including precision and absence/null distinctions. (^[40]) (^[37])

Capability and evidence matrix

Table 1 below is a proposed contract matrix. “Breaking risk” identifies what to investigate; it is not a claim that a specific implementation fails.

Version or capability	Producer and consumer contract	Breaking risk	Test and retained evidence
Legacy form to new form group	Earlier form-oriented producer; newer metadata consumer	Structural navigation and form/group classification change. ([60])	Compare identifier, membership, nesting, and rendering assumptions; retain mapping decisions.
Nested groups	Newer metadata producer; flat legacy consumer	Hierarchical relationships can be lost in flattening. ([5])	Exercise nested and repeated paths; compare parent-child relationships, not just item totals.
Identifier and metadata context	Partial-exchange producer; repository consumer	An identifier can resolve differently outside its defined context. ([24])	Change metadata context deliberately; retain dependency and resolution logs.
XML to JSON representation	Producer and consumer using different media	Numeric precision, duplicate names, and absence/null can differ. ([40]) ([61]) ([37])	Compare typed values and preserved lexemes; retain canonical comparison output.
Transactional updates	Incremental producer; stateful receiver	Treating omitted properties as replacement can change state. ([51]) ([45])	Replay partial updates and failed atomic changes; retain before/after states. ([46])
Audit and signature context	Collection system; archive reader	Context can be disconnected from the associated data. ([8]) ([62])	Reconstruct history and signed scope; retain independent review.
Extension handling	Extended producer; standard consumer	Extensions need a describing XML or JSON schema. XML extensions require distinct namespaces, while JSON extensions must avoid naming conflicts. ([63])	Test standard-only and extended fixtures; retain extension schema and mapping.
Localization	Multilingual producer; display/export consumer	Normalization or fallback choices can change meaningful text. ([36]) ([64])	Compare language tags, exact text, and approved fallback output.
Archive package	Archiving producer; long-term reader	Readable files can still omit significant properties or dependencies. ([14]) ([27])	Reconstruct the package without the live source service; retain manifests and reconciliation.

An extended-file application must also accept standard ODM files; removing extensions should leave a meaningful, accurate standard file. This is a model requirement, rather than permission to discard clinically necessary context. (^[65]) (^[34])

The matrix separates model compatibility, representation compatibility, and operational compatibility. A consumer can pass one category and fail another. In particular, XML Schema validation provides structural machinery, while ODM conformity also concerns semantics. (^[16]) (^[15]) Keep the producer version, consumer version, schema revision, processing settings, and test corpus together as evidence.

The checklist below is an editorial implementation recommendation, grounded in the referenced model and technical guidance:

• Pin artifacts: identify the final release and exact schema artifacts used, rather than relying on a moving repository branch. (^[3]) (^[13]) The pinned XML entrypoint is schema/ODM.xsd, with target namespace http://www.cdisc.org/ns/odm/v2.0; it imports xml.xsd and includes ODM-foundation.xsd. The latter includes the component schemas. Retain this dependency set with the implementation. (^[59]) (^[66])
• Prove validation runs: retain validator invocation and failure output; configuration can determine whether errors are reported. (^[19])
• Exercise identity constraints: test duplicate keys, unresolved references, and the implementation's actual scope rules. (^[16])
• Reject ambiguous JSON: test duplicate object names rather than accepting whichever value a parser retains. (^[61])
• Preserve numeric meaning: compare lexical and numeric representations separately wherever precision matters. (^[40]) (^[58])
• Distinguish missingness: test omitted properties, explicit null, empty content, and the mapped missingness representation. (^[37]) (^[67])
• Constrain XML external access: test document type definitions and external resolution in parser, schema, and stylesheet stages. (^[68]) (^[69])
• Verify parser restrictions: retain effective settings; Java's XML-processing guidance explains that empty external-access permissions allow no protocol. (^[70])
• Test media negotiation: send supported and unsupported representations and confirm documented responses. HTTP 415 concerns an unsupported request format. (^[52]) (^[71])
• Test stale writes: exercise the selected conditional-request policy rather than assuming concurrent updates are safe. (^[48])
• Test retry behavior: distinguish a rate-limit response from an accepted operation and record the selected retry policy. (^[49])
• Test error structure: retain machine-readable error fixtures and confirm that clients can interpret them. (^[50])
• Protect history: reconcile transferred records and their metadata; copying should preserve content and meaning. (^[34]) (^[62])
• Review signature boundaries: compare signed-record details and any digest-dependent evidence independently. (^[32]) (^[31])
• Test text policy: use normalization conformance fixtures and inspect transformations that can remove distinctions. (^[64]) (^[36])

Negative tests should demonstrate the intended rejection or preservation behavior, not merely produce a log entry. The Open Worldwide Application Security Project (OWASP) publishes parser guidance. (^[72]) Its guidance addresses external resolution risks, while World Wide Web Consortium (W3C) schema guidance addresses structural constraints. These are complementary checks. (^[69]) (^[16]) Parser settings must also implement the intended external-access policy. (^[70]) Treat a successful parser run as one evidence item in a broader traceability record.

A coexistence period should have a single authoritative record for each defined exchange scope and an explicit reconciliation process. ICH's migration guidance supports validated or otherwise appropriate processes such as reconciliation, while FDA guidance recommends a justified, documented risk assessment for the validation approach. These principles support proportionate evidence without prescribing a universal project threshold. (^[9]) (^[73])

Table 2 below assigns proposed consumer-specific gates. The rows describe roles, not actual vendor capabilities.

Consumer role	Candidate migration path	Evidence before cutover	Rollback and retirement condition
EDC metadata importer	Retain the established profile until the new structure is supported	Validated transfer and configuration evidence for the actual interface. ([10])	Restore the approved metadata configuration and demonstrate reproducible interpretation.
Metadata repository	Introduce richer structures behind a versioned adapter	Reference resolution, mapped relationships, and successful semantic checks. ([15])	Recover the previous approved definitions and dependent study configuration.
Operational API client	Enable selected media and operations	Negotiation, error, atomic update, and conditional-request tests. ([42]) ([46]) ([48])	Route to the previous documented contract after reconciling accepted writes.
Statistical or tabular consumer	Retain the required dataset contract	Dataset and metadata evidence specific to that exchange, not assumed from a distinct API. ([43])	Reproduce the accepted downstream dataset and metadata package.
Multilingual viewer	Enable new text handling after review	Approved normalization and fallback fixtures. ([64]) ([36])	Restore the previous rendering rules without discarding source text.
Archive reader	Migrate only after independent reconstruction	Context, audit trail, metadata, and significant-property preservation. ([8]) ([14])	Keep an independently readable retained package until reconstruction is accepted.

The matrix prevents a single “ODM supported” label from authorizing every exchange. FHIR's explicit declaration of supported formats provides a useful interoperability pattern, while OpenAPI can document an individual service's media and responses. Neither source establishes a particular ODM vendor's support. (^[57]) (^[42])

The transition sequence should remain reviewable:

• Inventory dependencies: record source systems, retained packages, schema versions, and processing settings; document ingest and transformation actions. (^[27])
• Select a bounded pilot: choose a consumer contract with representative dependencies and a defined comparison method. Risk assessment should justify the validation approach. (^[73])
• Reconcile parallel outputs: compare meaning and context, not just counts or checksums. (^[34]) (^[8])
• Control write authority: test the chosen update and conditional-request behavior before enabling production writes. (^[46]) (^[48])
• Exercise rollback: restore the prior agreed state and replay only reconciled operations. Appropriate reconciliation is central to migration assurance. (^[9])
• Retire deliberately: retain the required evidence and significant properties after the legacy route closes. (^[14]) (^[74])

Archive migration deserves a separate gate. ODM's Archive context requires a transactional file or collection, complete nonredundant transactions through its as-of time, all available source audit and signature information, and no Upsert transactions. Linked collections can depend on earlier files. (^[75]) (^[76]) A JSON endpoint that serves only current values is therefore not evidence of a complete archive.

For preservation, retain original bytes where appropriate, manifests, schema dependencies, semantic comparison results, and an independently usable viewing route. The National Institute of Standards and Technology (NIST) provides hash guidance for change detection; the National Archives and Records Administration (NARA) records fixities for preservation auditing. These are evidence practices, not clinical retention-period requirements. (^[33]) (^[74])

What published quantities establish

Quantitative context should remain separate from migration acceptance. The historical ODM portal study reported more than 250 forms containing approximately 8,000 items and described technical models without layout information. The counts establish the scale of that reported implementation, not current holdings, rendering fidelity, or ODM 2.0 compatibility. (^[11]) (^[21])

Huser and colleagues used one NIH protocol and examined a complete study lifecycle. That design can illuminate mechanisms and lifecycle requirements, but it cannot supply a population-wide conversion success rate. (^[12]) (^[77]) This research did not establish contemporary independent conversion benchmarks, error rates, migration costs, or vendor support measurements.

The temporal baseline is equally specific: the official pages date the earlier release to 1 December 2013 and the newer release to 23 August 2023. (^[2]) (^[1]) The regulator sources are separate: FDA's catalog landing page is labeled March 2025, and its electronic-systems guidance is dated October 2024. These dates do not create an ODM upgrade requirement. (^[78]) (^[79]) FDA says only some standards are required and that applicability varies across centers. (^[80]) (^[81])

Project metrics and denominators

Table 3 below defines editorial project metrics. They are proposed measurements, not CDISC acceptance limits. Reconciliation and preservation guidance support examining completeness and meaning; they do not prescribe these formulas. (^[9]) (^[14])

Metric	Formula	Required denominator evidence	Interpretation
Consumer coverage	Tested consumers / known consumers	Dated consumer inventory and documented test scope	Indicates coverage of the inventory; it does not prove each consumer passed.
Round-trip preservation	Preserved applicable elements / applicable source elements	Defined applicable elements and comparison rules	Counts preserved elements while requiring separate review of clinical significance.
Extension retirement	Replaced local extensions / extensions inventoried	Extension register, replacement mapping, and owner decision	Measures replacement progress; legitimate retained extensions need not count as failures.

The denominators are as consequential as the percentages. Count a consumer only for the contract actually tested. Define “preserved” before counting it, including relevant context and metadata. A hash comparison answers a different question from a semantic comparison, and FDA's copying guidance focuses on content and meaning. (^[33]) (^[34]) Keep significant-property definitions alongside the result. (^[14])

Calculation and precision fixture (Hypothetical Example)

With assumed inventories, 6 tested consumers out of 8 yield 75% coverage; 11 preserved applicable elements out of 12 yield approximately 91.7% preservation; 3 replaced extensions out of 5 yield 60% retirement. These are reproducible arithmetic examples, not observed project outcomes or acceptance thresholds.

As a hypothetical illustration, consider a generic XML-to-JSON fixture designed to test preservation of a study identifier, metadata-version identifier, item identifier, decimal string, language tag, and extension value. Include a separate check to distinguish an absent property from explicit null. If a transformation changes the decimal string 0.010 to 0.01, the comparison should flag the change as lexical loss. This proposed fixture would not be an ODM instance, schema-validation result, or conversion benchmark. It illustrates why JSON numeric limits, absent/null distinctions, and presentation precision need explicit tests. (^[40]) (^[37]) (^[58])

The decision should follow the capability that creates value for the actual exchange. Nested structures, richer text handling, and transactional operations can justify a bounded change, but release status and artifact availability need separate tracking. The final-release notes distinguish the core standard from planned supplements, so a standards register should record the exact artifact supporting each enabled capability. (^[7]) Retain the producer's API description beside the tested interface contract. (^[42])

For healthcare-linked work, declared format support and precision semantics offer useful comparison points. FHIR documents both, but it does not make ODM and FHIR payloads interchangeable. (^[57]) (^[58]) Teams should maintain explicit mappings, approved text policies, and negative fixtures for the standards they actually use. Unicode conformance testing and JSON's distinct null behavior supply relevant building blocks. (^[64]) (^[37])

Regulatory interpretation should remain scoped. FDA's Part 11 guidance concerns applicable electronic records, while its clinical-investigations guidance addresses systems, records, and signatures. (^[82]) (^[83]) ICH's final principles and Annex 1 document was adopted on 6 January 2025; this citation does not establish implementation dates in every jurisdiction or the status of other annexes. (^[84]) Applicable center, submission type, and current catalog should be checked independently. (^[78]) (^[81])

IntuitionLabs' first-party description of data pipelines and integration provides the adjacent consultancy perspective: evidence should connect the exchange contract to the receiving workflow. It does not establish product-level ODM support. (^[85]) An implementation record should connect parser settings, API contracts, semantic comparisons, and preservation evidence rather than treating any one artifact as complete assurance. (^[19]) (^[42]) (^[74])

Before publication or a production decision, recheck the official release, schema location, available supplements, and applicable regulatory sources. This session did not establish a separate errata publication; that is a research limitation, not evidence that errata cannot exist. Keeping source dates and pinned artifacts visible allows later changes to be assessed without rewriting the project's earlier validation history. (^[3]) (^[86])

ODM migration is a compatibility decision across a chain of producers and consumers. The final standard's backward-compatibility warning makes a version-label change an inadequate migration method. A controlled transition should retain an explicit mapping, an agreed processing contract, and evidence of what each consumer can actually interpret. (^[4]) (^[42])

Remaining on an established profile can be reasonable when it meets the exchange's needs. Selective adoption can be reasonable when a bounded capability has demonstrated value and consumers have passed the corresponding tests. Full retirement of a legacy route requires confidence in reconciliation, reconstruction, and the retained evidence. Appropriate migration reconciliation and preservation of significant properties provide the relevant principles. (^[9]) (^[14])

The useful project metrics measure inventory coverage, applicable-element preservation, and extension replacement. They become decision evidence only when their denominators and significance rules are visible. A syntactically valid payload, an unchanged checksum, and a semantically faithful record answer different questions. XML Schema supports structural validation, NIST describes digest-based change detection, and FDA emphasizes preserving record content and meaning. (^[16]) (^[33]) (^[34])

The recommended outcome is a consumer-specific migration record: exact artifacts, media and operation contracts, mapping decisions, negative tests, reconciliation results, and an exercised rollback path. Archive readers need independently reconstructable context and preservation evidence after the live service changes. (^[8]) (^[74]) That record lets teams adopt ODM capabilities at a justified pace while keeping the clinical meaning and history of their data reviewable.