OCTX v0.1 Specification

Status: v0.1 design baseline. This document defines normative OCTX behavior; the machine-readable JSON Schemas, normative examples, and conformance tests should remain consistent with it.

1. Scope

Open Context (OCTX) publishes a versioned knowledge asset as an immutable, self-contained, verifiable Package. A Package may contain only OKF Markdown that people and Agents can read directly, or it may declare standard Capabilities that carry derived structures and vectors.

OCTX defines:

• Package, Asset, and Release identities.
• OKF-compatible knowledge documents.
• The normative payload file manifest.
• Logical content integrity.
• Capability, versioning, and extension boundaries.

OCTX does not define search, ranking, Agent protocols, database mappings, or index runtimes.

In this document, “MUST,” “MUST NOT,” and “MAY” indicate normative requirements, normative prohibitions, and optional implementation behavior respectively.

2. Conformance Layers

OCTX uses two independent layers:

1. OCTX format: the manifest, knowledge documents, identities, versions, and integrity rules that every implementation must understand.
2. Capability: a versioned standard data capability actually carried by the Package.

sag-structured/0.1 is one complete Capability that includes chunks, events, entities, and both relation types as a whole. An unknown Capability does not prevent a consumer from reading a valid OCTX Package; a consumer also cannot claim support for a Capability it cannot validate completely.

3. Package and Directory Structure

An .octx file is a ZIP / ZIP64 representation of the following logical directory tree:

example.octx
├── manifest.json
├── knowledge/
│   ├── index.md                    # optional OKF navigation
│   ├── log.md                      # optional OKF log
│   └── **/*.md                     # at least one Concept Document
├── data/
│   ├── chunks.jsonl                # sag-structured/0.1
│   ├── events.jsonl                # sag-structured/0.1
│   └── entities.jsonl              # sag-structured/0.1
├── relations/
│   ├── chunk-events.jsonl          # sag-structured/0.1
│   └── event-entities.jsonl        # sag-structured/0.1
├── vectors/
│   ├── config.json                 # vectors/0.1
│   ├── chunks.arrow
│   ├── events.arrow
│   └── entities.arrow
└── extensions/
    └── <namespace>/<major.minor>/...

Optional directories and files appear only when they are actually needed. Empty data/, relations/, vectors/, or extensions/ directories have no normative meaning.

The same logical tree may also exist as an OCTX Working Directory. The working directory is editable; a published .octx Package is immutable.

4. ZIP and Paths

A published file must satisfy the following requirements:

• ZIP filenames use UTF-8, and logical paths use Unicode NFC.
• Paths use POSIX / separators and are case-sensitive.
• Only relative file paths are allowed. Absolute paths, empty path segments, ., .., backslashes, and NUL are prohibited.
• Paths that collide after normalization are invalid.
• Only regular files are accepted; directory entries may be ignored.
• Symbolic links, hard links, device nodes, and other special files are prohibited.
• Encrypted entries are prohibited.
• v0.1 requires consumers to support only ZIP STORE and DEFLATE; ZIP64 must be available for large Packages.

Before writing, an unpacker must validate destination paths and detect name collisions on the target filesystem. It cannot overwrite files outside the destination directory or unrelated existing files. Consumers must enforce local resource limits such as maximum single-file size, total expanded size, entry count, and compression ratio.

5. Manifest

manifest.json is a UTF-8 JSON object. A minimal OCTX manifest is:

{
  "format": "octx",
  "format_version": "0.1",
  "asset": {
    "id": "019c1234-5678-7abc-8def-0123456789ab",
    "name": "SAG Technical Research"
  },
  "release": {
    "version": "1.0.0",
    "created_at": "2026-07-12T10:00:00Z",
    "package_digest": "sha256:..."
  },
  "files": [
    {
      "path": "knowledge/sag.md",
      "sha256": "..."
    }
  ]
}

5.1 Required Fields

files must include at least one Concept Document under knowledge/ that is neither index.md nor log.md.

5.2 File Manifest

• Every normalized files[].path must be unique.
• files[].sha256 is the SHA-256 of the raw file bytes, stored as 64 lowercase hexadecimal characters without a prefix.
• manifest.json is not included in files, avoiding a self-referential digest.
• Every required file for each declared standard Capability must be included in files.
• A Package is invalid if a listed file is missing, a digest does not match, or a path is duplicated.
• Safe regular ZIP files not listed in files are ignored. They are not imported, unpacked, included in the Package Digest, or preserved when repackaging.
• Unlisted dangerous paths, links, special files, or encrypted entries must still be rejected.

files defines the complete normative payload, not every unrelated byte present in the ZIP.

5.3 Optional Declarations

capabilities is a JSON object whose keys are names and whose values are version objects:

{
  "capabilities": {
    "sag-structured": {"version": "0.1"},
    "vectors": {"version": "0.1"}
  }
}

When there are no declarations, the field is omitted rather than written as an empty array or a Boolean marker.

A derived Asset may record its direct source in asset.derived_from:

{
  "asset_id": "019c1234-5678-7abc-8def-0123456789ab",
  "version": "1.0.0",
  "package_digest": "sha256:..."
}

A consumer that supports the current OCTX format version must allow unknown optional fields, read known fields, and preserve unknown fields when rewriting a Package losslessly. Unknown fields cannot change the semantics of known fields or independently satisfy a Capability.

This preservation obligation applies only to lossless repackaging with identical logical content. When creating a new Release or Derived Asset, an older tool must not automatically carry signatures, attestations, or other unknown manifest fields it does not understand into the new identity. A producer that understands their semantics must regenerate or explicitly declare them.

Duplicate keys in a JSON object are validation errors.

6. Knowledge Documents

knowledge/ must comply with Google Open Knowledge Format v0.1.

Every non-reserved Concept Document must:

• Be UTF-8 Markdown.
• Have parseable YAML frontmatter.
• Have a non-empty OKF type.
• Have a unique document_id in the octx namespace.

---
type: Reference
title: OCTX Overview
octx:
  document_id: 019c1234-5678-7abc-8def-0123456789ab
---

# OCTX Overview

Body text.

octx.document_id is a canonical lowercase UUIDv7 and remains stable across subsequent Releases of the same Asset. Moving or renaming a document does not change its ID; copying it as a new independent document creates a new ID.

index.md and log.md are reserved OKF files rather than OCTX Knowledge Documents, so they do not require octx.document_id. They must still follow the corresponding OKF structures.

Paths retain OKF navigation and Markdown-link semantics; document_id carries OCTX cross-version identity and derived-record references. Neither can replace the other.

7. Standard Capability Registry

Chunks, events, entities, and relations are not declared as separate Capabilities. If any standard SAG structure path appears, the complete sag-structured/0.1 Capability must be declared and all five structure files must be present. Producer-private data belongs in extensions/ and cannot occupy or reinterpret standard paths.

Each type of v0.1 standard JSONL file may appear at most once per Package and is not split or sharded by document. Future sharding must use a new Capability version.

8. Encoding

• manifest.json, other JSON, and JSONL use UTF-8 without a BOM.
• Every non-empty logical line in JSONL must be one complete JSON object. Empty lines are invalid; a final newline is optional.
• Markdown uses UTF-8. Producers should not write a BOM; readers must accept one optional UTF-8 BOM at the beginning of the file and remove it before parsing Markdown and YAML frontmatter.
• YAML must use safe parsing mode and must not execute custom object construction. YAML anchors and aliases are both prohibited to prevent resource amplification through alias expansion.
• Vectors use the Apache Arrow IPC file format; the vectors Capability defines the exact schema.

Per-file SHA-256 is computed over raw file bytes, so changes to line endings, JSON whitespace, or field order produce a new file digest. Consumers cannot format payloads automatically before validation.

9. Identity

OCTX assigns UUIDv7 identifiers to:

• Asset
• Knowledge Document
• Chunk
• Event
• Entity

All identifiers use lowercase hyphenated UUID strings without urn:uuid:, braces, or type prefixes. A Release has no separate UUID and is identified by asset.id + release.version + package_digest.

Record IDs represent semantic identity; digests represent content. Text, names, and file digests cannot replace record IDs.

10. Package Digest

Per-file digests and the Package Digest serve different purposes:

• files[].sha256 locates and validates a specific payload file.
• release.package_digest commits to the manifest semantics and the entire normative payload manifest.

Calculation steps:

1. Recompute and verify the SHA-256 of every file in manifest.files.
2. Copy the complete manifest and remove release.package_digest.
3. Sort the files array in the calculation copy by the UTF-8 bytes of normalized path in ascending order.
4. Encode the entire calculation copy using RFC 8785 JSON Canonicalization Scheme (JCS).
5. Compute SHA-256 over the result and store it as sha256:<lowercase-hex>.

File bytes are not concatenated again in step 5 because each per-file digest already commits to its contents. ZIP compression method, entry order, timestamps, and safe unlisted additional files do not affect the Package Digest.

A mismatch between a declared digest and the computed result is an integrity failure that cannot be bypassed. It is not a Release conflict that a user may confirm.

11. Versioning

OCTX versions the following independently:

• format_version: the OCTX format version, as major.minor.
• Capability version: the independent major.minor of each Capability.
• release.version: the knowledge-asset content version, using SemVer.

Before 1.0, each 0.x minor may change required behavior or field semantics, and consumers must explicitly support the exact version. After 1.x, a new minor within the same major may only add optional content or clarify semantics while remaining backward compatible.

Consumer behavior:

• A consumer that supports OCTX 0.1 reads known content and preserves unknown optional fields.
• An unknown Capability does not prevent reading OCTX documents.
• An unsupported OCTX format version must be rejected explicitly rather than interpreted speculatively.

12. Private Extensions

Private extension paths use:

extensions/<reverse-domain-namespace>/<major.minor>/...

For example:

extensions/com.zleap.sag/1.0/data.jsonl

Extension files must be listed in manifest.files and included in the Package Digest. An unknown consumer may ignore extension semantics, but must preserve extension bytes exactly during a lossless round trip. A private extension cannot replace a standard Capability.

13. OCTX Validation Results

Any of the following makes an OCTX Package invalid:

• The manifest is missing, cannot be parsed, or lacks a required field.
• format / format_version is unsupported.
• There is no Concept Document.
• Concept frontmatter, type, or octx.document_id is invalid.
• Asset or document IDs are duplicated or use non-canonical encoding.
• A listed file is missing; a path is illegal; or a per-file digest or Package Digest does not match.
• A ZIP safety rule is violated.

An invalid OCTX Package must not be installed as the original Asset. After an explicit user choice, a tool may extract still-readable Markdown and create a derived asset with new Asset and document identities.

14. Non-Goals

OCTX v0.1 does not define:

• Database snapshots or database primary keys.
• Incremental synchronization, deletion markers, live updates, or remote payloads.
• Pre-conversion attachments such as PDF, DOCX, images, or web-page snapshots.
• Digital signatures, publisher identity, or roots of trust.
• Encrypted ZIP files.
• Search APIs, retrieval algorithms, ranking scores, Agent protocols, or result formats.