UAI 1 Production Specification

Version: 1.0.0

Metadata

Field	Value
Source site	protocol5.com
Source URL	https://protocol5.com/
Canonical AIWikis URL	https://aiwikis.org/protocol5/uai-system/files/spec-uai-1-md-b3ff05e2/
Source reference	spec/uai-1.md
File type	md
Content category	specification
Last fetched	2026-05-15T00:23:56.0837262Z
Last changed	2026-04-26T16:23:03.9831983Z
Content hash	sha256:b3ff05e28765770d772b7b236bfd81b4c9595d16d6fd7f7ca463cad4290460e1
Import status	unchanged
Raw source layer	data/sources/protocol5/spec-uai-1-md-b3ff05e28765.md
Normalized source layer	data/normalized/protocol5/spec-uai-1-md-b3ff05e28765.txt

Current File Content

Structure Preview

• UAI-1 Production Specification
• 1. Purpose
• 2. Scope
• 3. Normative language
• 4. Versioning
• 5. Canonical syntax
• 6. Top-level object
• 7. Source and metadata
• 8. Structural model
• 9. Required node vocabulary
• 10. Symbol model
• 11. Semantics and annotations
• 12. Relationships
• 13. Validation rules
• 14. Normalization rules
• 15. Composition rules
• 16. Extension mechanism
• 17. Error semantics
• 18. Valid and invalid examples
• 19. Mapping from HTML and WordPress
• 20. Mapping from UAI-1 back to renderable output
• 21. HTTP, content negotiation, and discovery
• 22. Compatibility audit and legacy position

Raw Version

This public page shows a bounded preview of a large source file. The complete source remains in the raw and normalized source layers named in metadata, with the SHA-256 hash above for verification.

• Source characters: 15183
• Preview characters: 11968

Local absolute paths are redacted in this public view. The source hash and source-side raw layer are based on the unredacted source file.

# UAI-1 Production Specification

**Terminology:** UAI means **Universal Artificial Intelligence**. **UAI-1** means the current public UAI exchange contract published by UAIX.org.

Version: `1.0.0`

Status: Protocol5 package mirror / implementation reference

UAIX.org is the public authority for UAI-1. This repository copy supports the Protocol5 .NET package, local tests, compatibility mirrors, and generated Protocol5.com distribution pages. Do not use this file to override the UAIX.org specification, schemas, registry, validator behavior, roadmap, governance, or changelog.

Local package artifacts:

- Registry mirror: `registry/uai-1.registry.json` (source-relative: registry/uai-1.registry.json)
- JSON Schema: `schema/uai-1.schema.json` (source-relative: schema/uai-1.schema.json)
- Type definitions: `schema/uai-1.types.ts` (source-relative: schema/uai-1.types.ts)
- Translator contract: `translator-contract.md` (source-relative: translator-contract.md)
- Integration contracts: `integration-contracts.md` (source-relative: integration-contracts.md)
- Website export contract: `website-export-contract.md` (source-relative: website-export-contract.md)
- Registry resolution contract: `registry-resolution-contract.md` (source-relative: registry-resolution-contract.md)
- Radix 63404 contract: `radix-63404-contract.md` (source-relative: radix-63404-contract.md)
- Package examples: `../examples/` (source-relative: ../examples)

## 1. Purpose

UAI-1 is a canonical intermediate representation for websites and symbolic or semantic content.

It exists to let producers, translators, validators, renderers, crawlers, content systems, and AI agents exchange the same page in a strict machine-readable form without relying on ad hoc HTML interpretation.

UAI-1 identifiers are protocol identifiers first. Their meaning comes from field role, schema, and authoritative registries.

Protocol5 publications may render numeric identifiers using Radix 63404, but that numeric notation is external to the UAI-1 document model and does not define UAI-1 semantics.

Immutable public definitions for UAI-1 are published by UAIX.org. Protocol5 may expose local `/uai-1/*` mirrors for package compatibility, staging, and tests, but those mirrors are not the public authority.

UAI-1 is designed to preserve:

