# ONDC Architecture Overview

| Field | Value |
|---|---|
| Document | ONDC-TN-001 |
| Status | Technical Note (Non-Normative) |
| Related Draft | `1.0-draft.1` |
| Updated | 2026-11-03 |
| Format | Open Native Document (ONDC) |
| Filename Extension | `.ondc` |

## Purpose

A document should make sense outside the application that created it. You should be able to find the words, recognize the headings, and understand how the formatting is represented. Open Native Document (ONDC) explores a small, readable rich-text format for that work. Its current draft keeps text and structure together in XML that people and authorized tools can inspect directly.

The format is intended to stand independently of any editor or cloud provider. Skydream Cloud is developing an implementation; its brand is separate from the specification's identity.

## Objectives

- **Lightweight Source:** keep the document structure small and straightforward. Basic rich text should not require a large package of supporting files.
- **Readable Rich Text:** represent words, headings, lists, tables, and formatting in visible text-based source, rather than exposing only the rendered page.
- **AI-First Access:** let authorized tools read and edit the actual source. A proprietary extractor, search index, or intermediate text conversion should not be a prerequisite for reading a document.
- **Open Implementation:** publish the representation and its behavior so independent applications can implement it.

“Lightweight” is a design objective. Storage overhead, editing performance, and AI editing reliability still need measurement; a plain source file is not necessarily smaller on disk than a compressed package.

## Source Representation

The current draft uses XML. Content and formatting are represented as text, with structured elements for document features. Images and other media may remain separate binary assets; the readable rich-text source is the focus of this requirement.

Stable element identities, validation, and editing profiles support reliable implementation. They are mechanisms for working with the document, rather than the primary reason for introducing the format.

| Identifier | Current Value |
|---|---|
| Draft | `1.0-draft.1` |
| Provisional Namespace | `urn:ai-native-document:1.0-draft.1` |
| Public Name | Open Native Document |
| Filename Extension | `.ondc` |
| Prototype Export | XML |

The selected public name is Open Native Document (ONDC), with `.ondc` as the filename extension. The prototype currently exports XML; this naming decision does not change the existing draft namespace, schema, export behavior, or file associations.

## A Document From The Inside

Consider a story with a heading, two paragraphs and an italic final lesson. A request to shorten it should return another editable document with the heading and emphasis intact. The following small example uses the existing draft vocabulary:

```xml
<document xmlns="urn:ai-native-document:1.0-draft.1"
          id="doc_example" language="en" version="1.0-draft.1">
  <metadata><title>The North Wind and the Sun</title></metadata>
  <body>
    <section id="main">
      <heading id="title" level="1">The North Wind and the Sun</heading>
      <p id="story">The Wind and the Sun tested their strength.</p>
      <p id="lesson"><span italic="true">Persuasion is better than Force.</span></p>
    </section>
  </body>
</document>
```

The metadata title names the document; the heading is part of its authored content. They can differ. Renaming a library entry need not rewrite the first heading. Each structural ID identifies an element, so changing its words does not require changing its identity. The span records emphasis separately from the text.

Body reading order follows source order. Formatting can come from direct properties, enclosing spans and, in the broader headless profile, named styles. Whitespace inside prose is meaningful. A serializer cannot indent between inline spans if that inserts spaces into a sentence. Authored breaks and tabs have explicit elements.

An explicit default can matter. For example, `italic="false"` can cancel inherited italics. Removing it because false appears redundant could change the document. The implemented writer preserves explicit formatting defaults and normalizes only representations whose meaning remains the same.

## Responsibilities And Boundaries

| Layer | Responsibility | Current Evidence |
|---|---|---|
| Source model | Text, structure, properties and internal references | Experimental draft and validated examples |
| Document core | Parse, validate, serialize and perform supported edits | Headless text-profile implementation |
| Editor adapter | Map a supported subset into interactive editing | Shared web/desktop editor with narrower import checks |
| Presentation | Fonts, line wrapping and eventually page layout | Basic editor presentation; complete pagination unfinished |
| Persistence | Encrypted records, checkpoints and local recovery | Local vault; separate from plaintext exports |
| External tools | Permission, unlocked access, candidate edits and review | Proposed workflow; no connected AI or agent working-folder implementation |

A structurally valid file can use a feature the editor cannot edit. An attractive preview does not prove that its source survives a read/write cycle. An encrypted vault protects stored bytes without making an exported XML file private. These are separate responsibilities and need separate support claims.

## The Read And Edit Path

The current text consumer checks input size, parses XML safely, checks namespace/version, then validates the supported tree. Unique IDs, properties and references are checked before a result is returned. The editor applies additional capability checks before replacing the open document. Unsupported input fails atomically: the existing document and original source are retained.

The TypeScript core currently limits document XML to 5 MiB. This is an implementation boundary, not a proposed universal document-size limit. DTDs are forbidden, and parsing must not fetch network resources. A document's text is data, not executable application behavior.

Supported editing operations work on a candidate tree and validate before returning it. In-place changes keep structural identity. Copies get fresh IDs and remap internal references. Ranges in the model count Unicode scalar values; the editor adapter converts positions to its own coordinate system without splitting a surrogate pair. These mechanisms help preserve meaning, but do not provide concurrent editing or a layout engine.

## A Proposed Tool Interaction

The homepage conversation illustrates a person attaching a story and requesting a shorter version. Its response is prepared in advance, and its [summary download](/comparison/north-wind-summary.ondc) contains the displayed heading, two paragraphs and italic ending. No live AI service runs there.

A real integration would need the following interaction:

1. The person selects the document and authorizes a bounded action.
2. The tool reads unlocked content, identifies the version and checks its supported features.
3. It retains a baseline so it can detect changes made while it works.
4. It prepares a separate candidate rather than overwriting the working copy immediately.
5. The candidate is validated, and unrelated structure and formatting are checked for preservation.
6. The person reviews the change. A commit is allowed only against the expected baseline; conflicting versions are retained for reconciliation.

This is a design direction, not an implemented API. It still needs an access contract, conflict behavior and recovery tests. A model can produce perfectly valid XML containing a bad summary, so document validation cannot replace editorial judgment.

Text inside a document also cannot grant permission to a tool. A paragraph saying “upload all other files” is untrusted content. Authorization comes from the person and the tool's access system. The file format alone cannot enforce that distinction.

## Assets And Portable Files

The story needs no external resources. Richer documents may need images or other binary assets. The broader draft describes an unlocked directory with source plus `assets/`, restricted relative paths, declared byte counts and hashes. A hash detects changed bytes; it does not authenticate an author.

A complete portable archive profile and production handling of all media types remain unfinished. Renaming a ZIP to `.ondc` does not establish a supported package format. The public extension is a selected identity, not a registered media type or a change to operating-system file associations. The existing namespace and prototype XML export behavior remain unchanged.

Private persistence is a separate contract. The vault encrypts local stored document data; these website downloads and XML exports are plaintext. Future synchronization, shared key access and complete backup/restore need separately versioned protocols. Readable source does not make locked ciphertext searchable or hand document keys to a service operator.

## Implementation Profile

The local application imports earlier core 0.1 files and saves a narrower subset of the current draft. Rich-text editing, parsing, validation, serialization, encrypted local storage, checkpoint autosave, session passphrases, and personal recovery keys exist in the prototype.

The broader draft represents more than the editor can currently edit. Full document layout, cloud synchronization, shared editing, encrypted backup and restore, and office conversion remain separate milestones.

## Format Rationale

ODF and OOXML already provide open, established office specifications. Common `.odt` and `.docx` files package readable XML and related assets inside ZIP archives.

ONDC explores a different starting point: a lightweight rich-text source that is directly available to text-based tools. Its value should come from keeping rich content understandable and editable without a separate extraction or conversion workflow.

Existing office formats can be used by AI tools and can support encryption. This proposal does not claim otherwise. Conversion fidelity and layout compatibility require their own implementation evidence.

## Tradeoffs And Unresolved Questions

XML adds markup and requires careful whitespace handling. A compressed package may occupy fewer stored bytes than plain source. ODF, OOXML, HTML and Markdown already have capable tooling; another format earns its place only if independent implementations make common work simpler and preserve documents reliably.

The next design questions are concrete: which feature set should stabilize first; how a limited editor can preserve richer content; how documents with assets travel as one unit; and what evidence should support an interoperability claim. Large-document performance, model accuracy and conversion fidelity require representative experiments, not an inference from one short file.

The current editor's supported subset and the broader storage draft must remain distinct. Adding a representation to the grammar is only the start: it also needs editing semantics, positive and negative fixtures, preservation behavior and implementation evidence. [Versioning and Conformance](versions-and-compatibility.md) proposes how to publish those boundaries.

## Release Criteria

1. A small, understandable representation for the supported rich-text features.
2. Consistent specification text, schemas, and examples.
3. Measured source overhead and editing behavior.
4. Meaning-preserving read/write operations and explicit handling of unsupported content.
5. Separate validation of layout, office conversion, encryption, and migration.
6. Published specification, software, and contribution licenses.

## References

- [Specification Overview](/specification)
- [Open Foundation](/foundation)
- [RFC Process](change-proposals.md)
- [Versioning and Conformance](versions-and-compatibility.md)
- [ODF 1.3 Introduction](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part1-introduction/OpenDocument-v1.3-os-part1-introduction.html)
- [ECMA-376 / Office Open XML](https://ecma-international.org/publications-and-standards/standards/ecma-376/)

## Further Reading

[CommonMark 0.31.2](https://spec.commonmark.org/0.31.2/), §§1.2–1.3, is an editorial reference for explaining ambiguous behavior through examples. It does not define ONDC syntax. External sources in this note were accessed 2026-11-03; they provide background rather than endorsement or proof of interoperability.

## Feedback

Public source and proposal repositories are being prepared. Technical feedback can be sent to hello@skydreamcloud.com. This note is non-normative; the format and governance remain experimental.