diff --git a/CHANGELOG.md b/CHANGELOG.md index ed550f6..63ebb47 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -All notable changes to the Codex file format specification. +All notable changes to the CDX file format specification. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). @@ -19,14 +19,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - Highlight annotation documentation in collaboration extension (Section 4.7) #### Extensions -- **Academic** (`codex.academic`) - Theorems, proofs, exercises, algorithms, equation groups -- **Collaboration** (`codex.collaboration` v0.2) - CRDT integration, comments, change tracking, presence -- **Forms** (`codex.forms`) - Interactive form fields with validation -- **Legal** (`codex.legal`) - Citations, Table of Authorities, court captions, signature blocks -- **Phantoms** (`codex.phantoms`) - Invisible structural elements for complex layouts -- **Presentation** (`codex.presentation`) - Advanced typography, master pages, print features -- **Security** (`codex.security`) - Digital signatures, encryption, redaction, scoped signatures -- **Semantic** (`codex.semantic`) - Bibliography, footnotes, glossary, entity markup, JSON-LD +- **Academic** (`cdx.academic`) - Theorems, proofs, exercises, algorithms, equation groups +- **Collaboration** (`cdx.collaboration` v0.2) - CRDT integration, comments, change tracking, presence +- **Forms** (`cdx.forms`) - Interactive form fields with validation +- **Legal** (`cdx.legal`) - Citations, Table of Authorities, court captions, signature blocks +- **Phantoms** (`cdx.phantoms`) - Invisible structural elements for complex layouts +- **Presentation** (`cdx.presentation`) - Advanced typography, master pages, print features +- **Security** (`cdx.security`) - Digital signatures, encryption, redaction, scoped signatures +- **Semantic** (`cdx.semantic`) - Bibliography, footnotes, glossary, entity markup, JSON-LD #### Profiles - Simple Documents profile for recreational reading diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5935ccf..5d126bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# Contributing to Codex Document Format +# Contributing to CDX -Thank you for your interest in contributing to the Codex Document Format specification. +Thank you for your interest in contributing to the CDX specification. ## How to Contribute diff --git a/README.md b/README.md index af25c97..5e4c44b 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -# Codex Document Format +# CDX [![Validate Schemas](https://github.com/Entrolution/codex-file-format-spec/actions/workflows/validate-schemas.yml/badge.svg)](https://github.com/Entrolution/codex-file-format-spec/actions/workflows/validate-schemas.yml) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) -**An open specification for documents that unify viewing and editing, with modern security and machine readability.** +**CDX — Content-addressed Document eXchange.** An open specification for documents that unify viewing and editing, with modern security and machine readability. > Status: Draft Specification (v0.1) @@ -85,7 +85,7 @@ This divide creates workflow friction, format conversion overhead, and lost fide ## Key Feature: Verifiable Provenance -Codex documents form a **cryptographic hash chain** — each document's identity IS its content hash, and each document can reference its parent by hash: +CDX documents form a **cryptographic hash chain** — each document's identity IS its content hash, and each document can reference its parent by hash: ``` doc-v1 (sha256:aaa) ←── doc-v2 (sha256:bbb) ←── doc-v3 (sha256:ccc) @@ -103,7 +103,7 @@ This enables: ## Key Feature: State-Aware Presentation -Codex uses **progressive enhancement** for presentation — the level of layout precision evolves with document maturity: +CDX uses **progressive enhancement** for presentation — the level of layout precision evolves with document maturity: | Document State | Presentation Requirement | What's Frozen | |----------------|-------------------------|---------------| @@ -164,7 +164,7 @@ The specification is modular: ### Document Structure -A Codex document is a ZIP archive with this structure: +A CDX document is a ZIP archive with this structure: ``` document.cdx @@ -195,7 +195,7 @@ document.cdx ```json { - "codex": "0.1", + "cdx": "0.1", "id": "sha256:a1b2c3...", "state": "draft", "content": { @@ -209,7 +209,7 @@ document.cdx "type": "paragraph", "children": [ { "type": "text", "value": "This is a " }, - { "type": "text", "value": "Codex", "marks": ["bold"] }, + { "type": "text", "value": "CDX", "marks": ["bold"] }, { "type": "text", "value": " document." } ] } @@ -221,8 +221,8 @@ document.cdx ## File Extension and MIME Type - **Extension**: `.cdx` -- **MIME Type**: `application/vnd.codex+json` (canonical JSON form) -- **Alternative**: `application/vnd.codex` (binary/packed form) +- **MIME Type**: `application/vnd.cdx+json` (canonical JSON form) +- **Alternative**: `application/vnd.cdx` (binary/packed form) ## Roadmap diff --git a/SECURITY.md b/SECURITY.md index e71af32..0012288 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -20,7 +20,7 @@ If you find a security issue in the reference implementation ([cdx-core](https:/ This security policy covers: -- The Codex Document Format specification +- The CDX specification - JSON schemas in this repository - Example documents in this repository diff --git a/docs/design-decisions.md b/docs/design-decisions.md index ed07e31..10c0aff 100644 --- a/docs/design-decisions.md +++ b/docs/design-decisions.md @@ -1,6 +1,6 @@ # Design Decisions -This document records key design decisions made during the Codex format specification development. +This document records key design decisions made during the CDX format specification development. ## DD-001: ZIP Container Format @@ -559,7 +559,7 @@ This section captures key strategic insights from early design discussions that **Build Order**: 1. **cdx-core** (Rust library) — Foundation everything else builds on 2. **cdx-cli** — Dogfoods the core library, essential for tooling development -3. **Pandoc writer** — Markdown → Codex (the academia unlock) +3. **Pandoc writer** — Markdown → CDX (the academia unlock) 4. **Web viewer** — cdx-core compiled to WASM (zero-install demonstration) **Why Pandoc**: Academics don't adopt new editors, they adopt new export targets. A Pandoc writer fits existing workflows with zero friction for authors. diff --git a/examples/academic-document/manifest.json b/examples/academic-document/manifest.json index e83f999..20aa2ee 100644 --- a/examples/academic-document/manifest.json +++ b/examples/academic-document/manifest.json @@ -1,12 +1,12 @@ { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-28T14:00:00Z", "modified": "2025-01-28T14:00:00Z", "extensions": [ { - "id": "codex.academic", + "id": "cdx.academic", "version": "0.1", "required": false } diff --git a/examples/academic-document/metadata/dublin-core.json b/examples/academic-document/metadata/dublin-core.json index 124a6c7..87f4692 100644 --- a/examples/academic-document/metadata/dublin-core.json +++ b/examples/academic-document/metadata/dublin-core.json @@ -7,7 +7,7 @@ "description": "A demonstration of academic extension features including theorems, proofs, exercises, and algorithms.", "date": "2025-01-28", "type": "Text", - "format": "application/vnd.codex+zip", + "format": "application/vnd.cdx+zip", "language": "en", "rights": "CC BY 4.0" } diff --git a/examples/collaboration-document/manifest.json b/examples/collaboration-document/manifest.json index 43f82f5..0f7526b 100644 --- a/examples/collaboration-document/manifest.json +++ b/examples/collaboration-document/manifest.json @@ -1,12 +1,12 @@ { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-28T14:00:00Z", "modified": "2025-01-28T14:00:00Z", "extensions": [ { - "id": "codex.collaboration", + "id": "cdx.collaboration", "version": "0.2", "required": false } diff --git a/examples/collaboration-document/metadata/dublin-core.json b/examples/collaboration-document/metadata/dublin-core.json index 15fb143..bd31d4f 100644 --- a/examples/collaboration-document/metadata/dublin-core.json +++ b/examples/collaboration-document/metadata/dublin-core.json @@ -7,7 +7,7 @@ "description": "A demonstration of collaboration extension features including comments, suggestions, reactions, and tracked changes with multiple authors.", "date": "2025-01-28", "type": "Text", - "format": "application/vnd.codex+zip", + "format": "application/vnd.cdx+zip", "language": "en", "rights": "Confidential" } diff --git a/examples/comprehensive-document/content/document.json b/examples/comprehensive-document/content/document.json index 2875e47..2cc4e62 100644 --- a/examples/comprehensive-document/content/document.json +++ b/examples/comprehensive-document/content/document.json @@ -15,7 +15,7 @@ "children": [ { "type": "text", "value": "This document demonstrates " }, { "type": "text", "value": "all block types", "marks": ["bold"] }, - { "type": "text", "value": " supported by the Codex format. It serves as both documentation and a validation test case." } + { "type": "text", "value": " supported by the CDX format. It serves as both documentation and a validation test case." } ] }, { @@ -273,7 +273,7 @@ { "type": "definitionTerm", "children": [ - { "type": "text", "value": "Codex" } + { "type": "text", "value": "CDX" } ] }, { @@ -332,7 +332,7 @@ "children": [ { "type": "text", - "value": "interface CodexDocument {\n version: string;\n blocks: Block[];\n}\n\nfunction validate(doc: CodexDocument): boolean {\n return doc.blocks.every(block => block.type !== undefined);\n}" + "value": "interface CdxDocument {\n version: string;\n blocks: Block[];\n}\n\nfunction validate(doc: CdxDocument): boolean {\n return doc.blocks.every(block => block.type !== undefined);\n}" } ] }, @@ -607,7 +607,7 @@ { "type": "figcaption", "children": [ - { "type": "text", "value": "Figure: Codex document architecture showing the relationship between content, presentation, and metadata layers." } + { "type": "text", "value": "Figure: CDX document architecture showing the relationship between content, presentation, and metadata layers." } ] } ] @@ -624,8 +624,8 @@ "type": "barcode", "id": "qr-demo", "format": "qr", - "data": "https://codex.document/spec", - "alt": "QR code linking to Codex specification", + "data": "https://cdx.dev/spec", + "alt": "QR code linking to CDX specification", "errorCorrection": "M", "size": 150 }, @@ -701,7 +701,7 @@ "signer": { "name": "Jane Smith", "title": "Technical Lead", - "organization": "Codex Foundation", + "organization": "CDX Foundation", "email": "jane.smith@example.com" }, "timestamp": "2025-01-28T14:00:00Z", @@ -905,7 +905,7 @@ "type": "paragraph", "id": "conclusion", "children": [ - { "type": "text", "value": "This document demonstrates all block types defined in the Codex content schema. Each block type serves a specific semantic purpose, enabling reliable machine processing and consistent rendering across implementations." } + { "type": "text", "value": "This document demonstrates all block types defined in the CDX content schema. Each block type serves a specific semantic purpose, enabling reliable machine processing and consistent rendering across implementations." } ] } ] diff --git a/examples/comprehensive-document/manifest.json b/examples/comprehensive-document/manifest.json index 073ce71..ea997ae 100644 --- a/examples/comprehensive-document/manifest.json +++ b/examples/comprehensive-document/manifest.json @@ -1,5 +1,5 @@ { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-28T14:00:00Z", diff --git a/examples/comprehensive-document/metadata/dublin-core.json b/examples/comprehensive-document/metadata/dublin-core.json index 9e0e549..afb9606 100644 --- a/examples/comprehensive-document/metadata/dublin-core.json +++ b/examples/comprehensive-document/metadata/dublin-core.json @@ -2,16 +2,16 @@ "version": "1.1", "terms": { "title": "Comprehensive Block Type Reference", - "creator": "Codex Specification Team", + "creator": "CDX Specification Team", "subject": [ "Documentation", "Specification", "Block Types", "Reference" ], - "description": "A comprehensive example document demonstrating all block types supported by the Codex format, including text content, lists, tables, code blocks, mathematics, media, measurements, signatures, and internationalization features.", + "description": "A comprehensive example document demonstrating all block types supported by the CDX format, including text content, lists, tables, code blocks, mathematics, media, measurements, signatures, and internationalization features.", "type": "Text", - "format": "application/vnd.codex+json", + "format": "application/vnd.cdx+json", "language": "en", "date": "2025-01-28", "rights": "Public Domain" diff --git a/examples/forms-document/manifest.json b/examples/forms-document/manifest.json index fc8db7c..12a60f4 100644 --- a/examples/forms-document/manifest.json +++ b/examples/forms-document/manifest.json @@ -1,12 +1,12 @@ { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-28T14:00:00Z", "modified": "2025-01-28T14:00:00Z", "extensions": [ { - "id": "codex.forms", + "id": "cdx.forms", "version": "0.1", "required": false } diff --git a/examples/forms-document/metadata/dublin-core.json b/examples/forms-document/metadata/dublin-core.json index 0f207fa..a5f2359 100644 --- a/examples/forms-document/metadata/dublin-core.json +++ b/examples/forms-document/metadata/dublin-core.json @@ -7,7 +7,7 @@ "description": "A demonstration of forms extension features including text inputs, dropdowns, checkboxes, validation, conditional validation, and signatures.", "date": "2025-01-28", "type": "InteractiveResource", - "format": "application/vnd.codex+zip", + "format": "application/vnd.cdx+zip", "language": "en", "rights": "All rights reserved" } diff --git a/examples/legal-document/manifest.json b/examples/legal-document/manifest.json index f3a1418..053668c 100644 --- a/examples/legal-document/manifest.json +++ b/examples/legal-document/manifest.json @@ -1,12 +1,12 @@ { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-30T10:00:00Z", "modified": "2025-01-30T10:00:00Z", "extensions": [ { - "id": "codex.legal", + "id": "cdx.legal", "version": "0.1", "required": false } diff --git a/examples/legal-document/metadata/dublin-core.json b/examples/legal-document/metadata/dublin-core.json index aa1df9c..883fd1d 100644 --- a/examples/legal-document/metadata/dublin-core.json +++ b/examples/legal-document/metadata/dublin-core.json @@ -7,7 +7,7 @@ "description": "A demonstration of the legal extension features including caption, Table of Authorities, legal citations, and signature block.", "date": "2025-01-30", "type": "Text", - "format": "application/vnd.codex+zip", + "format": "application/vnd.cdx+zip", "language": "en", "rights": "Confidential - Attorney Work Product" } diff --git a/examples/phantoms-document/manifest.json b/examples/phantoms-document/manifest.json index 1d6bf6f..9ccb4e7 100644 --- a/examples/phantoms-document/manifest.json +++ b/examples/phantoms-document/manifest.json @@ -1,12 +1,12 @@ { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-28T14:00:00Z", "modified": "2025-01-28T14:00:00Z", "extensions": [ { - "id": "codex.phantoms", + "id": "cdx.phantoms", "version": "0.1", "required": false } diff --git a/examples/phantoms-document/metadata/dublin-core.json b/examples/phantoms-document/metadata/dublin-core.json index 22f8771..b5f95b4 100644 --- a/examples/phantoms-document/metadata/dublin-core.json +++ b/examples/phantoms-document/metadata/dublin-core.json @@ -7,7 +7,7 @@ "description": "A demonstration of phantoms extension features including annotation clusters with different scopes (shared, role-based, private), phantom connections, and nested content.", "date": "2025-01-28", "type": "Text", - "format": "application/vnd.codex+zip", + "format": "application/vnd.cdx+zip", "language": "en", "rights": "Internal Use Only" } diff --git a/examples/presentation-document/content/document.json b/examples/presentation-document/content/document.json index 01b2ea5..10cf071 100644 --- a/examples/presentation-document/content/document.json +++ b/examples/presentation-document/content/document.json @@ -11,7 +11,7 @@ "type": "paragraph", "id": "p-intro-1", "children": [ - { "type": "text", "value": "This document demonstrates the advanced presentation features available in the Codex format. The presentation layer provides fine-grained control over typography, layout, and print output." } + { "type": "text", "value": "This document demonstrates the advanced presentation features available in the CDX format. The presentation layer provides fine-grained control over typography, layout, and print output." } ] }, { diff --git a/examples/presentation-document/manifest.json b/examples/presentation-document/manifest.json index 997a870..5db7465 100644 --- a/examples/presentation-document/manifest.json +++ b/examples/presentation-document/manifest.json @@ -1,5 +1,5 @@ { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-29T10:00:00Z", @@ -21,7 +21,7 @@ }, "extensions": [ { - "id": "codex.presentation", + "id": "cdx.presentation", "version": "0.1", "required": false } diff --git a/examples/presentation-document/metadata/dublin-core.json b/examples/presentation-document/metadata/dublin-core.json index f9540b0..b4f98da 100644 --- a/examples/presentation-document/metadata/dublin-core.json +++ b/examples/presentation-document/metadata/dublin-core.json @@ -2,12 +2,12 @@ "version": "1.1", "terms": { "title": "Presentation Extension Example", - "creator": "Codex Specification Team", + "creator": "CDX Specification Team", "subject": ["Document Format", "Presentation", "Typography"], "description": "An example document demonstrating the Presentation Extension features including master pages, typography, multi-column layout, and running headers/footers.", "date": "2025-01-29", "type": "Text", - "format": "application/vnd.codex+zip", + "format": "application/vnd.cdx+zip", "language": "en" } } diff --git a/examples/semantic-document/manifest.json b/examples/semantic-document/manifest.json index d40048e..4cf9c6e 100644 --- a/examples/semantic-document/manifest.json +++ b/examples/semantic-document/manifest.json @@ -1,12 +1,12 @@ { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-28T14:00:00Z", "modified": "2025-01-28T14:00:00Z", "extensions": [ { - "id": "codex.semantic", + "id": "cdx.semantic", "version": "0.1", "required": false } diff --git a/examples/semantic-document/metadata/dublin-core.json b/examples/semantic-document/metadata/dublin-core.json index 090ea1b..088d2dd 100644 --- a/examples/semantic-document/metadata/dublin-core.json +++ b/examples/semantic-document/metadata/dublin-core.json @@ -7,7 +7,7 @@ "description": "A demonstration of semantic extension features including citations, footnotes, glossary terms, and entity annotations.", "date": "2025-01-28", "type": "Text", - "format": "application/vnd.codex+zip", + "format": "application/vnd.cdx+zip", "language": "en", "rights": "CC BY 4.0" } diff --git a/examples/signed-document/manifest.json b/examples/signed-document/manifest.json index ddd414a..d41ef67 100644 --- a/examples/signed-document/manifest.json +++ b/examples/signed-document/manifest.json @@ -1,5 +1,5 @@ { - "codex": "0.1", + "cdx": "0.1", "id": "sha256:3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b", "state": "frozen", "hashAlgorithm": "sha256", @@ -24,7 +24,7 @@ }, "extensions": [ { - "id": "codex.security", + "id": "cdx.security", "version": "0.1", "required": true } diff --git a/examples/signed-document/metadata/dublin-core.json b/examples/signed-document/metadata/dublin-core.json index bed2b12..78e9e14 100644 --- a/examples/signed-document/metadata/dublin-core.json +++ b/examples/signed-document/metadata/dublin-core.json @@ -7,7 +7,7 @@ "description": "Service agreement between Acme Corporation and XYZ Enterprises for consulting services.", "date": "2025-01-15", "type": "Text", - "format": "application/vnd.codex+json", + "format": "application/vnd.cdx+json", "language": "en", "rights": "Confidential. All rights reserved." } diff --git a/examples/simple-document/content/document.json b/examples/simple-document/content/document.json index c120738..cd752c8 100644 --- a/examples/simple-document/content/document.json +++ b/examples/simple-document/content/document.json @@ -6,7 +6,7 @@ "id": "title", "level": 1, "children": [ - { "type": "text", "value": "Welcome to Codex" } + { "type": "text", "value": "Welcome to CDX" } ] }, { @@ -14,7 +14,7 @@ "id": "intro", "children": [ { "type": "text", "value": "This is a simple " }, - { "type": "text", "value": "Codex", "marks": ["bold"] }, + { "type": "text", "value": "CDX", "marks": ["bold"] }, { "type": "text", "value": " document demonstrating the basic structure of the format." } ] }, @@ -30,7 +30,7 @@ "type": "paragraph", "id": "features-intro", "children": [ - { "type": "text", "value": "The Codex format offers several advantages:" } + { "type": "text", "value": "The CDX format offers several advantages:" } ] }, { @@ -88,7 +88,7 @@ "type": "paragraph", "id": "code-intro", "children": [ - { "type": "text", "value": "Here's how you might validate a Codex document:" } + { "type": "text", "value": "Here's how you might validate a CDX document:" } ] }, { @@ -98,7 +98,7 @@ "children": [ { "type": "text", - "value": "import { validate } from '@codex/validator';\n\nconst result = await validate('./document.cdx');\nif (result.valid) {\n console.log('Document is valid!');\n} else {\n console.error('Validation errors:', result.errors);\n}" + "value": "import { validate } from '@cdx/validator';\n\nconst result = await validate('./document.cdx');\nif (result.valid) {\n console.log('Document is valid!');\n} else {\n console.error('Validation errors:', result.errors);\n}" } ] }, @@ -113,12 +113,12 @@ { "type": "text", "value": "Learn more at the " }, { "type": "text", - "value": "Codex Documentation", + "value": "CDX Documentation", "marks": [ { "type": "link", - "href": "https://codex.document", - "title": "Codex Documentation" + "href": "https://cdx.dev", + "title": "CDX Documentation" } ] }, diff --git a/examples/simple-document/manifest.json b/examples/simple-document/manifest.json index b09cd53..5dc3a24 100644 --- a/examples/simple-document/manifest.json +++ b/examples/simple-document/manifest.json @@ -1,5 +1,5 @@ { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-15T10:00:00Z", diff --git a/examples/simple-document/metadata/dublin-core.json b/examples/simple-document/metadata/dublin-core.json index d31caf1..8946553 100644 --- a/examples/simple-document/metadata/dublin-core.json +++ b/examples/simple-document/metadata/dublin-core.json @@ -1,12 +1,12 @@ { "version": "1.1", "terms": { - "title": "Welcome to Codex", + "title": "Welcome to CDX", "creator": "Documentation Team", "subject": ["Documentation", "Getting Started", "Tutorial"], - "description": "A simple introductory document demonstrating the basic structure of the Codex format.", + "description": "A simple introductory document demonstrating the basic structure of the CDX format.", "type": "Text", - "format": "application/vnd.codex+json", + "format": "application/vnd.cdx+json", "language": "en" } } diff --git a/package.json b/package.json index 01c621e..f43d88c 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "codex-file-format-spec", "version": "0.1.0", - "description": "Specification for the Codex document format", + "description": "Specification for CDX (Content-addressed Document eXchange)", "private": true, "scripts": { "test": "npm run validate:schemas && npm run validate:examples", diff --git a/schemas/README.md b/schemas/README.md index baab9fb..913bdcd 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -1,6 +1,6 @@ -# Codex JSON Schemas +# CDX JSON Schemas -This directory contains JSON Schema definitions for validating Codex document components. +This directory contains JSON Schema definitions for validating CDX document components. ## Schema Files @@ -89,7 +89,7 @@ for schema_file in ['anchor.schema.json', 'phantoms.schema.json']: schema = json.load(f) schema_store[schema['$id']] = schema -resolver = RefResolver.from_schema(schema_store['https://codex.document/schemas/phantoms.schema.json'], store=schema_store) +resolver = RefResolver.from_schema(schema_store['https://cdx.dev/schemas/phantoms.schema.json'], store=schema_store) validate(instance=document, schema=phantoms_schema, resolver=resolver) ``` diff --git a/schemas/academic.schema.json b/schemas/academic.schema.json index da20fe7..6573367 100644 --- a/schemas/academic.schema.json +++ b/schemas/academic.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/academic.schema.json", - "title": "Codex Academic Extension", - "description": "Schema for academic extension blocks and marks in a Codex document", + "$id": "https://cdx.dev/schemas/academic.schema.json", + "title": "CDX Academic Extension", + "description": "Schema for academic extension blocks and marks in a CDX document", "$defs": { "abstractBlock": { "type": "object", diff --git a/schemas/anchor.schema.json b/schemas/anchor.schema.json index 68f3c01..474669c 100644 --- a/schemas/anchor.schema.json +++ b/schemas/anchor.schema.json @@ -1,7 +1,7 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/anchor.schema.json", - "title": "Codex Content Anchor and Person Definitions", + "$id": "https://cdx.dev/schemas/anchor.schema.json", + "title": "CDX Content Anchor and Person Definitions", "description": "Reusable schema definitions for ContentAnchor, ContentAnchorUri, and Person, used by collaboration, phantoms, security, and other extensions.", "$defs": { "person": { diff --git a/schemas/annotations.schema.json b/schemas/annotations.schema.json index 727d39c..344289d 100644 --- a/schemas/annotations.schema.json +++ b/schemas/annotations.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/annotations.schema.json", - "title": "Codex Core Annotations", - "description": "Schema for the security/annotations.json file in a Codex document. Provides minimal annotation support for implementations that don't use the collaboration extension.", + "$id": "https://cdx.dev/schemas/annotations.schema.json", + "title": "CDX Core Annotations", + "description": "Schema for the security/annotations.json file in a CDX document. Provides minimal annotation support for implementations that don't use the collaboration extension.", "type": "object", "required": ["annotations"], "properties": { @@ -35,7 +35,7 @@ "enum": ["comment", "highlight", "note", "reaction"] }, "anchor": { - "$ref": "https://codex.document/schemas/anchor.schema.json#/$defs/contentAnchor", + "$ref": "https://cdx.dev/schemas/anchor.schema.json#/$defs/contentAnchor", "description": "Anchor to document content" }, "author": { diff --git a/schemas/asset-index.schema.json b/schemas/asset-index.schema.json index 79430f3..ca1fbe1 100644 --- a/schemas/asset-index.schema.json +++ b/schemas/asset-index.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/asset-index.schema.json", + "$id": "https://cdx.dev/schemas/asset-index.schema.json", "title": "Asset Index", - "description": "Schema for asset index files in a Codex document", + "description": "Schema for asset index files in a CDX document", "type": "object", "required": ["version", "assets"], "properties": { diff --git a/schemas/collaboration.schema.json b/schemas/collaboration.schema.json index 2e5afd2..48381a8 100644 --- a/schemas/collaboration.schema.json +++ b/schemas/collaboration.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/collaboration.schema.json", - "title": "Codex Collaboration Extension", - "description": "Schema for collaboration extension files in a Codex document", + "$id": "https://cdx.dev/schemas/collaboration.schema.json", + "title": "CDX Collaboration Extension", + "description": "Schema for collaboration extension files in a CDX document", "$defs": { "crdtFormat": { "type": "string", @@ -12,7 +12,7 @@ "author": { "description": "Comment/change author information extending base person", "allOf": [ - { "$ref": "https://codex.document/schemas/anchor.schema.json#/$defs/person" }, + { "$ref": "https://cdx.dev/schemas/anchor.schema.json#/$defs/person" }, { "type": "object", "properties": { @@ -81,7 +81,7 @@ "$ref": "#/$defs/commentType" }, "anchor": { - "$ref": "https://codex.document/schemas/anchor.schema.json#/$defs/contentAnchor", + "$ref": "https://cdx.dev/schemas/anchor.schema.json#/$defs/contentAnchor", "description": "Anchor to content (see Anchors and References spec)" }, "author": { @@ -228,7 +228,7 @@ "$ref": "#/$defs/changeType" }, "anchor": { - "$ref": "https://codex.document/schemas/anchor.schema.json#/$defs/contentAnchor", + "$ref": "https://cdx.dev/schemas/anchor.schema.json#/$defs/contentAnchor", "description": "Anchor to affected content" }, "position": { diff --git a/schemas/content.schema.json b/schemas/content.schema.json index 6425217..78c6698 100644 --- a/schemas/content.schema.json +++ b/schemas/content.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/content.schema.json", - "title": "Codex Document Content", - "description": "Schema for the content/document.json file in a Codex document", + "$id": "https://cdx.dev/schemas/content.schema.json", + "title": "CDX Document Content", + "description": "Schema for the content/document.json file in a CDX document", "type": "object", "required": ["version", "blocks"], "properties": { @@ -154,7 +154,7 @@ "description": "Named style to apply" }, "semantic": { - "$ref": "https://codex.document/schemas/semantic.schema.json#/$defs/jsonLdAnnotation", + "$ref": "https://cdx.dev/schemas/semantic.schema.json#/$defs/jsonLdAnnotation", "description": "JSON-LD semantic annotation for this block" } } @@ -180,15 +180,15 @@ { "$ref": "#/$defs/linkMark" }, { "$ref": "#/$defs/anchorMark" }, { "$ref": "#/$defs/mathMark" }, - { "$ref": "https://codex.document/schemas/semantic.schema.json#/$defs/citationMark" }, - { "$ref": "https://codex.document/schemas/semantic.schema.json#/$defs/footnoteMark" }, - { "$ref": "https://codex.document/schemas/semantic.schema.json#/$defs/entityMark" }, - { "$ref": "https://codex.document/schemas/semantic.schema.json#/$defs/glossaryMark" }, - { "$ref": "https://codex.document/schemas/academic.schema.json#/$defs/theoremRefMark" }, - { "$ref": "https://codex.document/schemas/academic.schema.json#/$defs/equationRefMark" }, - { "$ref": "https://codex.document/schemas/academic.schema.json#/$defs/algorithmRefMark" }, - { "$ref": "https://codex.document/schemas/presentation.schema.json#/$defs/indexMark" }, - { "$ref": "https://codex.document/schemas/legal.schema.json#/$defs/legalCiteMark" } + { "$ref": "https://cdx.dev/schemas/semantic.schema.json#/$defs/citationMark" }, + { "$ref": "https://cdx.dev/schemas/semantic.schema.json#/$defs/footnoteMark" }, + { "$ref": "https://cdx.dev/schemas/semantic.schema.json#/$defs/entityMark" }, + { "$ref": "https://cdx.dev/schemas/semantic.schema.json#/$defs/glossaryMark" }, + { "$ref": "https://cdx.dev/schemas/academic.schema.json#/$defs/theoremRefMark" }, + { "$ref": "https://cdx.dev/schemas/academic.schema.json#/$defs/equationRefMark" }, + { "$ref": "https://cdx.dev/schemas/academic.schema.json#/$defs/algorithmRefMark" }, + { "$ref": "https://cdx.dev/schemas/presentation.schema.json#/$defs/indexMark" }, + { "$ref": "https://cdx.dev/schemas/legal.schema.json#/$defs/legalCiteMark" } ] } } diff --git a/schemas/dublin-core.schema.json b/schemas/dublin-core.schema.json index 1f736fd..e430238 100644 --- a/schemas/dublin-core.schema.json +++ b/schemas/dublin-core.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/dublin-core.schema.json", + "$id": "https://cdx.dev/schemas/dublin-core.schema.json", "title": "Dublin Core Metadata", - "description": "Schema for Dublin Core metadata in a Codex document", + "description": "Schema for Dublin Core metadata in a CDX document", "type": "object", "required": ["version", "terms"], "properties": { diff --git a/schemas/forms.schema.json b/schemas/forms.schema.json index 2fe5f62..4dbc267 100644 --- a/schemas/forms.schema.json +++ b/schemas/forms.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/forms.schema.json", - "title": "Codex Forms Extension", - "description": "Schema for forms extension blocks and data files in a Codex document", + "$id": "https://cdx.dev/schemas/forms.schema.json", + "title": "CDX Forms Extension", + "description": "Schema for forms extension blocks and data files in a CDX document", "$defs": { "validatorType": { "type": "string", diff --git a/schemas/legal.schema.json b/schemas/legal.schema.json index 6206008..c71e317 100644 --- a/schemas/legal.schema.json +++ b/schemas/legal.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/legal.schema.json", - "title": "Codex Legal Extension", - "description": "Schema for legal extension blocks and marks in a Codex document", + "$id": "https://cdx.dev/schemas/legal.schema.json", + "title": "CDX Legal Extension", + "description": "Schema for legal extension blocks and marks in a CDX document", "$defs": { "citationCategory": { "type": "string", diff --git a/schemas/manifest.schema.json b/schemas/manifest.schema.json index 05f04ff..4c8c09a 100644 --- a/schemas/manifest.schema.json +++ b/schemas/manifest.schema.json @@ -1,12 +1,12 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/manifest.schema.json", - "title": "Codex Document Manifest", - "description": "Schema for the manifest.json file in a Codex document", + "$id": "https://cdx.dev/schemas/manifest.schema.json", + "title": "CDX Document Manifest", + "description": "Schema for the manifest.json file in a CDX document", "type": "object", - "required": ["codex", "id", "state", "created", "modified", "content", "metadata"], + "required": ["cdx", "id", "state", "created", "modified", "content", "metadata"], "properties": { - "codex": { + "cdx": { "type": "string", "description": "Specification version", "pattern": "^\\d+\\.\\d+$", diff --git a/schemas/phantoms.schema.json b/schemas/phantoms.schema.json index db01f93..b835c27 100644 --- a/schemas/phantoms.schema.json +++ b/schemas/phantoms.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/phantoms.schema.json", - "title": "Codex Phantom Clusters", - "description": "Schema for the phantoms/clusters.json file in a Codex document", + "$id": "https://cdx.dev/schemas/phantoms.schema.json", + "title": "CDX Phantom Clusters", + "description": "Schema for the phantoms/clusters.json file in a CDX document", "type": "object", "required": ["version", "clusters"], "properties": { @@ -29,7 +29,7 @@ "description": "Unique cluster identifier" }, "anchor": { - "$ref": "https://codex.document/schemas/anchor.schema.json#/$defs/contentAnchor", + "$ref": "https://cdx.dev/schemas/anchor.schema.json#/$defs/contentAnchor", "description": "Anchor to document content" }, "label": { @@ -189,7 +189,7 @@ "author": { "description": "Author identity extending base person", "allOf": [ - { "$ref": "https://codex.document/schemas/anchor.schema.json#/$defs/person" } + { "$ref": "https://cdx.dev/schemas/anchor.schema.json#/$defs/person" } ], "unevaluatedProperties": false } diff --git a/schemas/precise-layout.schema.json b/schemas/precise-layout.schema.json index 55297a6..fb70c39 100644 --- a/schemas/precise-layout.schema.json +++ b/schemas/precise-layout.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/precise-layout.schema.json", - "title": "Codex Precise Layout", - "description": "Schema for precise layout files (presentation/layouts/*.json) in a Codex document. Required for FROZEN and PUBLISHED states.", + "$id": "https://cdx.dev/schemas/precise-layout.schema.json", + "title": "CDX Precise Layout", + "description": "Schema for precise layout files (presentation/layouts/*.json) in a CDX document. Required for FROZEN and PUBLISHED states.", "type": "object", "required": ["version", "presentationType", "targetFormat", "pageSize", "contentHash", "generatedAt", "pages"], "properties": { diff --git a/schemas/presentation.schema.json b/schemas/presentation.schema.json index eaeb715..7051563 100644 --- a/schemas/presentation.schema.json +++ b/schemas/presentation.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/presentation.schema.json", - "title": "Codex Presentation Layer", - "description": "Schema for presentation layer files in a Codex document", + "$id": "https://cdx.dev/schemas/presentation.schema.json", + "title": "CDX Presentation Layer", + "description": "Schema for presentation layer files in a CDX document", "type": "object", "required": ["version", "type", "defaults", "styles"], "properties": { diff --git a/schemas/provenance.schema.json b/schemas/provenance.schema.json index 5d61a76..9a5a485 100644 --- a/schemas/provenance.schema.json +++ b/schemas/provenance.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/provenance.schema.json", - "title": "Codex Provenance Record", - "description": "Schema for provenance/record.json in a Codex document", + "$id": "https://cdx.dev/schemas/provenance.schema.json", + "title": "CDX Provenance Record", + "description": "Schema for provenance/record.json in a CDX document", "type": "object", "required": ["version", "documentId", "created"], "properties": { diff --git a/schemas/security.schema.json b/schemas/security.schema.json index 9e442c6..cf2068b 100644 --- a/schemas/security.schema.json +++ b/schemas/security.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/security.schema.json", - "title": "Codex Security Extension", - "description": "Schema for security extension files in a Codex document", + "$id": "https://cdx.dev/schemas/security.schema.json", + "title": "CDX Security Extension", + "description": "Schema for security extension files in a CDX document", "$defs": { "signatureAlgorithm": { "type": "string", @@ -70,7 +70,7 @@ "signer": { "description": "Signer identity information extending base person", "allOf": [ - { "$ref": "https://codex.document/schemas/anchor.schema.json#/$defs/person" }, + { "$ref": "https://cdx.dev/schemas/anchor.schema.json#/$defs/person" }, { "type": "object", "properties": { diff --git a/schemas/semantic.schema.json b/schemas/semantic.schema.json index 90d5d0d..8266108 100644 --- a/schemas/semantic.schema.json +++ b/schemas/semantic.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://codex.document/schemas/semantic.schema.json", - "title": "Codex Semantic Extension", - "description": "Schema for semantic extension blocks and marks in a Codex document", + "$id": "https://cdx.dev/schemas/semantic.schema.json", + "title": "CDX Semantic Extension", + "description": "Schema for semantic extension blocks and marks in a CDX document", "$defs": { "citationMark": { "type": "object", diff --git a/scripts/check-example-coverage.ts b/scripts/check-example-coverage.ts index da7f00e..fcb1d17 100644 --- a/scripts/check-example-coverage.ts +++ b/scripts/check-example-coverage.ts @@ -65,7 +65,7 @@ function exampleUsesExtension(exampleDir: string, extensionId: string): boolean const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); const extensions = manifest.extensions || []; return extensions.some((ext: { id: string }) => - ext.id === `codex.${extensionId}` || ext.id === extensionId + ext.id === `cdx.${extensionId}` || ext.id === extensionId ); } catch { return false; diff --git a/scripts/generate-template.ts b/scripts/generate-template.ts index e3d9eac..6f0b083 100644 --- a/scripts/generate-template.ts +++ b/scripts/generate-template.ts @@ -1,7 +1,7 @@ #!/usr/bin/env npx tsx /** - * Generates minimal valid Codex document templates. + * Generates minimal valid CDX document templates. * * Usage: * npx tsx scripts/generate-template.ts --extensions academic,semantic --output ./my-doc @@ -23,7 +23,7 @@ interface ExtensionConfig { const extensionConfigs: Record = { academic: { - id: 'codex.academic', + id: 'cdx.academic', version: '0.1', required: false, directories: ['academic'], @@ -38,7 +38,7 @@ const extensionConfigs: Record = { } }, semantic: { - id: 'codex.semantic', + id: 'cdx.semantic', version: '0.1', required: false, directories: ['semantic'], @@ -54,7 +54,7 @@ const extensionConfigs: Record = { } }, forms: { - id: 'codex.forms', + id: 'cdx.forms', version: '0.1', required: false, directories: ['forms'], @@ -66,7 +66,7 @@ const extensionConfigs: Record = { } }, security: { - id: 'codex.security', + id: 'cdx.security', version: '0.1', required: false, directories: ['security'], @@ -78,7 +78,7 @@ const extensionConfigs: Record = { } }, collaboration: { - id: 'codex.collaboration', + id: 'cdx.collaboration', version: '0.2', required: false, directories: ['collaboration'], @@ -94,7 +94,7 @@ const extensionConfigs: Record = { } }, presentation: { - id: 'codex.presentation', + id: 'cdx.presentation', version: '0.1', required: false, directories: ['presentation'], @@ -111,7 +111,7 @@ const extensionConfigs: Record = { } }, phantoms: { - id: 'codex.phantoms', + id: 'cdx.phantoms', version: '0.1', required: false, directories: ['phantoms'], @@ -142,7 +142,7 @@ function generateManifest(extensions: string[]): Record { const now = new Date().toISOString(); const manifest: Record = { - codex: '0.1', + cdx: '0.1', id: 'pending', state: 'draft', created: now, @@ -213,7 +213,7 @@ function generateDublinCore(): Record { description: 'Document description', date: new Date().toISOString().split('T')[0], type: 'Text', - format: 'application/vnd.codex+zip', + format: 'application/vnd.cdx+zip', language: 'en' }; } @@ -267,7 +267,7 @@ function generateTemplate(outputDir: string, extensions: string[]): void { function parseArgs(): { extensions: string[]; output: string; listPresets: boolean } { const args = process.argv.slice(2); let extensions: string[] = []; - let output = './codex-document'; + let output = './cdx-document'; let listPresets = false; for (let i = 0; i < args.length; i++) { @@ -293,7 +293,7 @@ function parseArgs(): { extensions: string[]; output: string; listPresets: boole output = args[++i] || output; } else if (arg === '--help' || arg === '-h') { console.log(` -Codex Document Template Generator +CDX Document Template Generator Usage: npx tsx scripts/generate-template.ts [options] @@ -301,7 +301,7 @@ Usage: Options: --extensions, -e Comma-separated list of extensions to include --preset, -p Use a named preset (see --list-presets) - --output, -o Output directory (default: ./codex-document) + --output, -o Output directory (default: ./cdx-document) --list-presets, -l List available presets --help, -h Show this help diff --git a/spec/core/00-introduction.md b/spec/core/00-introduction.md index f593f9f..71dd9fa 100644 --- a/spec/core/00-introduction.md +++ b/spec/core/00-introduction.md @@ -1,12 +1,12 @@ -# Codex Document Format Specification +# CDX Specification **Version**: 0.1 (Draft) **Status**: Working Draft -**Editors**: Codex Specification Team +**Editors**: CDX Specification Team ## Abstract -This specification defines the Codex Document Format, an open format for documents that unifies viewing and editing modes while providing modern security, efficient compression, and native machine readability. +This specification defines CDX (Content-addressed Document eXchange), an open format for documents that unifies viewing and editing modes while providing modern security, efficient compression, and native machine readability. ## Status of This Document @@ -32,7 +32,7 @@ Additionally, existing formats suffer from: ### 1.2 Design Goals -The Codex format addresses these issues through the following design goals: +The CDX format addresses these issues through the following design goals: 1. **Semantic-First Architecture**: Content is stored as semantic blocks (headings, paragraphs, lists, etc.) rather than visual instructions. Presentation is derived from semantics, not the other way around. @@ -97,7 +97,7 @@ This section defines key terms used throughout the specification. ### 1.5 Document Structure Overview -A Codex document is a ZIP archive containing: +A CDX document is a ZIP archive containing: ``` document.cdx @@ -131,13 +131,13 @@ document.cdx ### 1.6 Annotation Layers -Codex provides three annotation storage locations, each serving different purposes: +CDX provides three annotation storage locations, each serving different purposes: | Layer | Location | Purpose | Extension Required | |-------|----------|---------|--------------------| | Core annotations | `security/annotations.json` | Minimal annotation support for frozen/published documents. Lightweight format for implementations that don't support extensions. | No (core) | -| Collaboration | `collaboration/comments.json` | Full-featured comments, suggestions, change tracking, presence awareness. Supersedes core annotations when active. | `codex.collaboration` | -| Phantoms | `phantoms/clusters.json` | Spatially-organized off-page annotation clusters (margin notes, mind maps). Orthogonal to inline annotations. | `codex.phantoms` | +| Collaboration | `collaboration/comments.json` | Full-featured comments, suggestions, change tracking, presence awareness. Supersedes core annotations when active. | `cdx.collaboration` | +| Phantoms | `phantoms/clusters.json` | Spatially-organized off-page annotation clusters (margin notes, mind maps). Orthogonal to inline annotations. | `cdx.phantoms` | **When to use each layer:** diff --git a/spec/core/01-container-format.md b/spec/core/01-container-format.md index 5405107..e77d600 100644 --- a/spec/core/01-container-format.md +++ b/spec/core/01-container-format.md @@ -5,7 +5,7 @@ ## 1. Overview -A Codex document is packaged as a ZIP archive with the file extension `.cdx`. This approach provides: +A CDX document is packaged as a ZIP archive with the file extension `.cdx`. This approach provides: - Familiar tooling and broad platform support - Built-in compression at the container level @@ -16,14 +16,14 @@ A Codex document is packaged as a ZIP archive with the file extension `.cdx`. Th ### 2.1 File Extension -Codex documents MUST use the file extension `.cdx`. +CDX documents MUST use the file extension `.cdx`. ### 2.2 MIME Types | Form | MIME Type | Use | |------|-----------|-----| -| Canonical (JSON) | `application/vnd.codex+json` | Primary format | -| Binary | `application/vnd.codex` | Future optimization | +| Canonical (JSON) | `application/vnd.cdx+json` | Primary format | +| Binary | `application/vnd.cdx` | Future optimization | Implementations SHOULD register these MIME types with the operating system for proper file association. @@ -31,7 +31,7 @@ Implementations SHOULD register these MIME types with the operating system for p ### 3.1 ZIP Format Requirements -Codex documents MUST be valid ZIP archives conforming to [APPNOTE.TXT](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT) version 6.3.3 or later. +CDX documents MUST be valid ZIP archives conforming to [APPNOTE.TXT](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT) version 6.3.3 or later. The following ZIP features are REQUIRED: @@ -40,7 +40,7 @@ The following ZIP features are REQUIRED: The following ZIP features MUST NOT be used: -- ZIP encryption (use Codex security extension instead) +- ZIP encryption (use CDX security extension instead) - Multi-volume archives ### 3.2 Compression Methods @@ -112,7 +112,7 @@ All file and directory names within the archive: The archive MAY include a ZIP comment containing: ``` -Codex Document Format v0.1 +CDX v0.1 ``` This enables format identification without extracting content. @@ -179,7 +179,7 @@ Implementations MUST ignore unrecognized files and directories. This enables: ### 8.1 Creating Archives -When creating a Codex document: +When creating a CDX document: 1. Write `manifest.json` as the first entry 2. Add required content and metadata files @@ -191,7 +191,7 @@ When creating a Codex document: ### 8.2 Reading Archives -When reading a Codex document: +When reading a CDX document: 1. Verify the archive is a valid ZIP 2. Read `manifest.json` first to determine version and structure diff --git a/spec/core/02-manifest.md b/spec/core/02-manifest.md index 7f159f8..86f4d74 100644 --- a/spec/core/02-manifest.md +++ b/spec/core/02-manifest.md @@ -5,7 +5,7 @@ ## 1. Overview -The manifest (`manifest.json`) is the root metadata structure of a Codex document. It describes the document's identity, version, state, structure, and processing requirements. +The manifest (`manifest.json`) is the root metadata structure of a CDX document. It describes the document's identity, version, state, structure, and processing requirements. ## 2. Location and Format @@ -22,7 +22,7 @@ The manifest MUST be: ```json { - "codex": "0.1", + "cdx": "0.1", "id": "sha256:a1b2c3d4e5f6...", "state": "draft", "created": "2025-01-15T10:30:00Z", @@ -44,7 +44,7 @@ The manifest MUST be: | Field | Type | Description | |-------|------|-------------| -| `codex` | string | Specification version (e.g., "0.1") | +| `cdx` | string | Specification version (e.g., "0.1") | | `id` | string | Content-addressable document identifier | | `state` | string | Document state (see State Machine spec) | | `created` | string | ISO 8601 creation timestamp | @@ -65,13 +65,13 @@ The manifest MUST be: ## 4. Field Definitions -### 4.1 `codex` (Required) +### 4.1 `cdx` (Required) The specification version this document conforms to. ```json { - "codex": "0.1" + "cdx": "0.1" } ``` @@ -249,12 +249,12 @@ Array of active extensions beyond the core specification. { "extensions": [ { - "id": "codex.security", + "id": "cdx.security", "version": "0.1", "required": true }, { - "id": "codex.collaboration", + "id": "cdx.collaboration", "version": "0.1", "required": false } @@ -336,7 +336,7 @@ Implementations MUST verify: 1. All required fields are present 2. Field types match specification -3. `codex` version is supported +3. `cdx` version is supported 4. Referenced files exist in archive 5. File hashes match when present @@ -363,7 +363,7 @@ The manifest state MUST be consistent with other indicators: 1. Extract `manifest.json` from archive 2. Parse as JSON -3. Validate `codex` version +3. Validate `cdx` version 4. Check required fields 5. Load referenced files as needed @@ -391,7 +391,7 @@ When modifying a document: ```json { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-15T10:30:00Z", @@ -410,7 +410,7 @@ When modifying a document: ```json { - "codex": "0.1", + "cdx": "0.1", "id": "sha256:3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b", "state": "frozen", "created": "2025-01-10T08:00:00Z", @@ -441,7 +441,7 @@ When modifying a document: }, "extensions": [ { - "id": "codex.security", + "id": "cdx.security", "version": "0.1", "required": true } diff --git a/spec/core/03-content-blocks.md b/spec/core/03-content-blocks.md index 63388c4..e9bf300 100644 --- a/spec/core/03-content-blocks.md +++ b/spec/core/03-content-blocks.md @@ -1138,7 +1138,7 @@ Before comparison or hashing, content SHOULD be normalized: "type": "paragraph", "children": [ { "type": "text", "value": "This document describes the " }, - { "type": "text", "value": "Codex", "marks": ["bold"] }, + { "type": "text", "value": "CDX", "marks": ["bold"] }, { "type": "text", "value": " format." } ] }, diff --git a/spec/core/03a-anchors-and-references.md b/spec/core/03a-anchors-and-references.md index 6eea802..4ef5e98 100644 --- a/spec/core/03a-anchors-and-references.md +++ b/spec/core/03a-anchors-and-references.md @@ -303,16 +303,16 @@ The anchor system is defined in the core specification but is primarily consumed | Extension | Anchor Usage | |-----------|-------------| -| Collaboration (`codex.collaboration`) | Comments, suggestions, change tracking, cursor/selection positions use ContentAnchor objects | -| Phantoms (`codex.phantoms`) | Phantom clusters anchor to content via ContentAnchor objects | -| Presentation (`codex.presentation`) | Cross-reference `target` fields use Content Anchor URI syntax | -| Semantic (`codex.semantic`) | Internal `semantic:ref` `target` fields use Content Anchor URI syntax | +| Collaboration (`cdx.collaboration`) | Comments, suggestions, change tracking, cursor/selection positions use ContentAnchor objects | +| Phantoms (`cdx.phantoms`) | Phantom clusters anchor to content via ContentAnchor objects | +| Presentation (`cdx.presentation`) | Cross-reference `target` fields use Content Anchor URI syntax | +| Semantic (`cdx.semantic`) | Internal `semantic:ref` `target` fields use Content Anchor URI syntax | See the respective extension specifications for details. ## 11. Cross-Reference Mechanism Selection -Multiple mechanisms exist for cross-referencing within Codex documents. Use the following guidance: +Multiple mechanisms exist for cross-referencing within CDX documents. Use the following guidance: | Mechanism | Extension | Use When | |-----------|-----------|----------| diff --git a/spec/core/05-asset-embedding.md b/spec/core/05-asset-embedding.md index 6023f49..3140a59 100644 --- a/spec/core/05-asset-embedding.md +++ b/spec/core/05-asset-embedding.md @@ -5,7 +5,7 @@ ## 1. Overview -Assets are binary resources embedded within a Codex document. This includes images, fonts, and other files that are referenced by content blocks or presentation layers. +Assets are binary resources embedded within a CDX document. This includes images, fonts, and other files that are referenced by content blocks or presentation layers. ## 2. Asset Categories @@ -354,7 +354,7 @@ sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ### 9.1 Policy -By default, Codex documents SHOULD be self-contained. External references: +By default, CDX documents SHOULD be self-contained. External references: - MAY be allowed for non-critical assets - MUST NOT be required for core content diff --git a/spec/core/06-document-hashing.md b/spec/core/06-document-hashing.md index 602ab09..bf112a8 100644 --- a/spec/core/06-document-hashing.md +++ b/spec/core/06-document-hashing.md @@ -5,7 +5,7 @@ ## 1. Overview -Codex documents use content-addressable hashing as a core identity mechanism. The document's hash serves as its canonical identifier, enabling: +CDX documents use content-addressable hashing as a core identity mechanism. The document's hash serves as its canonical identifier, enabling: - Integrity verification - Version identification @@ -68,7 +68,7 @@ Documents MAY specify their hash algorithm in the manifest: ```json { - "codex": "0.1", + "cdx": "0.1", "hashAlgorithm": "sha256", "id": "sha256:..." } diff --git a/spec/core/07-state-machine.md b/spec/core/07-state-machine.md index 44b3274..13953fe 100644 --- a/spec/core/07-state-machine.md +++ b/spec/core/07-state-machine.md @@ -5,7 +5,7 @@ ## 1. Overview -Codex documents have explicit lifecycle states that govern their mutability and signature requirements. This state machine addresses a fundamental limitation of PDF and other formats: the lack of clear semantics around document finalization. +CDX documents have explicit lifecycle states that govern their mutability and signature requirements. This state machine addresses a fundamental limitation of PDF and other formats: the lack of clear semantics around document finalization. ## 2. Design Goals @@ -364,8 +364,8 @@ There are three annotation storage locations, each serving a different purpose: | Layer | Location | Purpose | Extension Required | |-------|----------|---------|--------------------| | Core annotations | `security/annotations.json` | Minimal annotation support for frozen/published documents. Lightweight format for implementations that don't support extensions. | No (core) | -| Collaboration | `collaboration/comments.json` | Full-featured comments, suggestions, change tracking, presence. Supersedes core annotations when active. | `codex.collaboration` | -| Phantoms | `phantoms/clusters.json` | Spatially-organized off-page annotation clusters. Orthogonal to inline annotations. | `codex.phantoms` | +| Collaboration | `collaboration/comments.json` | Full-featured comments, suggestions, change tracking, presence. Supersedes core annotations when active. | `cdx.collaboration` | +| Phantoms | `phantoms/clusters.json` | Spatially-organized off-page annotation clusters. Orthogonal to inline annotations. | `cdx.phantoms` | When the collaboration extension is active, implementations SHOULD use `collaboration/comments.json` rather than `security/annotations.json` for new annotations. Core annotations exist as a fallback for minimal implementations. @@ -379,7 +379,7 @@ The state is stored in the manifest: ```json { - "codex": "0.1", + "cdx": "0.1", "state": "frozen", "id": "sha256:..." } @@ -475,7 +475,7 @@ For frozen documents: ```json { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-10T08:00:00Z", @@ -494,7 +494,7 @@ For frozen documents: ```json { - "codex": "0.1", + "cdx": "0.1", "id": "sha256:3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b", "state": "frozen", "created": "2025-01-10T08:00:00Z", @@ -507,7 +507,7 @@ For frozen documents: "signatures": "security/signatures.json" }, "extensions": [ - { "id": "codex.security", "version": "0.1", "required": true } + { "id": "cdx.security", "version": "0.1", "required": true } ], "metadata": { "dublinCore": "metadata/dublin-core.json" @@ -523,7 +523,7 @@ For frozen documents: ```json { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "created": "2025-01-16T09:00:00Z", diff --git a/spec/core/08-metadata.md b/spec/core/08-metadata.md index 39818e9..6ce4974 100644 --- a/spec/core/08-metadata.md +++ b/spec/core/08-metadata.md @@ -5,7 +5,7 @@ ## 1. Overview -Metadata provides descriptive information about a document: its title, author, subject, dates, and other properties. Codex uses Dublin Core as the foundation, with support for extensions. +Metadata provides descriptive information about a document: its title, author, subject, dates, and other properties. CDX uses Dublin Core as the foundation, with support for extensions. ## 2. Metadata Layers @@ -37,7 +37,7 @@ Location: `metadata/extended.json` (or custom paths) ### 3.1 File Format -The `version` field in Dublin Core metadata refers to the Dublin Core Metadata Element Set standard version (currently 1.1), not the Codex specification version. The Codex specification version is declared in the manifest's `specVersion` field. +The `version` field in Dublin Core metadata refers to the Dublin Core Metadata Element Set standard version (currently 1.1), not the CDX specification version. The CDX specification version is declared in the manifest's `specVersion` field. ```json { @@ -51,7 +51,7 @@ The `version` field in Dublin Core metadata refers to the Dublin Core Metadata E "contributor": ["Finance Team", "Legal Team"], "date": "2025-01-15", "type": "Text", - "format": "application/vnd.codex+json", + "format": "application/vnd.cdx+json", "identifier": "sha256:3a7bd3e2...", "source": null, "language": "en", @@ -278,7 +278,7 @@ Extended metadata supports domain-specific needs not covered by Dublin Core. ```json { - "namespace": "https://codex.document/metadata/academic", + "namespace": "https://cdx.dev/metadata/academic", "terms": { "doi": "10.1234/example.2025.001", "journal": "Journal of Document Engineering", @@ -295,7 +295,7 @@ Extended metadata supports domain-specific needs not covered by Dublin Core. ```json { - "namespace": "https://codex.document/metadata/legal", + "namespace": "https://cdx.dev/metadata/legal", "terms": { "caseNumber": "2025-CV-12345", "jurisdiction": "California", @@ -310,7 +310,7 @@ Extended metadata supports domain-specific needs not covered by Dublin Core. ```json { - "namespace": "https://codex.document/metadata/business", + "namespace": "https://cdx.dev/metadata/business", "terms": { "department": "Finance", "confidentiality": "Internal", @@ -483,7 +483,7 @@ Implementations SHOULD support metadata-based search: "contributor": ["Research Team", "Policy Advisory Board"], "date": "2025-01-15", "type": "Text", - "format": "application/vnd.codex+json", + "format": "application/vnd.cdx+json", "identifier": "sha256:abc123...", "source": "https://doi.org/10.1234/previous-study", "language": "en", @@ -513,7 +513,7 @@ Extended (`metadata/legal.json`): ```json { "version": "0.1", - "namespace": "https://codex.document/metadata/legal", + "namespace": "https://cdx.dev/metadata/legal", "terms": { "contractType": "Service Agreement", "parties": ["Acme Corp", "XYZ Services"], diff --git a/spec/core/09-provenance-and-lineage.md b/spec/core/09-provenance-and-lineage.md index a1f4db0..311b93c 100644 --- a/spec/core/09-provenance-and-lineage.md +++ b/spec/core/09-provenance-and-lineage.md @@ -5,7 +5,7 @@ ## 1. Overview -Codex documents form a cryptographic chain through content-addressable hashing and lineage pointers. This enables: +CDX documents form a cryptographic chain through content-addressable hashing and lineage pointers. This enables: - Tamper-evident document history - Verifiable ancestry ("this document descended from that one") @@ -17,7 +17,7 @@ Codex documents form a cryptographic chain through content-addressable hashing a ### 2.1 Documents as a Hash Chain -Each Codex document's identity IS its content hash. When a document references its parent by hash, it creates an immutable link: +Each CDX document's identity IS its content hash. When a document references its parent by hash, it creates an immutable link: ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ @@ -514,7 +514,7 @@ If intermediate documents are unavailable: ```json { - "codex": "0.1", + "cdx": "0.1", "id": "sha256:abc123...", "state": "frozen", "lineage": { diff --git a/spec/extensions/README.md b/spec/extensions/README.md index 8d7d668..6752595 100644 --- a/spec/extensions/README.md +++ b/spec/extensions/README.md @@ -1,19 +1,19 @@ -# Codex Extensions +# CDX Extensions -This directory contains specifications for Codex extensions. Each extension adds specialized functionality to the core Codex document format. +This directory contains specifications for CDX extensions. Each extension adds specialized functionality to the core CDX specification. ## Available Extensions | Extension | ID | Version | Status | Purpose | |-----------|----|---------|----|---------| -| [Semantic](semantic/README.md) | `codex.semantic` | 0.1 | Draft | Citations, footnotes, glossary, entity annotations | -| [Academic](academic/README.md) | `codex.academic` | 0.1 | Draft | Theorems, proofs, exercises, algorithms, equations | -| [Forms](forms/README.md) | `codex.forms` | 0.1 | Draft | Interactive form fields and validation | -| [Collaboration](collaboration/README.md) | `codex.collaboration` | 0.2 | Draft | Comments, track changes, real-time collaboration | -| [Security](security/README.md) | `codex.security` | 0.1 | Draft | Digital signatures, encryption, access control | -| [Phantoms](phantoms/README.md) | `codex.phantoms` | 0.1 | Draft | Off-page annotation clusters | -| [Presentation](presentation/README.md) | `codex.presentation` | 0.1 | Draft | Layout templates and rendering hints | -| [Legal](legal/README.md) | `codex.legal` | 0.1 | Draft | Legal citations, clause references, jurisdiction metadata | +| [Semantic](semantic/README.md) | `cdx.semantic` | 0.1 | Draft | Citations, footnotes, glossary, entity annotations | +| [Academic](academic/README.md) | `cdx.academic` | 0.1 | Draft | Theorems, proofs, exercises, algorithms, equations | +| [Forms](forms/README.md) | `cdx.forms` | 0.1 | Draft | Interactive form fields and validation | +| [Collaboration](collaboration/README.md) | `cdx.collaboration` | 0.2 | Draft | Comments, track changes, real-time collaboration | +| [Security](security/README.md) | `cdx.security` | 0.1 | Draft | Digital signatures, encryption, access control | +| [Phantoms](phantoms/README.md) | `cdx.phantoms` | 0.1 | Draft | Off-page annotation clusters | +| [Presentation](presentation/README.md) | `cdx.presentation` | 0.1 | Draft | Layout templates and rendering hints | +| [Legal](legal/README.md) | `cdx.legal` | 0.1 | Draft | Legal citations, clause references, jurisdiction metadata | ## Extension Compatibility @@ -47,7 +47,7 @@ Extensions are declared in the manifest: { "extensions": [ { - "id": "codex.semantic", + "id": "cdx.semantic", "version": "0.1", "required": false } @@ -82,7 +82,7 @@ Extensions share common definitions from the core specification: ## Implementation Guidance -When implementing Codex support, consider the following priority order: +When implementing CDX support, consider the following priority order: ### Required for Basic Support 1. Core content blocks diff --git a/spec/extensions/academic/README.md b/spec/extensions/academic/README.md index 3e2cf1f..d5d96d8 100644 --- a/spec/extensions/academic/README.md +++ b/spec/extensions/academic/README.md @@ -1,6 +1,6 @@ # Academic Extension -**Extension ID**: `codex.academic` +**Extension ID**: `cdx.academic` **Version**: 0.1 **Status**: Draft @@ -23,7 +23,7 @@ The Academic Extension provides structured support for academic and scientific d { "extensions": [ { - "id": "codex.academic", + "id": "cdx.academic", "version": "0.1", "required": false } @@ -1045,7 +1045,7 @@ The `resetOn` field accepts heading level identifiers: `heading1` through `headi ## 12. Author Identification -For scholarly documents, author identification is critical for attribution and citation. The Codex specification uses a base `person` object defined in `anchor.schema.json` that includes an `identifier` field for persistent identifiers. +For scholarly documents, author identification is critical for attribution and citation. The CDX specification uses a base `person` object defined in `anchor.schema.json` that includes an `identifier` field for persistent identifiers. ### 12.1 ORCID Recommendation diff --git a/spec/extensions/collaboration/README.md b/spec/extensions/collaboration/README.md index ae54d08..f8a4c2e 100644 --- a/spec/extensions/collaboration/README.md +++ b/spec/extensions/collaboration/README.md @@ -1,6 +1,6 @@ # Collaboration Extension -**Extension ID**: `codex.collaboration` +**Extension ID**: `cdx.collaboration` **Version**: 0.2 **Status**: Draft @@ -19,7 +19,7 @@ The Collaboration Extension enables multi-user editing and feedback: { "extensions": [ { - "id": "codex.collaboration", + "id": "cdx.collaboration", "version": "0.2", "required": false } @@ -41,7 +41,7 @@ Conflict-free Replicated Data Types (CRDTs) enable: ### 3.2 Integration Model -The Codex format doesn't mandate a specific CRDT implementation. Instead, it defines: +The CDX format doesn't mandate a specific CRDT implementation. Instead, it defines: - How CRDT state maps to content blocks - Synchronization protocol hooks @@ -172,7 +172,7 @@ When exchanging documents between implementations using different CRDT formats, { "action": "materialized", "timestamp": "2025-01-15T12:00:00Z", - "agent": "codex-tool/2.0", + "agent": "cdx-tool/2.0", "details": { "fromCrdtFormat": "yjs", "toCrdtFormat": "automerge", diff --git a/spec/extensions/forms/README.md b/spec/extensions/forms/README.md index 2c3491b..5caf7de 100644 --- a/spec/extensions/forms/README.md +++ b/spec/extensions/forms/README.md @@ -1,6 +1,6 @@ # Forms Extension -**Extension ID**: `codex.forms` +**Extension ID**: `cdx.forms` **Version**: 0.1 **Status**: Draft @@ -20,7 +20,7 @@ The Forms Extension enables interactive form fields within documents: { "extensions": [ { - "id": "codex.forms", + "id": "cdx.forms", "version": "0.1", "required": false } diff --git a/spec/extensions/legal/README.md b/spec/extensions/legal/README.md index af28d99..ce3304d 100644 --- a/spec/extensions/legal/README.md +++ b/spec/extensions/legal/README.md @@ -1,6 +1,6 @@ # Legal Extension -**Extension ID**: `codex.legal` +**Extension ID**: `cdx.legal` **Version**: 0.1 **Status**: Draft @@ -18,7 +18,7 @@ The Legal Extension provides specialized blocks and marks for legal documents, i { "extensions": [ { - "id": "codex.legal", + "id": "cdx.legal", "version": "0.1", "required": false } diff --git a/spec/extensions/phantoms/README.md b/spec/extensions/phantoms/README.md index 492d097..d88e135 100644 --- a/spec/extensions/phantoms/README.md +++ b/spec/extensions/phantoms/README.md @@ -1,6 +1,6 @@ # Phantom Extension -**Extension ID**: `codex.phantoms` +**Extension ID**: `cdx.phantoms` **Version**: 0.1 **Status**: Draft @@ -21,7 +21,7 @@ Phantom clusters are groups of annotation objects that the rendering application { "extensions": [ { - "id": "codex.phantoms", + "id": "cdx.phantoms", "version": "0.1", "required": false } diff --git a/spec/extensions/presentation/README.md b/spec/extensions/presentation/README.md index 9a16fd5..492b229 100644 --- a/spec/extensions/presentation/README.md +++ b/spec/extensions/presentation/README.md @@ -1,6 +1,6 @@ # Presentation Extension -**Extension ID**: `codex.presentation` +**Extension ID**: `cdx.presentation` **Version**: 0.1 **Status**: Draft @@ -15,7 +15,7 @@ The Presentation Extension provides advanced layout and styling capabilities bey ### File Paths -Presentation extension data is stored within the `presentation/` directory in the Codex archive: +Presentation extension data is stored within the `presentation/` directory in the CDX archive: | File | Purpose | |------|---------| @@ -31,7 +31,7 @@ These files are referenced from the manifest's extension declaration. { "extensions": [ { - "id": "codex.presentation", + "id": "cdx.presentation", "version": "0.1", "required": false } diff --git a/spec/extensions/security/README.md b/spec/extensions/security/README.md index bd11773..29f640f 100644 --- a/spec/extensions/security/README.md +++ b/spec/extensions/security/README.md @@ -1,12 +1,12 @@ # Security Extension -**Extension ID**: `codex.security` +**Extension ID**: `cdx.security` **Version**: 0.1 **Status**: Draft ## 1. Overview -The Security Extension provides cryptographic capabilities for Codex documents: +The Security Extension provides cryptographic capabilities for CDX documents: - Digital signatures for document authentication and integrity - Encryption for confidentiality @@ -20,7 +20,7 @@ To use this extension, declare it in the manifest: { "extensions": [ { - "id": "codex.security", + "id": "cdx.security", "version": "0.1", "required": true } diff --git a/spec/extensions/semantic/README.md b/spec/extensions/semantic/README.md index 6a1c1ee..d904104 100644 --- a/spec/extensions/semantic/README.md +++ b/spec/extensions/semantic/README.md @@ -1,6 +1,6 @@ # Semantic Extension -**Extension ID**: `codex.semantic` +**Extension ID**: `cdx.semantic` **Version**: 0.1 **Status**: Draft @@ -19,7 +19,7 @@ The Semantic Extension enhances documents with rich semantic markup: { "extensions": [ { - "id": "codex.semantic", + "id": "cdx.semantic", "version": "0.1", "required": false } @@ -390,7 +390,7 @@ The semantic extension provides `semantic:measurement` for measurements with lin #### 6.2.1 Core vs Semantic Measurements -The Codex format defines two measurement types for different use cases: +The CDX format defines two measurement types for different use cases: | Type | Location | Purpose | |------|----------|---------| diff --git a/spec/profiles/README.md b/spec/profiles/README.md index bf717af..e2e6c21 100644 --- a/spec/profiles/README.md +++ b/spec/profiles/README.md @@ -1,6 +1,6 @@ -# Codex Profiles +# CDX Profiles -Profiles define subsets of the Codex format optimized for specific use cases. They provide guidance on which features to use (and avoid) for particular document types. +Profiles define subsets of the CDX format optimized for specific use cases. They provide guidance on which features to use (and avoid) for particular document types. ## Available Profiles @@ -22,23 +22,23 @@ Profiles do NOT: - Create new features or block types - Override the core specification - Require special handling by implementations -- Restrict what a valid Codex document can contain +- Restrict what a valid CDX document can contain ## Profile Conformance -Documents are not required to declare profile conformance. A document conforming to a profile is simply a valid Codex document that happens to use only the features recommended by that profile. +Documents are not required to declare profile conformance. A document conforming to a profile is simply a valid CDX document that happens to use only the features recommended by that profile. However, documents MAY declare their intended profile in the manifest for tooling purposes: ```json { - "codex": "0.1", + "cdx": "0.1", "profile": "simple", ... } ``` -Implementations SHOULD ignore unrecognized profile values and treat the document as a standard Codex document. +Implementations SHOULD ignore unrecognized profile values and treat the document as a standard CDX document. ## Future Profiles diff --git a/spec/profiles/simple-documents.md b/spec/profiles/simple-documents.md index ef171e4..38e11ff 100644 --- a/spec/profiles/simple-documents.md +++ b/spec/profiles/simple-documents.md @@ -6,14 +6,14 @@ ## 1. Overview -The Simple Documents profile defines a minimal subset of Codex for recreational reading, basic articles, and straightforward prose documents. It is designed to be: +The Simple Documents profile defines a minimal subset of CDX for recreational reading, basic articles, and straightforward prose documents. It is designed to be: - **Lightweight** — minimal required files and structure - **Easy to create** — no extensions, no presentation layers, no precise layouts -- **Universally renderable** — any Codex reader can display these documents +- **Universally renderable** — any CDX reader can display these documents - **EPUB-comparable** — similar complexity for similar use cases -This profile is non-normative guidance. Documents conforming to this profile are fully valid Codex documents that happen to use only a subset of available features. +This profile is non-normative guidance. Documents conforming to this profile are fully valid CDX documents that happen to use only a subset of available features. ## 2. Use Cases @@ -77,7 +77,7 @@ Simple Documents do not need: ```json { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "content": { @@ -93,7 +93,7 @@ Simple Documents do not need: | Field | Required | Notes | |-------|----------|-------| -| `codex` | Yes | Specification version | +| `cdx` | Yes | Specification version | | `id` | Yes | Use `"pending"` for drafts | | `state` | Yes | Typically `"draft"` for simple documents | | `content` | Yes | Path to content file | @@ -106,7 +106,7 @@ Simple Documents do not need: ```json { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "content": { @@ -325,15 +325,15 @@ JSON is more verbose than XHTML for prose: | Format | Example paragraph | |--------|-------------------| | XHTML | `

