A universal, representation-independent foundation for knowledge.
CKS is an open specification that defines how knowledge can be represented, validated, exchanged, and evolved independently of programming languages, document formats, databases, or AI systems.
Rather than introducing yet another serialization format or programming language, CKS defines a canonical semantic layer shared by humans, software, and artificial intelligence.
Today the same knowledge exists simultaneously in many incompatible forms:
- documents
- databases
- JSON
- XML
- source code
- knowledge graphs
- ontologies
- AI prompts
- APIs
Each representation describes the same underlying knowledge differently.
CKS separates knowledge itself from every concrete representation.
Knowledge
│
▼
Canonical Knowledge Structure (CKS)
│
┌────┼───────────────┐
▼ ▼ ▼
JSON Python Database Natural Language
Representations may change.
Canonical knowledge remains the same.
CKS is founded on four simple principles.
Knowledge is not JSON.
Knowledge is not a PDF.
Knowledge is not source code.
Representations are temporary.
Knowledge is not.
Meaning is preserved by canonical structure rather than by syntax.
Different representations may express the same canonical structure.
Validation.
Serialization.
Comparison.
Evolution.
Inspection.
These are operations on knowledge—not on files, databases, or programming languages.
The CKS ecosystem consists of implementation-independent specifications.
| Specification | Purpose |
|---|---|
| CKS-000 | Foundations and terminology |
| CKS-001 | Canonical semantic model |
| CKS-002 | Knowledge construction |
| CKS-003 | Canonical serialization |
| CKS-004 | Structure evolution |
| CKS-005 | Validation |
| CKS-006 | Reference Engine |
| CKS-007 | Canonical Knowledge Interface |
| CKS-008 | Conformance |
| CKS-009 | Reference Knowledge Corpus |
| CKS-B001 | Python Reference Implementation |
The current Python reference implementation provides:
- Immutable Canonical Knowledge Objects
- Canonical Relations
- Immutable Knowledge Structures
- Canonical JSON Serialization
- Deterministic Validation Pipeline
- Diagnostic System
- Reference Engine
- Canonical Public API
- Structural Comparison
- Projection
- Extraction
- Inspection
- Conformance Test Suite
- Command-Line Interface (validate, parse, inspect, evolve, schema, plugin)
- Structural Evolution (Genesis/Decay operators)
- Configurable Severity Thresholds
- HTML and Markdown Report Formatters
- Batch Validation (multiple files)
- JSON‑LD, Turtle, RDF/XML Import (via
cks convert) - JSON‑LD, Turtle, RDF/XML Export (via
cks export) - Strict Plugin Validation (
--strict) - Static Type Checking (mypy)
CKS is designed to be:
- deterministic
- immutable
- observationally pure
- representation-independent
- implementation-independent
- language-independent
- suitable for formal verification
This repository contains the official Python Reference Implementation of the Canonical Knowledge Structure specifications.
Currently implemented:
- ✅ Canonical Knowledge Objects
- ✅ Canonical Relations
- ✅ Canonical Knowledge Structures
- ✅ Canonical Serialization
- ✅ Validation Pipeline
- ✅ Diagnostic System
- ✅ Reference Engine
- ✅ Canonical Public Interface
- ✅ Command-Line Interface
- ✅ Structural Evolution (CKS‑004)
- ✅ Reference Knowledge Corpus
- ✅ Conformance Test Suite (114 tests)
- ✅ PyPI Publication
- ✅ Import/Export Adapters (JSON‑LD, Turtle, RDF/XML)
- ✅ Modular CLI (commands refactored into separate handlers)
- ✅ Contract Documentation (
docs/contracts.md) - ✅ Static Type Checking (mypy)
Planned:
- Constraint Libraries (additional built‑in constraints)
- Additional language implementations (Rust, TypeScript)
From PyPI:
pip install canonical-ksOr from source:
git clone https://github.com/Deus-corp/CKS.git
cd CKS
pip install -e .from cks import (
construct,
validate,
serialize,
)
from cks.core import (
KnowledgeObject,
ObjectIdentity,
)
obj = KnowledgeObject(
identity=ObjectIdentity(
id="obj-1",
type="Definition",
name="Knowledge",
)
)
structure = construct([obj])
result = validate(structure)
print(result.is_valid)
print(serialize(structure))Or use the command line:
# Validate a knowledge structure
cks validate examples/corpus/valid_theory_example.json
# Evolve a structure by adding an object
cks evolve examples/corpus/valid_theory_example.json examples/corpus/evolve_add.jsonOr convert between formats:
# Convert JSON‑LD to CKS
cks convert examples/corpus/person.jsonld --format json-ld --output person.cks.json
# Export CKS to Turtle
cks export examples/corpus/valid_theory_example.json --format turtle --output theory.ttlRun the complete conformance suite:
python -m pytest -vCurrent status:
- 114 tests
- all passing
The test suite verifies:
- deterministic behaviour
- immutability
- observational purity
- canonical serialization
- validation correctness
- public API conformance
- structural equivalence
The complete specification is published separately.
Core specifications:
- CKS-000 — Foundations
- CKS-001 — Core Specification
- CKS-002 — Construction
- CKS-003 — Serialization
- CKS-004 — Evolution
- CKS-005 — Validator
- CKS-006 — Reference Engine
- CKS-007 — Canonical Knowledge Interface
- CKS-008 — Conformance
DOI:
Current implementation status:
| Component | Status |
|---|---|
| Core Model | ✅ Complete |
| Serialization | ✅ Complete |
| Validation | ✅ Complete |
| Reference Engine | ✅ Complete |
| Public API | ✅ Complete |
| Test Suite | ✅ Passing |
| CLI | ✅ Complete |
| Structural Evolution | ✅ Complete |
| Advanced Validation | ✅ Complete |
| Import/Export Adapters | ✅ Complete |
| Modular CLI | ✅ Complete |
| Contract Documentation | ✅ Complete |
| Static Type Checking | ✅ Complete |
The current implementation serves as the reference implementation of the existing CKS specifications.
Future work focuses primarily on expanding the specification rather than redesigning the implemented components.
CKS aims to establish a universal semantic foundation for knowledge exchange between:
- humans
- software
- databases
- distributed systems
- artificial intelligence
through a single canonical representation of knowledge that is independent of every concrete implementation.
MIT