- authored page structure
- literal readable text
- declared metadata
- symbolic definitions and symbolic occurrences
- translator inferences and confidence
- unsupported source fragments that cannot be normalized safely

## 2. Scope

This specification defines:

- the canonical JSON syntax for UAI-1 documents
- the top-level data model
- the required node vocabulary
- validation and normalization rules
- the extension mechanism
- HTTP discovery and content negotiation conventions
- compatibility requirements for existing `x-uai-1` and `X-UAI-1` usage

This specification does not define:

- a visual design system
- a browser runtime
- a universal ontology for all semantic values
- a requirement that every image be interpreted as a symbol
- a required numeric notation for identifiers or values

## 3. Normative language

The terms `MUST`, `MUST NOT`, `REQUIRED`, `SHOULD`, `SHOULD NOT`, and `MAY` are normative.

## 4. Versioning

UAI-1 uses three version declarations:

- `spec`: fixed identifier. For this specification it MUST be `"UAI-1"`.
- `version`: document format version. It MUST use semantic versioning.
- `schemaVersion`: JSON Schema version used to validate the document. It MUST use semantic versioning.

Extension payloads MUST declare their own version in `extensions.{namespace}.version`.

For `1.0.0` documents:

- `spec` MUST equal `"UAI-1"`
- `version` MUST equal `"1.0.0"`
- `schemaVersion` MUST equal `"1.0.0"`

## 5. Canonical syntax

Canonical UAI-1 syntax is UTF-8 encoded JSON with these rules:

1. The document root MUST be a JSON object.
2. Duplicate object keys MUST NOT appear.
3. Comments MUST NOT appear.
4. Top-level keys MUST appear in this order when serialized:
   `spec`, `version`, `schemaVersion`, `documentId`, `source`, `metadata`, `structure`, `semantics`, `symbols`, `assets`, `relationships`, `annotations`, `provenance`, `extensions`.
5. Numbers representing confidence MUST be JSON numbers, not strings.
6. Empty top-level collections MUST still be emitted as arrays or objects.
7. Optional properties MAY be omitted when absent.

## 6. Top-level object

Canonical shape:

```json
{
  "spec": "UAI-1",
  "version": "1.0.0",
  "schemaVersion": "1.0.0",
  "documentId": "string",
  "source": {},
  "metadata": {},
  "structure": [],
  "semantics": [],
  "symbols": [],
  "assets": [],
  "relationships": [],
  "annotations": [],
  "provenance": {},
  "extensions": {}
}
```

Field requirements:

| Field | Required | Meaning |
| --- | --- | --- |
| `spec` | yes | fixed format identifier |
| `version` | yes | document format version |
| `schemaVersion` | yes | schema version used for validation |
| `documentId` | yes | stable identifier for the document and root node |
| `source` | yes | source retrieval metadata |
| `metadata` | yes | page-level metadata |
| `structure` | yes | array containing exactly one root `document` node |
| `semantics` | yes | semantic interpretations that are not implied by structure alone |
| `symbols` | yes | canonical symbol definitions |
| `assets` | yes | referenced images, files, or media |
| `relationships` | yes | explicit cross-object relationships |
| `annotations` | yes | warnings, preservation notes, translator notes, and errors |
| `provenance` | yes | generator and translator provenance |
| `extensions` | yes | namespaced extension payloads |

## 7. Source and metadata

`source` preserves crawl or export facts.

`source.uri` and `source.retrievedAt` are REQUIRED.

`metadata` preserves page-level publishing facts.

`metadata.title`, `metadata.language`, and `metadata.pageType` are REQUIRED.

`metadata.pageType` MUST be one of:

- `generic`
- `homepage`
- `article`
- `landing-page`
- `navigation`
- `symbolic-manuscript`
- `wordpress-page`
- `gallery`
- `glossary`
- `reference`

## 8. Structural model

`structure` MUST contain exactly one root node of type `document`.

The root node id MUST equal `documentId`.

Every node MUST include:

- `type`
- `id`

