Specification

Encodings

A CKF package can be serialized in three formats. Pick by audience: Markdown for humans, YAML for diffing, JSON for machines.

When to use each

.ckf.md — readable by humans and crawlers; embeds YAML blocks per section. Best default for documentation, blogs, repos.
.ckf.yaml — single canonical YAML document; ideal for git diffs and CI.
.ckf.json — strictly typed, fastest to parse, mandatory when the consumer is a machine pipeline (RAG indexer, agent runtime, validator).

Same package, three faces

json

{
  "metadata": {
    "package_id": "spaced-retrieval-101",
    "protocol_version": "0.1",
    "source_type": "article"
  },
  "entities": [
    {
      "id": "ent_spaced_retrieval",
      "name": "Spaced retrieval",
      "type": "technique",
      "source_basis": "explicit"
    }
  ]
}

Markdown encoding

The Markdown form interleaves human-readable headings with YAML blocks. The headings are part of the format and must follow ## N. Section name:

yaml

# CKF — KNOWLEDGE CONTEXT PACKAGE

package_id: spaced-retrieval-101
protocol_version: 0.1
source_type: article

## 4. Entities

```yaml
entities:
  - id: ent_spaced_retrieval
    name: "Spaced retrieval"
    type: technique
    source_basis: explicit
```

Canonicalization

JSON: 2-space indent, sorted top-level keys following the schema order.
YAML: 2-space indent, no flow style, no anchors, line width 0 (one value per line).
Markdown: section headings in schema order; missing sections are still emitted as section: [] with a comment.