"Hello," she said.

` (27 bytes) | -| Codex | `{"type":"paragraph","children":[{"type":"text","value":"\"Hello,\" she said."}]}` (81 bytes) | +| CDX | `{"type":"paragraph","children":[{"type":"text","value":"\"Hello,\" she said."}]}` (81 bytes) | Raw JSON is approximately 3× larger than XHTML for prose content. ### 9.2 Compression -With Zstandard compression (Codex default), the size difference is minimal: +With Zstandard compression (CDX default), the size difference is minimal: -| Document | EPUB (deflate) | Codex (zstd) | Difference | +| Document | EPUB (deflate) | CDX (zstd) | Difference | |----------|----------------|--------------|------------| | 100KB novel | ~35KB | ~40KB | +14% | | 500KB novel | ~170KB | ~190KB | +12% | @@ -353,7 +353,7 @@ The JSON verbosity provides: ### 10.1 Structure Mapping -| EPUB | Codex Simple | +| EPUB | CDX Simple | |------|--------------| | `mimetype` | (not needed) | | `META-INF/container.xml` | (not needed) | @@ -365,7 +365,7 @@ The JSON verbosity provides: ### 10.2 Content Mapping -| XHTML | Codex Block | +| XHTML | CDX Block | |-------|-------------| | `

