# Versioning and Conformance

| Field | Value |
|---|---|
| Document | ONDC-RFC-002 |
| Status | Draft RFC; Not Adopted |
| Related Draft | `1.0-draft.1` |
| Updated | 2026-11-03 |

## Purpose

Readers should be able to distinguish an experiment, a supported profile and a stable release. Implementers need explicit information about changes, migration and preservation behavior.

This note summarizes existing draft boundaries and proposes publication requirements. It does not introduce a new version number, freeze the draft, or select a universal release-numbering scheme.

## What A Support Claim Should Tell A Person

“Supports ONDC” is too broad to be useful. A person needs to know whether an application can read their file, let them edit it, save it without losing information, and reopen it elsewhere. An implementer needs the exact version and feature boundary behind each promise.

This RFC proposes how to make those claims precise. The following release rules and support categories are proposals. Existing implementation facts are identified separately; this document does not make an unimplemented feature available or establish a certification program.

## Draft Baseline

- ONDC document draft: `1.0-draft.1`, experimental.
- Earlier core 0.1 documents remain an import path in the local application.
- The running editor supports a narrower text profile than the full draft represents.
- Broad examples demonstrate representation, not complete editor, renderer or converter support.

## Versions And Profiles Answer Different Questions

| Identifier | Question It Answers | Current Example |
|---|---|---|
| Source version and namespace | Which vocabulary and meaning does this document declare? | `1.0-draft.1` and its provisional namespace |
| Consumer profile | Which subset does an implementation understand and preserve? | Headless `draft-text-1` |
| Editor capability boundary | Which of those features can the interactive editor safely expose? | Narrower one-section text/page subset |
| Application release | Which build contains the behavior? | Reported by the application, not inferred from the document version |
| Storage/encryption version | How are private records encoded, authenticated and recovered? | Separate local-vault contract |

A profile name describes an implementation contract. It does not mean the profile is necessarily written into each source file. The existing draft is experimental, and profiles are not evidence of a frozen standard. A future version-numbering scheme still needs review; this RFC does not reserve a particular next version or promise semantic-versioning rules.

The public `.ondc` extension identifies the selected format name. It cannot replace checking the contents. Changing the extension does not migrate XML, and changing a version attribute alone does not make older content conform to a new contract.

## A Reader's Decision Path

An application should determine support before changing the working document:

1. Safely inspect the envelope and declared version within its resource limits.
2. Select a known decoder. If no decoder exists, stop with a useful version diagnostic.
3. Validate the declared structure and semantics.
4. Check the consumer's feature/profile limits and then the editor's narrower limits.
5. Return a supported document only after every required check succeeds.

The current text/editor import path follows an atomic refusal policy. Unknown native elements, attributes and versions are rejected. The caller retains the original input and open document. It does not strip content to produce a file that appears supported.

The broader storage draft describes extension envelopes, but that does not give the current editor a preservation engine. An unsupported required feature can belong to a meaningful document while still requiring a different consumer. A valid envelope is insufficient permission to save a reduced version.

## Three Cases That Must Stay Distinct

### An Earlier Supported Document

The prototype can import the earlier core 0.1 representation and create its supported current draft model. The migration preserves structural IDs, exact text, list starts and first-row headers while adding the required section and metadata structure. A new section ID is checked for collisions.

That is an implemented migration, not a general converter between all draft versions. Automatic downgrade is not provided. A future publication should name the exact source and destination versions and the features covered by each migration.

### A Valid Feature Outside The Editor

Suppose a document uses a richer feature represented by the broader draft but unsupported by the interactive editor. The editor should explain the unsupported feature and leave both the file and current work intact. Headless validation can establish that some broader rules hold without making that file safely editable in the application.

A future read-only preview or preserving editor could offer more options, but must prove its own behavior. It should not inherit an editing claim simply because it can display a placeholder.

### Invalid Or Oversized Input

Duplicate IDs, invalid property values and missing reference targets are errors in the declared model. Exceeding a consumer's declared size or depth limit is a resource-limit failure. Those are different diagnoses: a file too large for one consumer is not necessarily corrupt.

In either case, no partial result should replace the person's working copy. A useful diagnostic identifies the rule, location or feature when possible. Messages here describe expected behavior, not a promised public error-code API.

## What Must Survive A Read/Write Cycle

