Skip to content

02-manifest.md

Latest commit

 

History

History
458 lines (361 loc) · 10.9 KB

02-manifest.md

File metadata and controls

458 lines (361 loc) · 10.9 KB

Manifest

Section: Core Specification Version: 0.1

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.

2. Location and Format

The manifest MUST be:

  • Located at /manifest.json in the archive root
  • The first file in the ZIP archive
  • Valid JSON conforming to RFC 8259
  • Encoded as UTF-8 without BOM

3. Structure

3.1 Root Object

{
  "codex": "0.1",
  "id": "sha256:a1b2c3d4e5f6...",
  "state": "draft",
  "created": "2025-01-15T10:30:00Z",
  "modified": "2025-01-15T14:22:00Z",
  "content": {
    "path": "content/document.json",
    "hash": "sha256:..."
  },
  "presentation": [...],
  "assets": {...},
  "security": {...},
  "metadata": {...},
  "extensions": [...],
  "lineage": {...}
}

3.2 Required Fields

Field Type Description
codex 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
modified string ISO 8601 last modification timestamp
content object Content layer reference
metadata object Metadata references

3.3 Optional Fields

Field Type Description
presentation array Presentation layer references
assets object Asset manifest
security object Security layer reference
extensions array Active extension declarations
lineage object Version history and parent reference
phantoms object Phantom layer reference (Phantom Extension)

4. Field Definitions

4.1 codex (Required)

The specification version this document conforms to.

{
  "codex": "0.1"
}

Format: MAJOR.MINOR (PATCH omitted for documents)

Implementations MUST reject documents with a major version they do not support.

4.2 id (Required)

The content-addressable identifier for this document version.

{
  "id": "sha256:3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b"
}

Format: algorithm:hexdigest

See Document Hashing specification for computation rules.

For documents in draft state, the id MAY be a placeholder that is computed when the document is finalized:

{
  "id": "pending"
}

4.3 state (Required)

The current lifecycle state of the document.

{
  "state": "draft"
}

Valid values: "draft", "review", "frozen", "published"

See State Machine specification for state definitions and transitions.

4.4 created (Required)

ISO 8601 timestamp when the document was first created.

{
  "created": "2025-01-15T10:30:00Z"
}

This value MUST NOT change across document versions. Use lineage to trace original creation time.

4.5 modified (Required)

ISO 8601 timestamp when the document was last modified.

{
  "modified": "2025-01-15T14:22:00Z"
}

This value MUST be updated on any content or metadata change.

4.6 content (Required)

Reference to the content layer.

{
  "content": {
    "path": "content/document.json",
    "hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "compression": "zstd"
  }
}
Field Type Required Description
path string Yes Relative path within archive
hash string Yes Hash of file contents
compression string No Compression used ("deflate", "zstd", "none")
merkleRoot string No Merkle tree root hash of content blocks (see Provenance spec section 4.4)
blockCount integer No Number of content blocks in the document

4.7 presentation (Optional)

Array of presentation layer references.

{
  "presentation": [
    {
      "type": "paginated",
      "path": "presentation/paginated.json",
      "hash": "sha256:...",
      "default": true
    },
    {
      "type": "continuous",
      "path": "presentation/continuous.json",
      "hash": "sha256:..."
    }
  ]
}
Field Type Required Description
type string Yes Presentation type identifier
path string Yes Relative path within archive
hash string Yes Hash of file contents
default boolean No Whether this is the default presentation

Standard presentation types:

  • "paginated" - Fixed page layout for print
  • "continuous" - Vertical scroll for screen
  • "responsive" - Reflowable layout

4.8 assets (Optional)

Asset manifest describing embedded resources.

{
  "assets": {
    "images": {
      "count": 5,
      "totalSize": 1048576,
      "index": "assets/images/index.json"
    },
    "fonts": {
      "count": 2,
      "totalSize": 65536,
      "index": "assets/fonts/index.json"
    },
    "embeds": {
      "count": 1,
      "totalSize": 2048,
      "index": "assets/embeds/index.json"
    }
  }
}

See Asset Embedding specification for index file format.

4.9 security (Optional)

Security layer reference. Presence indicates the Security Extension is active.

{
  "security": {
    "signatures": "security/signatures.json",
    "encryption": null
  }
}
Field Type Description
signatures string Path to signatures file, or null
encryption string Path to encryption metadata, or null

4.10 extensions (Optional)

Array of active extensions beyond the core specification.