` - `

` | `heading` (level 1-6) | | `

` | `paragraph` | @@ -380,7 +380,7 @@ The JSON verbosity provides: ### 10.3 Conversion Notes -1. **Consolidate chapters** — EPUB splits content across files; Codex uses one file +1. **Consolidate chapters** — EPUB splits content across files; CDX uses one file 2. **Flatten CSS** — Convert CSS classes to presentation styles or omit 3. **Extract metadata** — Move Dublin Core from OPF to separate JSON file 4. **Simplify navigation** — Table of contents is generated from headings @@ -394,7 +394,7 @@ A minimal novel in three files: ```json { - "codex": "0.1", + "cdx": "0.1", "id": "pending", "state": "draft", "content": { @@ -499,7 +499,7 @@ A minimal novel in three files: ### 12.3 For Converters -1. EPUB → Codex conversion should be straightforward +1. EPUB → CDX conversion should be straightforward 2. Consolidate multiple XHTML files into single document.json 3. Preserve reading order from EPUB spine 4. Extract Dublin Core metadata diff --git a/use-cases/use-cases.md b/use-cases/use-cases.md index 6a1e747..3dc1cb4 100644 --- a/use-cases/use-cases.md +++ b/use-cases/use-cases.md @@ -1,6 +1,6 @@ -# Codex Format Use Cases +# CDX Format Use Cases -This document describes concrete scenarios where the Codex format provides value over existing solutions. +This document describes concrete scenarios where the CDX format provides value over existing solutions. ## 1. Legal Contracts and Agreements @@ -13,9 +13,9 @@ A law firm drafts contracts that require signatures from multiple parties, must - No clear "frozen" state — uncertainty about what was actually signed - Format conversion loses fidelity -### Codex Solution +### CDX Solution ``` -1. Draft contract in Codex editor (state: draft) +1. Draft contract in CDX editor (state: draft) 2. Submit for review (state: review) — all parties can comment 3. Final version frozen with signatures (state: frozen) - Document ID cryptographically binds content to signatures @@ -44,7 +44,7 @@ A researcher publishes a paper with figures, citations, and supplementary data. - Supplementary materials require separate downloads - Text extraction for meta-analysis is unreliable -### Codex Solution +### CDX Solution ``` Paper structure: ├── Semantic content with structured headings @@ -78,7 +78,7 @@ A company produces quarterly financial reports that must be: - Accessibility often an afterthought - Updates require republishing entire document -### Codex Solution +### CDX Solution ``` Single source document with: ├── Content layer: semantic financial data @@ -109,7 +109,7 @@ A government agency publishes regulations, forms, and public records that must b - Long-term preservation uncertain - Citizen data extraction for research is blocked -### Codex Solution +### CDX Solution ``` Public regulation document: ├── Content: semantic legal text with section references @@ -138,7 +138,7 @@ A software company maintains documentation that includes code samples, diagrams, - Code samples go stale - Cross-references break on restructuring -### Codex Solution +### CDX Solution ``` Documentation structure: ├── Content: semantic docs with code blocks @@ -174,7 +174,7 @@ A hospital generates patient records that must be: - Patient portals show images of documents - Long-term format stability uncertain -### Codex Solution +### CDX Solution ``` Medical record: ├── Content: clinical notes as semantic blocks @@ -207,7 +207,7 @@ A university creates course materials including syllabi, lecture notes, and assi - No version tracking for materials - Students print some, view others digitally -### Codex Solution +### CDX Solution ``` Course syllabus: ├── Content: @@ -239,7 +239,7 @@ A news organization publishes investigative reports with primary sources, must p - No way to cryptographically prove document unchanged - Archive.org not reliable for sensitive materials -### Codex Solution +### CDX Solution ``` Investigative report: ├── Content: article with citations to sources @@ -272,11 +272,11 @@ A real estate closing involves dozens of documents requiring signatures from mul - Document packages unwieldy - Long-term validity of e-signatures uncertain -### Codex Solution +### CDX Solution ``` Closing package: ├── Manifest: list of all documents -├── Documents (each a Codex): +├── Documents (each a CDX): │ ├── Purchase agreement │ ├── Deed │ ├── Title insurance @@ -307,7 +307,7 @@ An individual wants to create, sign, and preserve personal documents (wills, dir - No easy way to self-sign - Cloud storage may not exist in 50 years -### Codex Solution +### CDX Solution ``` Personal document: ├── Content: the document itself @@ -328,7 +328,7 @@ Personal document: ## Summary: Format Selection Guide -| Use Case | Key Codex Advantage | +| Use Case | Key CDX Advantage | |----------|---------------------| | Legal | Clear freeze semantics, modern signatures | | Academic | Semantic citations, machine analysis |