Node ids MUST be unique across the full document namespace, including nodes, assets, annotations, semantic records, and symbols.

## 9. Required node vocabulary

Required node types and their minimum fields:

| Type | Required fields |
| --- | --- |
| `document` | `children` |
| `section` | `children` |
| `heading` | `text`, `level` |
| `paragraph` | `text` |
| `quote` | `text` |
| `list` | `ordered`, `children` |
| `listItem` | none beyond base fields; text or children SHOULD exist |
| `table` | `columns`, `rows` |
| `image` | `assetRef` |
| `figure` | `children` |
| `caption` | `text` |
| `button` | `text`, `action` |
| `link` | `text`, `href` |
| `navigation` | `children` |
| `form` | `children` |
| `input` | `inputType`, `name` |
| `glossaryEntry` | `term`, `definition` |
| `symbol` | `symbolRef` |
| `glyphCluster` | `children` |
| `diagram` | `assetRef`, `description` |
| `manuscriptPanel` | `children` |
| `callout` | `children` |
| `metadataBlock` | `entries` |
| `footer` | `children` |
| `header` | `children` |
| `unknown` | `rawContent`, `reason` |

## 10. Symbol model

UAI-1 separates symbol definition from symbol occurrence.

Canonical symbol definitions live in the top-level `symbols` array.

Symbol occurrences inside page structure use `type: "symbol"` and refer to a definition through `symbolRef`.

Each symbol definition MUST support:

- `id`
- `visualForm`
- `meaning`
- `inference`

Recommended fields for production use:

- `label`
- `geometry`
- `strokeLogic`
- `sourceSystem`
- `sourceEvidence`
- `variants`
- `relationships`
- `notes`

Important rule: if the source identifies a glyph by name but does not define meaning, `meaning` MUST be an empty array. Translators MUST NOT invent historical, doctrinal, or ritual meaning.

## 11. Semantics and annotations

`semantics` is for normalized semantic interpretations that are not guaranteed by structure alone.

Examples:

- page intent
- primary CTA role
- topical classification
- inferred audience

`annotations` are non-structural notes such as:

- validation warnings
- dropped decorative wrappers
- unknown widget preservation
- translator notices

## 12. Relationships

Use `relationships` when an explicit relation is needed between objects that do not stand in a strict parent-child relationship.

Examples:

- `references`
- `captionOf`
- `derivedFrom`
- `appearsWith`
- `instanceOf`

## 13. Validation rules

A UAI-1 document is invalid if any of these are true:

1. `spec` is not `"UAI-1"`.
2. `version` or `schemaVersion` is missing or not semantic version text.
3. `structure` does not contain exactly one root `document` node.
4. root node id does not equal `documentId`.
5. a required node field is missing.
6. an id is duplicated.
7. a symbol occurrence references an unknown `symbolRef`.
8. an image or diagram references an unknown `assetRef`.
9. an inferred value omits rationale or confidence.
10. confidence is outside `0.0` to `1.0`.
11. an extension key is not namespaced.
12. unsupported content is silently discarded instead of preserved as `unknown` when preservation is required.

## 14. Normalization rules

Normalizers MUST:

1. trim surrounding whitespace from string fields unless the field is source-authored raw content
2. preserve `text.literal` exactly as extracted by the translator contract
3. compute `text.normalized` if absent
4. sort top-level `semantics`, `symbols`, `assets`, `relationships`, and `annotations` by stable id when canonical output is produced
5. preserve source order inside `structure`
6. preserve explicit ids exactly

Normalizers MUST NOT:

- invent missing required ids
- change `text.literal`
- rewrite empty symbol meaning arrays into guessed meaning

## 15. Composition rules

UAI-1 uses composition, not inheritance, in document structure.

Containers contain child nodes.

Meaningful cross-links use `relationships`.

Machine interpretation MUST use:

1. explicit structure
2. explicit symbol definitions
3. explicit semantic records
4. explicit inference envelopes

No semantic interpretation is implied solely by CSS class names in the final UAI document.

## 16. Extension mechanism

Extensions live under `extensions`.