{
  "extensions": [
    {
      "id": "codex.security",
      "version": "0.1",
      "required": true
    },
    {
      "id": "codex.collaboration",
      "version": "0.1",
      "required": false
    }
  ]
}
Field Type Required Description
id string Yes Extension identifier
version string Yes Extension version
required boolean Yes Whether extension is required for correct rendering

If required is true, implementations that do not support the extension MUST refuse to process the document.

4.11 metadata (Required)

References to metadata files.

{
  "metadata": {
    "dublinCore": "metadata/dublin-core.json",
    "custom": "metadata/custom.json"
  }
}
Field Type Required Description
dublinCore string Yes Path to Dublin Core metadata
custom string No Path to custom metadata

4.12 phantoms (Optional)

Reference to the phantom annotation layer. Presence indicates the Phantom Extension is active.

{
  "phantoms": {
    "clusters": "phantoms/clusters.json"
  }
}
Field Type Required Description
clusters string Yes Path to phantom clusters file

Phantom data is explicitly outside the content hash boundary. No hash field is included — adding or editing phantoms never changes the document ID.

4.13 lineage (Optional)

Version history and document relationships. The manifest lineage provides a summary of the document's version context. The full provenance record (provenance/record.json) extends this with the complete ancestor chain, depth, merge history, and timestamps. See the Provenance and Lineage specification for the extended model.

{
  "lineage": {
    "parent": "sha256:previousdochash...",
    "version": 3,
    "branch": "main",
    "note": "Updated section 3 per review feedback"
  }
}
Field Type Required Description
parent string No Document ID of parent version
version integer No Sequential version number
branch string No Branch identifier for parallel versions
note string No Description of changes from parent

5. Validation

5.1 Required Field Validation

Implementations MUST verify:

  1. All required fields are present
  2. Field types match specification
  3. codex version is supported
  4. Referenced files exist in archive
  5. File hashes match when present

5.2 Hash Verification

For frozen documents, implementations SHOULD verify that referenced file hashes match actual contents. Hash mismatches in frozen documents MUST be reported as errors.

5.3 State Consistency

The manifest state MUST be consistent with other indicators:

State Security Signatures Lineage.parent
draft Optional Optional
review Optional Optional
frozen Required Required if forked
published Required Required if forked

Note: Lineage.parent is required for frozen/published documents that were derived from another document (forked). Root documents — those created from scratch, not forked from a parent — have no parent and omit this field.

6. Processing Model

6.1 Reading

  1. Extract manifest.json from archive
  2. Parse as JSON
  3. Validate codex version
  4. Check required fields
  5. Load referenced files as needed

6.2 Writing

  1. Construct manifest object
  2. Compute content hash
  3. Compute document ID (if not draft)
  4. Set timestamps
  5. Serialize to JSON
  6. Write as first file in archive

6.3 Updating

When modifying a document:

  1. Update modified timestamp
  2. Recalculate content hash
  3. Update id if not draft
  4. If version-controlled, set lineage.parent to previous id

7. Examples

7.1 Minimal Draft Document

{
  "codex": "0.1",
  "id": "pending",
  "state": "draft",
  "created": "2025-01-15T10:30:00Z",
  "modified": "2025-01-15T10:30:00Z",
  "content": {
    "path": "content/document.json",
    "hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "metadata": {
    "dublinCore": "metadata/dublin-core.json"
  }
}

7.2 Signed Frozen Document

{
  "codex": "0.1",
  "id": "sha256:3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
  "state": "frozen",
  "created": "2025-01-10T08:00:00Z",
  "modified": "2025-01-15T14:22:00Z",
  "content": {
    "path": "content/document.json",
    "hash": "sha256:abc123...",
    "compression": "zstd"
  },
  "presentation": [
    {
      "type": "paginated",
      "path": "presentation/paginated.json",
      "hash": "sha256:def456...",
      "default": true
    }
  ],
  "assets": {
    "images": {
      "count": 3,
      "totalSize": 524288,
      "index": "assets/images/index.json"
    }
  },
  "security": {
    "signatures": "security/signatures.json",
    "encryption": null
  },
  "extensions": [
    {
      "id": "codex.security",
      "version": "0.1",
      "required": true
    }
  ],
  "metadata": {
    "dublinCore": "metadata/dublin-core.json"
  },
  "lineage": {
    "parent": "sha256:previousversion...",
    "version": 2,
    "note": "Final version after legal review"
  }
}