# Universal Document Implementation Profile 0.1.0

Status: normative profile for interoperability. The JSON Schema and this profile are authoritative. Reference code is informative.

## Conformance

An implementation is format-compatible when it emits JSON that conforms to `ud.schema.v0.1.0.json`, follows the canonicalization and revision rules below, and—when emitting a BrowserCarrier—embeds the exact canonical UD bytes. Compatibility does not imply a valid signature or a trusted signer identity.

## UDR

A UDR has `ud_version: "0.1.0"`, `state: "UDR"`, required `metadata`, `manifest`, and `blocks`, and no `seal`. Blocks are ordered. Every block has a stable `id`, supported `type`, and `base_content`. Required metadata and manifest fields are defined by the schema.

Revision history uses the existing `clarity_layers.revision_history` extension. Records are append-only. Versions start at 1 and increase by one. Each record after the first names the prior `revision_id` and `record_hash`. `record_hash` is lower-case SHA-256 of the UTF-8 canonical JSON for that revision record with `record_hash` omitted. Existing records MUST NOT be rewritten.

The editing-policy extension is `clarity_layers.editing_policy` version `1.0`. Supported modes are `OPEN_REVISION`, `NAMED_EDITORS`, `SUGGEST_ONLY`, `COMMENT_ONLY`, and `READ_ONLY`.

## Canonical bytes and hashes

Canonical JSON is compact JSON with object keys sorted lexicographically, strings and keys normalized to Unicode NFC, arrays kept in source order, `-0` represented as `0`, and no non-finite numbers. Undefined object properties are omitted. No insignificant whitespace or trailing newline is part of the canonical JSON byte sequence.

The document hash is lower-case SHA-256 of the UTF-8 canonical JSON for the whole document after removing the top-level `seal` property.

## UDS

Finalize an appropriate UDR by cloning it, changing `state` to `UDS`, updating `metadata.updated_at`, appending the sealed custody event, and adding the existing `seal` object. `seal.hash` is the canonical document hash described above. A UDS is not ordinarily edited; an amendment begins a new UDR derived from it.

The approved production signature architecture is Ed25519 over the canonical protected byte sequence. A signature proves only mathematical validity for a public key. Trust in that key and verification of the real-world signer identity are separate policy results. Production organizational issuance is not enabled merely by implementing this profile.

## BrowserCarrier

Use `.udr.html` or `.uds.html`. The baseline carrier is self-contained, offline-readable, script-free, and makes zero automatic network requests. It contains a download link whose `data:application/vnd.universal-document+json;base64,` payload decodes to the exact original canonical UD bytes. Presentation HTML is not part of canonical UD identity.

## Versioning

Implementations MUST reject unsupported major or exact versions they cannot interpret safely with `UNSUPPORTED_VERSION`. They MAY preserve unknown extension fields when the schema permits them, but MUST NOT silently reinterpret them. Required unknown fields or incompatible semantics fail closed. Version 0.1.0 files remain governed by this profile; deprecation requires a published replacement profile and migration guidance.

## Privacy and APIs

The format is independently implementable. UniversalDocument.org APIs are optional services, not a compatibility requirement. Local tools are preferred for sensitive material.