Each extension key MUST use a namespaced identifier such as `vendor.feature`.

Each extension value MUST contain:

- `version`
- `required`
- `payload`

Consumers that do not understand a non-required extension MAY ignore it.

Consumers that do not understand a required extension MUST fail validation or surface a hard compatibility warning.

## 17. Error semantics

Validators SHOULD report:

- machine code
- JSON path
- severity
- human-readable message

Recommended severities:

- `info`
- `warning`
- `error`

## 18. Valid and invalid examples

Valid examples:

- `../examples/homepage.uai.json` (source-relative: ../examples/homepage.uai.json)
- `../examples/article-page.uai.json` (source-relative: ../examples/article-page.uai.json)
- `../examples/symbolic-manuscript-page.uai.json` (source-relative: ../examples/symbolic-manuscript-page.uai.json)

Invalid fragment:

```json
{
  "spec": "UAI-1",
  "version": "1.0.0",
  "schemaVersion": "1.0.0",
  "documentId": "bad",
  "structure": [
    {
      "type": "heading",
      "id": "bad"
    }
  ]
}
```

Why invalid:

- missing required top-level fields
- root node is not `document`

Why This File Exists

This is a source file from protocol5.com. It is shown here because AIWikis.org is demonstrating the real source files that make the UAIX / LLM Wiki memory system work, not only summarizing those systems after the fact.

Role

This file is a focused source unit. Its path, headings, and metadata give an agent a retrieval handle that is smaller than loading the entire site or repository.

Structure

The file is structured around these visible headings: UAI-1 Production Specification; 1. Purpose; 2. Scope; 3. Normative language; 4. Versioning; 5. Canonical syntax; 6. Top-level object; 7. Source and metadata. Those headings are retrieval anchors: a crawler or LLM can decide whether the file is relevant before reading every line.

Prompt-Size And Retrieval Benefit

Keeping this material in a separate file reduces prompt pressure because an agent can load this exact unit only when its role, source site, category, or hash is relevant. The surrounding index pages point to it, while this page preserves the full content for audit and exact recall.

How To Use It

• Humans should read the metadata first, then inspect the raw content when they need exact wording or provenance.
• LLMs and agents should use the source site, category, hash, headings, and related files to decide whether this file belongs in the active prompt.
• Crawlers should treat the AIWikis page as transparent evidence and follow the source URL/source reference for authority boundaries.
• Future maintainers should regenerate this page whenever the source hash changes, then review the explanation if the role or structure changed.

Update Requirements

When this source file changes, update the raw source layer, normalized source layer, hash history, this rendered page, generated explanation, source-file inventory, changed-files report, and any source-section index that links to it.

Related Pages

• Source overview
• UAI system index
• Source provenance
• Global File Index
• Reports

Provenance And History

• Current observation: 2026-05-15T00:23:56.0837262Z
• Source origin: current-source-workspace
• Retrieval method: local-source-workspace
• Duplicate group: sfg-564 (primary)
• Historical hash records are stored in data/hashes/source-file-history.jsonl.

Machine-Readable Metadata

{
    "title":  "UAI 1 Production Specification",
    "source_site":  "protocol5.com",
    "source_url":  "https://protocol5.com/",
    "canonical_url":  "https://aiwikis.org/protocol5/uai-system/files/spec-uai-1-md-b3ff05e2/",
    "source_reference":  "spec/uai-1.md",
    "file_type":  "md",
    "content_category":  "specification",
    "content_hash":  "sha256:b3ff05e28765770d772b7b236bfd81b4c9595d16d6fd7f7ca463cad4290460e1",
    "last_fetched":  "2026-05-15T00:23:56.0837262Z",
    "last_changed":  "2026-04-26T16:23:03.9831983Z",
    "import_status":  "unchanged",
    "duplicate_group_id":  "sfg-564",
    "duplicate_role":  "primary",
    "related_files":  [

                      ],
    "generated_explanation":  true,
    "explanation_last_generated":  "2026-05-15T00:23:56.0837262Z"
}