Preservation should be evaluated at the right level. Identical bytes, equal document meaning and equal page appearance are separate properties. The text writer can normalize attribute order, numeric spelling and color case without preserving original bytes. It must still preserve text, identity, effective formatting and required relationships within its supported scope.

For example, a span explicitly setting `italic="false"` inside italic content must not be discarded as a redundant default. Whitespace inside prose must not be reformatted into different text. A Unicode range cannot be moved into the middle of a surrogate pair just because an editor and a model count positions differently.

For supported operations, fixture comparisons should check the requested change and preservation outside it. An undo or failed operation should retain the original model. Renaming document metadata is not permission to rewrite headings. A copied subtree needs fresh IDs and correctly remapped internal references.

Full page appearance additionally depends on fonts, shaping, layout and renderer behavior. A source round trip cannot establish pagination fidelity. Conversion to office formats needs explicit feature mappings and loss reports; those converters remain unimplemented.

## Proposed Evidence Categories

| Claim | Minimum Evidence To Publish | What It Does Not Establish |
|---|---|---|
| Can parse | Safe decoding and rejection cases for a named version | Complete semantics or editing |
| Can validate | Grammar plus declared semantic checks and limits | Rendering or preservation |
| Can read/write a profile | Deterministic writing and meaning-preserving round trips | Unsupported feature families |
| Can edit a profile | Operation, undo, reference and failure fixtures | Concurrent editing or arbitrary AI edits |
| Can render | Defined resources and layout comparisons for stated features | Office import/export fidelity |
| Can convert | Feature mappings, loss reports and output checks | Universal lossless interchange |
| Can preserve unsupported objects | Original resources and dependencies survive allowed changes | Understanding or editing those objects |

These categories are proposed publication requirements, not current badges or certification levels. A product should report the subset actually demonstrated, including known failures and platform limits.

## What A Published Release Should Include

In addition to a version label, a release should provide a fixed reference text, schema/property definitions, representative files, positive and negative tests, profile descriptions and changes since the prior publication. The examples and checker should agree with the prose. When they disagree, that is a defect to resolve, not permission to choose whichever reading accepts more input.

The release record should link design decisions, migrations and known losses. Experimental features should remain labeled. A stable claim should require independent implementation evidence, including two consumers preserving the included model's meaning and identity, rather than relying only on tests of one codebase against itself.

Publishing an accepted RFC is not enough. Feature implementation, documentation and the chosen release gates must be complete for the specific support claim. An RFC can remain accepted while its feature is still unavailable.

## Migration And Failure Recovery

A migration should read the original into a known model, validate it, construct a candidate for the target version, validate the candidate, and retain the original until the new result is safely accepted. The publication must explain whether the migration is reversible and what information, if any, is lost.

If meaning cannot be preserved, the application should refuse automatic migration or offer an explicit lossy export with a clear report. Saving under a newer version label while silently dropping content is not migration. Repeated migrations, interrupted writes and insufficient storage also need tests wherever persistence is involved.

Source conversion is separate from encrypted catalog or storage migration. Changing document versions must not discard vault capabilities, user preferences, checkpoints or recovery material. Backup/restore and provider migration require complete workspace contracts; exporting selected XML files alone does not establish them.

## Unresolved Policy Choices

The project still needs to agree how draft identifiers evolve, when profile revisions require a new identifier, how long old readers remain supported, and how security fixes interact with compatibility. Stable-release authority, licenses, independent review and a conformance publication process also remain open.

This RFC proposes a reviewable direction: precise support claims, preserved originals, executable examples and clear failure boundaries. It does not freeze the format or claim that layout, office interchange, remote persistence, sync or collaboration are implemented.

## References

- [ONDC Architecture Overview](native-format-overview.md): source, editor and storage responsibilities.
- [RFC Process](change-proposals.md): proposed change-review lifecycle and decision records.
- [Format Comparison Methodology](comparison-methodology.md): what the public sample does and does not measure.
- [CommonMark 0.31.2](https://spec.commonmark.org/0.31.2/), §§1.2–1.3: concrete cases and testable interpretations as an editorial reference.
- [Rust RFC process](https://rust-lang.github.io/rfcs/): design approval and implementation tracked separately.

External references accessed 2026-11-03. These are references for technical communication and process, not an adopted external conformance policy.

## Feedback

Questions and proposed improvements can be sent to hello@skydreamcloud.com until public proposal channels are available.