From 61cda28e79c380cd73a3e1e5e44a839942f69016 Mon Sep 17 00:00:00 2001 From: Greg von Nessi Date: Sun, 22 Feb 2026 13:43:16 +0000 Subject: [PATCH] Fix 25 spec issues across core and extensions P0 (Correctness): - Replace undefined attachment block with link mark example - Add forms:form and forms:submit formal definitions and schema entries - Document locatorType field on citation mark - Add legal extension to extension index tables - Fix footnote number/symbol as conditional requirement - Add cross-extension footnote model guidance P1 (Consistency): - Document extension mark naming convention (Section 5.1) - Add CRDT metadata to hash boundary table - Change resetOn from chapter/section to heading levels - Clarify Person identity field divergence across extensions - Rename presentation figure numbering to numberingConfig - Add cross-reference mechanism selection guidance - Add change record and reply object field tables - Add field tables for all form field types - Document ACL enforcement model as advisory P2 (Quality): - Document glossary discovery and sort enum values - Add semantic:term field table and plain-string rationale - Note both CSL date formats as valid - Add presentation extension file paths section - Clarify forms:signature vs security digital signatures - Document "today" as only relative date keyword - Document phantom cross-reference limitations - Renumber section 1.5a to 1.6 - Clarify Dublin Core version vs Codex version --- schemas/academic.schema.json | 4 +- spec/core/00-introduction.md | 7 +- spec/core/03-content-blocks.md | 9 ++ spec/core/03a-anchors-and-references.md | 15 +++ spec/core/05-asset-embedding.md | 20 +++- spec/core/06-document-hashing.md | 3 + spec/core/08-metadata.md | 2 + spec/extensions/README.md | 21 ++-- spec/extensions/academic/README.md | 16 ++- spec/extensions/collaboration/README.md | 42 ++++++- spec/extensions/forms/README.md | 142 ++++++++++++++++++++++++ spec/extensions/legal/README.md | 2 + spec/extensions/phantoms/README.md | 4 + spec/extensions/presentation/README.md | 20 +++- spec/extensions/security/README.md | 2 + spec/extensions/semantic/README.md | 26 ++++- 16 files changed, 305 insertions(+), 30 deletions(-) diff --git a/schemas/academic.schema.json b/schemas/academic.schema.json index 2b8ab1b..da20fe7 100644 --- a/schemas/academic.schema.json +++ b/schemas/academic.schema.json @@ -92,8 +92,8 @@ }, "resetTrigger": { "type": "string", - "description": "When to reset counters", - "enum": ["chapter", "section", "none"] + "description": "When to reset counters. Uses heading level identifiers corresponding to the core heading block's level attribute.", + "enum": ["heading1", "heading2", "heading3", "heading4", "heading5", "heading6", "none"] }, "theoremBlock": { "type": "object", diff --git a/spec/core/00-introduction.md b/spec/core/00-introduction.md index 6b37996..f593f9f 100644 --- a/spec/core/00-introduction.md +++ b/spec/core/00-introduction.md @@ -129,7 +129,7 @@ document.cdx └── dublin-core.json # Dublin Core metadata (required) ``` -### 1.5a Annotation Layers +### 1.6 Annotation Layers Codex provides three annotation storage locations, each serving different purposes: @@ -151,7 +151,7 @@ All annotation layers are **outside the content hash boundary** — adding annot **Implementation note**: Core annotations live in `security/annotations.json` because they share the security directory's "outside content hash" semantics. When migrating from core annotations to the collaboration extension, implementations SHOULD convert existing annotations to the collaboration format and remove the core annotations file. The two formats SHOULD NOT coexist in the same document to avoid confusion. -### 1.6 Specification Organization +### 1.7 Specification Organization This specification is organized into the following sections: @@ -173,8 +173,9 @@ Extension specifications (optional modules) are defined separately: - Phantom Extension - Forms Extension - Semantic Extension +- Legal Extension -### 1.7 Versioning +### 1.8 Versioning This specification uses semantic versioning (MAJOR.MINOR.PATCH): diff --git a/spec/core/03-content-blocks.md b/spec/core/03-content-blocks.md index 3a92dce..63388c4 100644 --- a/spec/core/03-content-blocks.md +++ b/spec/core/03-content-blocks.md @@ -1003,6 +1003,15 @@ Example: } ``` +### 5.1 Extension Mark Types + +Extensions MAY define additional mark types for use within text nodes. Unlike block types, extension marks are NOT required to use a namespace prefix — marks operate within the text node's `marks` array where the collision risk is lower. However, extensions MAY use a namespace prefix (e.g., `legal:cite`) when the unqualified name could cause confusion with marks from other extensions. + +Extension marks: +- SHOULD be documented in the extension specification +- MUST define their field table (type, required fields, optional fields) +- SHOULD avoid names that collide with core marks or marks from commonly-paired extensions + ## 6. Internationalization ### 6.1 Text Direction and Writing Mode diff --git a/spec/core/03a-anchors-and-references.md b/spec/core/03a-anchors-and-references.md index 0b692c8..6eea802 100644 --- a/spec/core/03a-anchors-and-references.md +++ b/spec/core/03a-anchors-and-references.md @@ -295,6 +295,8 @@ Extensions extend the base Person type with additional fields via schema composi All Person objects MUST include at minimum the `name` field. Extensions SHOULD include the base fields alongside their extension-specific fields. The naming distinction between "author" and "signer" is intentional to reflect the semantic difference in their contexts. +Extensions MAY add domain-specific identity fields to the Person object. The core `identifier` field remains available for persistent scholarly or decentralized identifiers. Extension-specific identity fields are additive — they do not replace `identifier`. For example, the collaboration extension adds `userId` for session-level identity, and the security extension adds `keyId` for cryptographic key association. A Person object MAY include both `identifier` and extension-specific fields simultaneously. + ## 10. Relationship to Extensions The anchor system is defined in the core specification but is primarily consumed by extensions: @@ -307,3 +309,16 @@ The anchor system is defined in the core specification but is primarily consumed | Semantic (`codex.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: + +| Mechanism | Extension | Use When | +|-----------|-----------|----------| +| `link` mark (with `#anchor` href) | Core | General-purpose internal links; hyperlink-style references | +| `semantic:ref` | Semantic | Scholarly cross-references (e.g., 'see Section 3', 'as shown in Figure 2') with automatic label generation | +| `presentation:reference` | Presentation | Layout-aware references that need presentation-specific formatting or page numbers | +| `academic:theoremRef` / `academic:equationRef` | Academic | References to theorems, equations, or other numbered academic elements | + +For simple internal links, use the core `link` mark. For documents requiring automatic numbering and label generation (e.g., 'Figure 3', 'Theorem 2.1'), use extension-specific reference marks. When multiple reference types apply, prefer the most semantically specific mechanism. diff --git a/spec/core/05-asset-embedding.md b/spec/core/05-asset-embedding.md index 449e238..6023f49 100644 --- a/spec/core/05-asset-embedding.md +++ b/spec/core/05-asset-embedding.md @@ -288,14 +288,24 @@ Embedded files are attachments that accompany the document but are not directly ### 6.3 Referencing Embedded Files -Embedded files can be referenced from content: +Embedded files can be referenced from content using a `paragraph` block with a `link` mark pointing to the embedded file: ```json { - "type": "attachment", - "ref": "assets/embeds/quarterly-data.xlsx", - "title": "Download source data", - "icon": "spreadsheet" + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Download source data", + "marks": [ + { + "type": "link", + "href": "assets/embeds/quarterly-data.xlsx", + "title": "Download source data" + } + ] + } + ] } ``` diff --git a/spec/core/06-document-hashing.md b/spec/core/06-document-hashing.md index ade9e12..602ab09 100644 --- a/spec/core/06-document-hashing.md +++ b/spec/core/06-document-hashing.md @@ -122,9 +122,12 @@ The following table summarizes what is included in and excluded from the documen | Security | No | Signatures reference the hash — not part of it | | Timestamps | No | Administrative metadata (`created`, `modified`) | | Provenance | No | Lineage tracking and derivation history | +| CRDT metadata | No | Transient synchronization state from collaboration extension | This boundary ensures that the document's identity represents its **semantic content** — what the document says — rather than how it appears or administrative metadata about it. +> **Note:** CRDT metadata added by the collaboration extension (`crdt` fields on content blocks) is excluded from the content hash. CRDT data represents transient synchronization state and MUST be stripped before computing the document hash. + ### 4.2 Canonical Content Structure ```json diff --git a/spec/core/08-metadata.md b/spec/core/08-metadata.md index 04c6826..39818e9 100644 --- a/spec/core/08-metadata.md +++ b/spec/core/08-metadata.md @@ -37,6 +37,8 @@ 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. + ```json { "version": "1.1", diff --git a/spec/extensions/README.md b/spec/extensions/README.md index c03f1c3..8d7d668 100644 --- a/spec/extensions/README.md +++ b/spec/extensions/README.md @@ -13,20 +13,22 @@ This directory contains specifications for Codex extensions. Each extension adds | [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 | ## Extension Compatibility Extensions are designed to work together. The following matrix shows compatibility between extensions: -| Extension | semantic | academic | forms | collaboration | security | phantoms | presentation | -|-----------|----------|----------|-------|---------------|----------|----------|--------------| -| semantic | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| academic | ✓ | - | △* | ✓ | ✓ | ✓ | ✓ | -| forms | ✓ | △* | - | ✓ | ✓ | ✓ | ✓ | -| collaboration | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | -| security | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | -| phantoms | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | -| presentation | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | +| Extension | semantic | academic | forms | collaboration | security | phantoms | presentation | legal | +|-----------|----------|----------|-------|---------------|----------|----------|--------------|-------| +| semantic | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| academic | ✓ | - | △* | ✓ | ✓ | ✓ | ✓ | ✓ | +| forms | ✓ | △* | - | ✓ | ✓ | ✓ | ✓ | ✓ | +| collaboration | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | +| security | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | +| phantoms | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | +| presentation | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | +| legal | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | **Legend:** - ✓ = Fully compatible @@ -69,6 +71,7 @@ Most extensions store data in dedicated directories: | collaboration | `collaboration/` | `comments.json`, `changes.json` | | security | `security/` | `signatures.json`, `encryption.json` | | phantoms | `phantoms/` | `clusters.json` | +| legal | `legal/` | `citations.json` | ### Shared Definitions diff --git a/spec/extensions/academic/README.md b/spec/extensions/academic/README.md index 30facb5..3e2cf1f 100644 --- a/spec/extensions/academic/README.md +++ b/spec/extensions/academic/README.md @@ -632,7 +632,7 @@ Location: `academic/numbering.json` "version": "0.1", "equations": { "style": "chapter.number", - "resetOn": "chapter" + "resetOn": "heading1" }, "theorems": { "style": "chapter.section.number", @@ -644,11 +644,11 @@ Location: `academic/numbering.json` }, "algorithms": { "style": "number", - "resetOn": "chapter" + "resetOn": "heading1" }, "exercises": { "style": "chapter.number", - "resetOn": "chapter" + "resetOn": "heading1" }, "customVariants": { "axiom": { @@ -690,10 +690,16 @@ This produces: Theorem 1, Lemma 2, Proposition 3, Theorem 4, etc. ### 10.3 Reset Triggers +The `resetOn` field accepts heading level identifiers: `heading1` through `heading6`, corresponding to the core `heading` block's `level` attribute. For example, `"heading1"` resets numbering at each level-1 heading. + | Reset On | Description | |----------|-------------| -| `chapter` | Reset at each chapter | -| `section` | Reset at each section | +| `heading1` | Reset at each level-1 heading | +| `heading2` | Reset at each level-2 heading | +| `heading3` | Reset at each level-3 heading | +| `heading4` | Reset at each level-4 heading | +| `heading5` | Reset at each level-5 heading | +| `heading6` | Reset at each level-6 heading | | `none` | Never reset (document-wide numbering) | ## 11. Examples diff --git a/spec/extensions/collaboration/README.md b/spec/extensions/collaboration/README.md index 276454f..ae54d08 100644 --- a/spec/extensions/collaboration/README.md +++ b/spec/extensions/collaboration/README.md @@ -64,6 +64,8 @@ Each content block can carry CRDT metadata: } ``` +**Hashing:** CRDT metadata (`crdt` fields on content blocks) MUST be stripped before computing the document content hash (see Core Specification, Section 6 — Document Hashing). CRDT metadata represents transient synchronization state, not document content. Implementations MUST materialize CRDT operations to plain content before hashing. + ### 3.4 Text CRDTs For rich text editing within blocks, integrate with text CRDTs: @@ -231,7 +233,27 @@ Location: `collaboration/comments.json` | `resolved` | boolean | No | Whether comment is resolved | | `replies` | array | No | Reply comments | -### 4.3a Author Object +### 4.3a Reply Object + +The `replies` array contains reply objects. Replies are flat — they do not nest (a reply cannot contain further replies). Replies do not have their own anchors; they inherit the anchor context of the parent comment. + +```json +{ + "id": "c1-r1", + "author": { "name": "Author", "email": "author@example.com" }, + "created": "2025-01-15T10:30:00Z", + "content": "Good point, I'll expand this section." +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `id` | string | Yes | Unique reply identifier | +| `author` | object | Yes | Reply author (see Author Object below) | +| `created` | string | Yes | ISO 8601 creation timestamp | +| `content` | string | Yes | Reply text content | + +### 4.3b Author Object The `author` field uses a consistent structure throughout the collaboration extension: @@ -359,7 +381,21 @@ Location: `collaboration/changes.json` } ``` -### 5.3 Change Types +### 5.3 Change Record Fields + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `id` | string | Yes | Unique change identifier | +| `type` | string | Yes | Change type (see Change Types below) | +| `anchor` | ContentAnchor | Yes | Anchor to the affected content (see Anchors and References spec) | +| `position` | object | No | Position for insert/move operations (e.g., `{ "after": "block-id" }`) | +| `before` | object | No | Content state before the change (for `modify` and `delete` types) | +| `after` | object | No | Content state after the change (for `modify` and `insert` types) | +| `author` | object | Yes | Change author (see Author Object in section 4.3a) | +| `timestamp` | string | Yes | ISO 8601 change timestamp | +| `status` | string | No | Change status: `"pending"`, `"accepted"`, or `"rejected"` (default: `"pending"`) | + +### 5.4 Change Types | Type | Description | |------|-------------| @@ -369,7 +405,7 @@ Location: `collaboration/changes.json` | `move` | Block moved to new position | | `format` | Formatting changed | -### 5.4 Accepting/Rejecting Changes +### 5.5 Accepting/Rejecting Changes Changes can be: - `pending` - Not yet reviewed diff --git a/spec/extensions/forms/README.md b/spec/extensions/forms/README.md index 1171285..2c3491b 100644 --- a/spec/extensions/forms/README.md +++ b/spec/extensions/forms/README.md @@ -30,6 +30,47 @@ The Forms Extension enables interactive form fields within documents: ## 3. Form Block Types +### 3.0a Form Container + +The `forms:form` block is a container that groups form fields together. It wraps child form field blocks and provides submission configuration. + +```json +{ + "type": "forms:form", + "id": "contact-form", + "action": "https://api.example.com/submit", + "method": "POST", + "encoding": "application/json", + "children": [...] +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"forms:form"` | +| `id` | string | No | Unique form identifier | +| `action` | string (URI) | No | Form submission endpoint/handler URL | +| `method` | string | No | HTTP method for submission. One of: `GET`, `POST`. Defaults to `"POST"`. | +| `encoding` | string | No | Form encoding type. Defaults to `"application/json"`. | +| `children` | array | Yes | Array of form field blocks and submit buttons | + +### 3.0b Submit Button + +The `forms:submit` block renders a submission button within a form. + +```json +{ + "type": "forms:submit", + "label": "Send Message" +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"forms:submit"` | +| `id` | string | No | Unique block identifier | +| `label` | string | No | Button text. Defaults to `"Submit"`. | + ### 3.1 Text Input ```json @@ -47,6 +88,21 @@ The Forms Extension enables interactive form fields within documents: } ``` +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"forms:textInput"` | +| `name` | string | Yes | Field name for form data | +| `label` | string | No | Display label | +| `placeholder` | string | No | Placeholder text | +| `required` | boolean | No | Whether field is required. Defaults to `false`. | +| `disabled` | boolean | No | Whether field is disabled. Defaults to `false`. | +| `inputType` | string | No | Input type. One of: `text`, `email`, `password`, `tel`, `number`. Defaults to `"text"`. | +| `maxLength` | integer | No | Maximum character length | +| `autocomplete` | string | No | Autocomplete hint | +| `validation` | object | No | Validation rules (see section 4) | +| `conditionalValidation` | object | No | Conditional validation rules (see section 4.3) | +| `fallback` | object | No | Fallback block for non-forms viewers (see section 7) | + ### 3.2 Text Area ```json @@ -59,6 +115,20 @@ The Forms Extension enables interactive form fields within documents: } ``` +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"forms:textArea"` | +| `name` | string | Yes | Field name for form data | +| `label` | string | No | Display label | +| `placeholder` | string | No | Placeholder text | +| `required` | boolean | No | Whether field is required. Defaults to `false`. | +| `disabled` | boolean | No | Whether field is disabled. Defaults to `false`. | +| `rows` | integer | No | Number of visible text rows. Defaults to `4`. | +| `maxLength` | integer | No | Maximum character length | +| `validation` | object | No | Validation rules (see section 4) | +| `conditionalValidation` | object | No | Conditional validation rules (see section 4.3) | +| `fallback` | object | No | Fallback block for non-forms viewers (see section 7) | + ### 3.3 Checkbox ```json @@ -70,6 +140,18 @@ The Forms Extension enables interactive form fields within documents: } ``` +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"forms:checkbox"` | +| `name` | string | Yes | Field name for form data | +| `label` | string | No | Display label | +| `required` | boolean | No | Whether field is required. Defaults to `false`. | +| `disabled` | boolean | No | Whether field is disabled. Defaults to `false`. | +| `defaultChecked` | boolean | No | Initial checked state. Defaults to `false`. | +| `validation` | object | No | Validation rules (see section 4) | +| `conditionalValidation` | object | No | Conditional validation rules (see section 4.3) | +| `fallback` | object | No | Fallback block for non-forms viewers (see section 7) | + ### 3.4 Radio Group ```json @@ -86,6 +168,19 @@ The Forms Extension enables interactive form fields within documents: } ``` +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"forms:radioGroup"` | +| `name` | string | Yes | Field name for form data | +| `label` | string | No | Display label | +| `required` | boolean | No | Whether field is required. Defaults to `false`. | +| `disabled` | boolean | No | Whether field is disabled. Defaults to `false`. | +| `options` | array | Yes | Array of option objects (`{ "value": string, "label": string, "disabled"?: boolean }`) | +| `defaultValue` | string | No | Default selected value | +| `validation` | object | No | Validation rules (see section 4) | +| `conditionalValidation` | object | No | Conditional validation rules (see section 4.3) | +| `fallback` | object | No | Fallback block for non-forms viewers (see section 7) | + ### 3.5 Dropdown ```json @@ -102,6 +197,21 @@ The Forms Extension enables interactive form fields within documents: } ``` +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"forms:dropdown"` | +| `name` | string | Yes | Field name for form data | +| `label` | string | No | Display label | +| `required` | boolean | No | Whether field is required. Defaults to `false`. | +| `disabled` | boolean | No | Whether field is disabled. Defaults to `false`. | +| `options` | array | Yes | Array of option objects (`{ "value": string, "label": string, "disabled"?: boolean }`) | +| `defaultValue` | string | No | Default selected value | +| `searchable` | boolean | No | Enable search/filter functionality. Defaults to `false`. | +| `multiple` | boolean | No | Allow multiple selections. Defaults to `false`. | +| `validation` | object | No | Validation rules (see section 4) | +| `conditionalValidation` | object | No | Conditional validation rules (see section 4.3) | +| `fallback` | object | No | Fallback block for non-forms viewers (see section 7) | + ### 3.6 Date Picker ```json @@ -115,6 +225,23 @@ The Forms Extension enables interactive form fields within documents: } ``` +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"forms:datePicker"` | +| `name` | string | Yes | Field name for form data | +| `label` | string | No | Display label | +| `required` | boolean | No | Whether field is required. Defaults to `false`. | +| `disabled` | boolean | No | Whether field is disabled. Defaults to `false`. | +| `format` | string | No | Date format pattern (e.g., `"YYYY-MM-DD"`). Defaults to `"YYYY-MM-DD"`. | +| `minDate` | string | No | Minimum selectable date (ISO 8601 date string or `"today"`) | +| `maxDate` | string | No | Maximum selectable date (ISO 8601 date string or `"today"`) | +| `includeTime` | boolean | No | Include time selection. Defaults to `false`. | +| `validation` | object | No | Validation rules (see section 4) | +| `conditionalValidation` | object | No | Conditional validation rules (see section 4.3) | +| `fallback` | object | No | Fallback block for non-forms viewers (see section 7) | + +The `minDate` and `maxDate` fields accept ISO 8601 date strings (e.g., `"2024-01-01"`). The special value `"today"` is also supported, representing the current date at the time of form rendering. No other relative date keywords are defined. + ### 3.7 Signature Field ```json @@ -126,6 +253,21 @@ The Forms Extension enables interactive form fields within documents: } ``` +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"forms:signature"` | +| `name` | string | Yes | Field name for form data | +| `label` | string | No | Display label | +| `required` | boolean | No | Whether field is required. Defaults to `false`. | +| `disabled` | boolean | No | Whether field is disabled. Defaults to `false`. | +| `width` | integer | No | Signature pad width in pixels (minimum 100) | +| `height` | integer | No | Signature pad height in pixels (minimum 50) | +| `validation` | object | No | Validation rules (see section 4) | +| `conditionalValidation` | object | No | Conditional validation rules (see section 4.3) | +| `fallback` | object | No | Fallback block for non-forms viewers (see section 7) | + +The `forms:signature` field captures visual/input signatures (e.g., drawn signatures or typed names) as part of form data. This is distinct from the security extension's cryptographic digital signatures, which provide tamper detection and non-repudiation. For documents requiring both visual and cryptographic signatures, use `forms:signature` for the user-facing input and the security extension for cryptographic verification. + ## 4. Validation ### 4.1 Built-in Validators diff --git a/spec/extensions/legal/README.md b/spec/extensions/legal/README.md index a9ed002..af28d99 100644 --- a/spec/extensions/legal/README.md +++ b/spec/extensions/legal/README.md @@ -30,6 +30,8 @@ The Legal Extension provides specialized blocks and marks for legal documents, i The `legal:cite` mark annotates text with legal citation information for automatic Table of Authorities generation. +> **Note:** The `legal:cite` mark uses the `legal:` namespace prefix to distinguish it from the semantic extension's `citation` mark, which serves a different purpose (scholarly citations vs. legal citations). See the core Content Blocks specification (Section 5) for the extension mark naming convention. + ### 3.1 Basic Usage ```json diff --git a/spec/extensions/phantoms/README.md b/spec/extensions/phantoms/README.md index cccf6e2..492d097 100644 --- a/spec/extensions/phantoms/README.md +++ b/spec/extensions/phantoms/README.md @@ -202,6 +202,10 @@ Connections between phantoms MUST satisfy the following rules: Implementations MUST validate connection targets when loading phantom data. Broken connection targets (referencing non-existent phantom IDs) indicate data corruption in frozen documents and partial construction in mutable documents. +### 4.8 Known Limitations + +Phantom content blocks exist in a separate namespace from the main document content. Anchors within phantom blocks reference other phantom blocks within the same cluster; they cannot directly reference blocks in the main document content tree. To associate phantom content with specific document locations, use the cluster's `anchor` field to attach the phantom cluster to a document position. Cross-referencing between phantom content and document blocks requires an intermediary cluster-level anchor. + ## 5. Hashing Boundary Phantoms are explicitly OUTSIDE the content hash boundary. The `phantoms/` directory has no `hash` field in the manifest reference. Adding, editing, or removing phantoms never changes the document ID or invalidates signatures. diff --git a/spec/extensions/presentation/README.md b/spec/extensions/presentation/README.md index e6ffce2..9a16fd5 100644 --- a/spec/extensions/presentation/README.md +++ b/spec/extensions/presentation/README.md @@ -13,6 +13,18 @@ The Presentation Extension provides advanced layout and styling capabilities bey - Master pages and templates - Advanced typography +### File Paths + +Presentation extension data is stored within the `presentation/` directory in the Codex archive: + +| File | Purpose | +|------|---------| +| `presentation/styles.json` | Typography, colors, and style definitions | +| `presentation/layout.json` | Master pages, templates, and layout rules | +| `presentation/toc.json` | Table of contents configuration | + +These files are referenced from the manifest's extension declaration. + ## 2. Extension Declaration ```json @@ -407,7 +419,9 @@ Span options: `column`, `page`, `spread` ### 7.2 Advanced Figure Numbering -The core `figure` block supports basic `numbering` ("auto", "none", or explicit number). This extension adds chapter-based numbering: +The core `figure` block supports basic `numbering` ("auto", "none", or explicit number). This extension adds chapter-based numbering via the `numberingConfig` field: + +The `numberingConfig` field provides extended numbering configuration beyond the core `numbering` field. The core `numbering` field (string or integer) controls basic numbering mode, while `numberingConfig` provides presentation-specific formatting options. ```json { @@ -419,7 +433,7 @@ The core `figure` block supports basic `numbering` ("auto", "none", or explicit "children": [{ "type": "text", "value": "Figure 1: System architecture" }] } ], - "numbering": { + "numberingConfig": { "style": "Figure #", "chapter": true } @@ -513,6 +527,8 @@ In content: ### 10.1 Footnote Definition +**Cross-Extension Note:** When both the presentation and semantic extensions are active, the semantic extension provides the canonical footnote model with separate `semantic:footnote` blocks for footnote content. In this configuration, the presentation extension's footnote marks control styling and positioning only — the inline `content` array on presentation footnote marks is not used. The inline `content` array is a simplified alternative for documents that use the presentation extension without the semantic extension. + In content: ```json diff --git a/spec/extensions/security/README.md b/spec/extensions/security/README.md index b9e828c..bd11773 100644 --- a/spec/extensions/security/README.md +++ b/spec/extensions/security/README.md @@ -266,6 +266,8 @@ Access control defines what actions different users can perform: } ``` +**Enforcement Model:** Access control lists (ACLs) defined in this extension are declarative and advisory. They express the document author's intended access restrictions but do not enforce them cryptographically on their own. For enforceable access control, combine ACLs with the encryption capabilities defined in this extension (see Section 4 — Encryption). When encryption is applied, ACLs serve as metadata for key distribution and access management. Without encryption, ACLs function as guidance for compliant implementations, which SHOULD respect the declared permissions. + ### 5.3 Permission Types | Permission | Description | diff --git a/spec/extensions/semantic/README.md b/spec/extensions/semantic/README.md index b97b67c..6a1c1ee 100644 --- a/spec/extensions/semantic/README.md +++ b/spec/extensions/semantic/README.md @@ -94,6 +94,7 @@ Location: `metadata/jsonld.json` | `type` | string | Yes | Always `"citation"` | | `refs` | array | Yes | Bibliography entry IDs to cite | | `locator` | string | No | Page, chapter, section, or other location reference (CSL-compatible) | +| `locatorType` | string | No | Type of locator (CSL-compatible). One of: `page`, `chapter`, `section`, `paragraph`, `line`, `verse`, `volume`, `issue`, `part`, `book`, `figure`, `table`, `note`, `opus`, `sub-verbo`. Defaults to `"page"` if omitted. | | `prefix` | string | No | Text to display before the citation (e.g., "see", "cf.") | | `suffix` | string | No | Text to display after the citation | | `suppressAuthor` | boolean | No | If true, omit the author name from the rendered citation | @@ -191,10 +192,14 @@ The bibliography block renders citations. It can reference an external bibliogra When `entries` is provided, each entry MAY include a `renderedText` field containing pre-rendered citation text from citeproc. This enables accurate display without requiring a CSL processor in the reader. +**Note:** Both CSL date formats are supported for the `issued` field: the short form (`{ "year": 2023 }`) and the standard form (`{ "date-parts": [[2023, 3, 15]] }`). Implementations MUST accept both formats. + ### 4.5 Footnotes Footnotes provide numbered references to supplementary content. The semantic extension defines the footnote content; the presentation extension (section 10) controls footnote styling and positioning. +> **Cross-Extension Note:** The semantic extension provides the canonical footnote model. When both the semantic and presentation extensions are active, the presentation extension's footnote styling applies to semantic footnote blocks. The presentation extension's inline `content` array on footnote marks is a simplified alternative for documents that do not use the semantic extension. See the Presentation extension for details. + #### 4.5.1 Footnote Mark Use a footnote mark on text to create a footnote reference: @@ -286,7 +291,8 @@ Footnote content is stored as a block, typically at the end of a section or docu | Field | Type | Required | Description | |-------|------|----------|-------------| | `type` | string | Yes | Always `"semantic:footnote"` | -| `number` | integer | Yes | Footnote number (must match mark) | +| `number` | integer | Conditional | Footnote number (must match mark). Required unless `symbol` is provided. | +| `symbol` | string | Conditional | Symbol-based footnote marker (must match mark). Required unless `number` is provided. | | `id` | string | No | Unique identifier (must match mark if present) | | `children` | array | Yes | Footnote content (paragraph blocks) | @@ -444,6 +450,16 @@ Internal references use Content Anchor URI syntax (see core Anchors and Referenc } ``` +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"semantic:term"` | +| `id` | string | No | Unique term identifier for cross-referencing | +| `term` | string | Yes | The term being defined | +| `definition` | string | Yes | Plain-text definition of the term | +| `see` | array | No | Related term IDs for cross-references | + +The `definition` field is intentionally a plain string for simplicity, portability, and use in search, indexing, and accessibility contexts. For definitions requiring rich formatting, place formatted content (e.g., paragraph blocks with inline marks) following the `semantic:term` block, with the `definition` field serving as a plain-text summary. + ### 8.2 Term Usage ```json @@ -458,6 +474,8 @@ Internal references use Content Anchor URI syntax (see core Anchors and Referenc ### 8.3 Glossary Block +The `semantic:glossary` block renders a collected glossary by aggregating all `semantic:term` blocks found in the document. Implementations MUST scan the document content for `semantic:term` blocks and include their definitions in the rendered glossary. + ```json { "type": "semantic:glossary", @@ -466,6 +484,12 @@ Internal references use Content Anchor URI syntax (see core Anchors and Referenc } ``` +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"semantic:glossary"` | +| `title` | string | No | Section heading for the glossary | +| `sort` | string | No | Sort order for terms. One of: `alphabetical` (sort by term name, A-Z), `appearance` (document order), `none` (no sorting applied). Defaults to implementation-defined behavior. | + ## 9. Provenance ### 9.1 Source Attribution