Skip to content

Add missing schemas, extension examples, and documentation improvements#17

Merged
gvonness-apolitical merged 1 commit intomainfrom
feature/spec-cleanup-consistency
Feb 1, 2026
Merged

Add missing schemas, extension examples, and documentation improvements#17
gvonness-apolitical merged 1 commit intomainfrom
feature/spec-cleanup-consistency

Conversation

@gvonness-apolitical
Copy link
Collaborator

Summary

This PR addresses consistency and completeness issues in the Codex specification:

  • 3 new schema files for extensions that had README docs but no schemas (collaboration, forms, security)
  • 5 new example documents demonstrating extension usage (academic, semantic, forms, collaboration, phantoms)
  • Standardized Person/author objects across extensions using schema composition
  • Extension marks integration into core content schema for strict validation
  • Documentation improvements including terminology glossary and compatibility matrix

Changes by Phase

Phase 1: Missing Schema Files

  • schemas/collaboration.schema.json - Comments, changes, CRDT metadata
  • schemas/forms.schema.json - Form blocks, validation, conditional validation
  • schemas/security.schema.json - Signatures, encryption, access control

Phase 2: Extension Marks Integration

  • Updated content.schema.json to reference semantic/academic extension marks
  • Updated validation scripts to handle schema dependencies

Phase 3: Author/Person Standardization

  • Added base person definition with identifier field to anchor.schema.json
  • Updated phantoms, collaboration, security schemas to use allOf composition
  • Added ORCID recommendation for academic documents

Phase 4: Extension Examples

  • examples/academic-document/ - Theorems, proofs, exercises, algorithms
  • examples/semantic-document/ - Citations, footnotes, glossary, entities
  • examples/forms-document/ - Comprehensive form with conditional validation
  • examples/collaboration-document/ - Comments, suggestions, track changes
  • examples/phantoms-document/ - Multi-scope annotation clusters

Phase 5: Documentation

  • Added terminology glossary to spec/core/03a-anchors-and-references.md
  • Created spec/extensions/README.md with compatibility matrix
  • Documented extension policies in schemas/README.md
  • Added conditional validation docs to forms extension
  • Added CI and license badges to root README

Test plan

  • All 15 schemas compile successfully
  • All 8 example documents validate against schemas
  • npm test passes

Phase 1: Missing Schema Files
- Create collaboration.schema.json with comments, changes, CRDT metadata
- Create forms.schema.json with all form block types and validation
- Create security.schema.json with signatures, encryption, access control

Phase 2: Extension Marks Integration
- Integrate semantic and academic marks into content.schema.json
- Update validation scripts for schema dependencies

Phase 3: Author/Person Standardization
- Add base Person definition with identifier field to anchor.schema.json
- Update extension schemas to use allOf composition
- Add ORCID recommendation for academic documents

Phase 4: Extension Examples
- Create academic-document/ with theorems, proofs, exercises, algorithms
- Create semantic-document/ with citations, footnotes, glossary
- Create forms-document/ with comprehensive form validation examples
- Create collaboration-document/ with comments, suggestions, track changes
- Create phantoms-document/ with multi-scope annotation clusters

Phase 5: Documentation
- Add terminology glossary and Person docs to anchors spec
- Create spec/extensions/README.md with compatibility matrix
- Document extension policies in schemas/README.md
- Add conditional validation docs to forms extension
- Add CI and license badges to README
@gvonness-apolitical gvonness-apolitical merged commit e3212e0 into main Feb 1, 2026
2 checks passed
@gvonness-apolitical gvonness-apolitical deleted the feature/spec-cleanup-consistency branch February 1, 2026 04:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant