index.json Schema

index.json is the serialized knowledge graph for a knowledge space. Every build writes one. It sits next to the .indx archive and is also copied inside it. Its chunk shape matches the canonical shape used throughout the pipeline.

The file contains the document graph, the chunks, the resolved relations, build metadata, and aggregate stats. It holds everything except the vectors. Embeddings live separately under embeddings/, which keeps the graph small, diffable, and easy to read.

Where it lives

Running indx ./docs --out ./ai-ready writes index.json both as a top-level file in the output directory and as an entry inside the sealed archive:

ai-ready/
├── handbook.indx        # portable archive (contains a copy of index.json)
├── index.json           # the knowledge graph (this page)
├── chunks/              # per-chunk files (same chunk shape + resolved context)
└── embeddings/          # vectors + manifest (NOT in index.json)

The on-disk index.json and the copy inside the archive are identical. For the full container layout and manifest.json, see the .indx archive reference.

Pairs with the data models

Every object below is the JSON serialization of a Pydantic v2 model. For the in-memory types, fields, and the SDK surface, see Data Models.

Canonical chunk shape

A chunk is the retrievable unit of content. Every chunk records where it came from in source, what sits next to it in neighbors, and any typed edges it owns in relations. This exact shape appears in the chunks[] array and in the per-chunk files under chunks/.

{
  "id": "7bd8f3a4c91e0b52",
  "doc_id": "0e1f2a3b4c5d6e7f",
  "position": 1,
  "text": "Enterprise data is retained for 90 days…",
  "prev_id": "2f8c9b4a1d0e6c31",
  "next_id": "a1c9e33b72d45f00",
  "source": { "path": "policies/data/retention.pdf", "folder": "policies/data", "type": "policy" },
  "metadata": { "topics": ["retention", "compliance"], "summary": "90-day retention rule…" },
  "relations": [ { "src": "7bd8f3a4c91e0b52", "dst": "legal/gdpr.md", "type": "references", "score": 1.0 } ]
}

Field	Type	Notes
id	string	Stable deterministic id generated from document id and position.
doc_id	string	Parent document id.
position	integer	0-based position within the parent document.
text	string	The retrievable text payload.
source	object	Provenance: path, folder, type (see source).
prev_id / next_id	string or null	Adjacent chunk ids.
metadata	object	Enriched fields: topics (string[]), summary (string), tags (string[]).
relations	array	Outgoing typed edges from this chunk (see relation).

Embeddings are not inlined

The in-memory Chunk model carries an optional embedding vector, but index.json omits it. Vectors are written as little-endian float32 to embeddings/vectors.f32 with a companion manifest. This keeps the graph compact and lets the loader memory-map vectors on demand.

Top-level structure

The root of index.json is the serialized KnowledgeSpace. The required keys are version, root, documents, and chunks. Normal builds also include metadata, stats, and relations.

{
  "version": "1.0",
  "root": "/abs/path/docs",
  "metadata": {
    "tool_version": "indx 0.4.2",
    "created_at": "2026-06-06T12:00:00Z",
    "embedder": { "name": "text-embedding-3-small", "dim": 1536 },
    "config": { "...": "snapshot of resolved indx.toml" }
  },
  "stats": {
      "documents": 128, "chunks": 1042, "relations": 380,
      "embeddings": 1042, "embed_dim": 1536,
      "types": { "policy": 40, "guide": 30, "table": 12 }
  },
  "documents": [
    {
      "id": "0e1f2a3b4c5d6e7f",
      "path": "policies/data/retention.pdf",
      "lineage": ["policies", "policies/data"],
      "size_bytes": 42811,
      "doc_type": "policy",
      "topics": ["retention", "compliance"],
      "tags": ["gdpr", "data"],
      "summary": "Defines the 90-day retention rule…",
      "chunk_ids": ["2f8c9b4a1d0e6c31", "7bd8f3a4c91e0b52", "a1c9e33b72d45f00"],
      "references":    [ { "src": "0e1f2a3b4c5d6e7f", "dst": "legal/gdpr.md", "type": "references", "score": 1.0 } ],
      "referenced_by": [ { "src": "guides/onboarding.md", "dst": "0e1f2a3b4c5d6e7f", "type": "references", "score": 1.0 } ]
    }
  ],
  "chunks": [ /* objects in the canonical chunk shape above */ ],
  "relations": [ /* graph-level edges; an optional mirror of per-object edges */ ]
}

Top-level keys

Key	Type	Required	Description
version	string	yes	Knowledge-space schema version, e.g. "1.0".
root	string	yes	Absolute path of the walked directory or ZIP.
metadata	object	—	Build provenance: tool_version, created_at, embedder ({name, dim}), and a config snapshot of the resolved indx.toml. May also carry an errors array of non-fatal per-item failures.
stats	object	—	Aggregate counts (see stats).
documents	array	yes	The document graph (see document).
chunks	array	yes	All chunks in the canonical shape.
relations	array	—	Graph-level edges. An optional mirror of edges stored on individual chunks and documents.

document

A document is one source file, enriched. It carries its folder lineage, detected type, LLM-derived topics/tags/summary, the ids of the chunks it produced, and its references in both directions.

Field	Type	Notes
id	string	Stable deterministic id generated from the relative path.
path	string	Original path relative to root.
lineage	string[]	Folder ancestry, root→leaf.
size_bytes	integer	Source file size in bytes.
doc_type	string or null	Detected/enriched document type, e.g. policy.
topics	string[]	Enriched topics.
tags	string[]	Enriched tags.
summary	string	LLM-generated summary (may be absent).
chunk_ids	string[]	Chunks produced from this document, in order.
references	array	Outgoing references resolved in the Relate stage.
referenced_by	array	Incoming references (reverse edges).

Reading the graph

document.chunk_ids lets you walk from a file to its chunks, and each chunk.source.path walks back. references and referenced_by give you the cross-document citation graph in both directions without re-scanning.

JSON Schema

The following is the abridged schema (JSON Schema draft 2020-12). It defines $defs for source, relation, chunk, document, and stats, and is authoritative for the shapes above.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "indx index.json",
  "type": "object",
  "required": ["version", "root", "documents", "chunks"],
  "properties": {
    "version":  { "type": "string" },
    "root":     { "type": "string" },
    "metadata": { "type": "object" },
    "stats":    { "$ref": "#/$defs/stats" },
    "documents": { "type": "array", "items": { "$ref": "#/$defs/document" } },
    "chunks":    { "type": "array", "items": { "$ref": "#/$defs/chunk" } },
    "relations": { "type": "array", "items": { "$ref": "#/$defs/relation" } }
  },
  "$defs": {
    "source": {
      "type": "object",
      "required": ["path"],
      "properties": {
        "path":   { "type": "string" },
        "folder": { "type": "string" },
        "type":   { "type": ["string", "null"] }
      }
    },
    "relation": {
      "type": "object",
      "required": ["src", "dst", "type"],
      "properties": {
        "src":     { "type": "string" },
        "dst":     { "type": "string" },
        "type":    { "enum": ["sibling", "parent", "references", "continues", "duplicate-of"] },
        "score":   { "type": "number", "minimum": 0, "maximum": 1 }
      }
    },
    "chunk": {
      "type": "object",
      "required": ["id", "doc_id", "position", "text"],
      "properties": {
        "id":       { "type": "string" },
        "doc_id":   { "type": "string" },
        "position": { "type": "integer" },
        "text":     { "type": "string" },
        "prev_id":  { "type": ["string", "null"] },
        "next_id":  { "type": ["string", "null"] },
        "source":   { "$ref": "#/$defs/source" },
        "metadata": {
          "type": "object",
          "properties": {
            "topics":  { "type": "array", "items": { "type": "string" } },
            "summary": { "type": "string" },
            "tags":    { "type": "array", "items": { "type": "string" } }
          }
        },
        "relations": { "type": "array", "items": { "$ref": "#/$defs/relation" } }
      }
    },
    "document": {
      "type": "object",
      "required": ["id", "path"],
      "properties": {
        "id":           { "type": "string" },
        "path":         { "type": "string" },
        "lineage":      { "type": "array", "items": { "type": "string" } },
        "size_bytes":   { "type": "integer" },
        "doc_type":     { "type": ["string", "null"] },
        "topics":       { "type": "array", "items": { "type": "string" } },
        "tags":         { "type": "array", "items": { "type": "string" } },
        "summary":      { "type": "string" },
        "chunk_ids":    { "type": "array", "items": { "type": "string" } },
        "references":   { "type": "array", "items": { "$ref": "#/$defs/relation" } },
        "referenced_by":{ "type": "array", "items": { "$ref": "#/$defs/relation" } }
      }
    },
    "stats": {
      "type": "object",
      "properties": {
        "documents":  { "type": "integer" },
        "chunks":     { "type": "integer" },
        "relations":  { "type": "integer" },
        "embeddings": { "type": "integer" },
        "embed_dim":  { "type": "integer" },
        "types":      { "type": "object", "additionalProperties": { "type": "integer" } }
      }
    }
  }
}

source

Provenance for a chunk or parsed unit. path is required and is relative to the walked root. folder defaults to "", and type may be null until detection or enrichment fills it.

relation

A typed, directed edge. src, dst, and type are required. score is an optional confidence/similarity score in [0, 1] and defaults to 1.0.

type value	Meaning
sibling	Same folder / same logical group.
parent	Folder lineage / containment.
references	Outgoing citation, link, or mention.
continues	Next unit in a split sequence.
duplicate-of	Near or exact duplicate content.

Forward-compatible

New RelationType members and metadata keys are additive within a major version. Consumers must ignore unknown values rather than fail.

stats

The serialized SpaceStats — the same object returned by space.stats and emitted by indx inspect --json. embed_dim is the vector dimensionality (e.g. 1024 for bge-m3) and types is a document-count histogram keyed by detected type.

Per-chunk files (chunks/)

The per-chunk files under chunks/ (chunk_0000.json, chunk_0001.json, …) use the same canonical chunk shape shown above. The file names are sequential for convenient browsing; the chunk’s stable identity remains the id field inside each JSON object.

Related references

• .indx Archive Format — the ZIP container, manifest.json, and embeddings/ layout.
• Data Models — the Pydantic v2 types behind every object here.
• Protocols — the OutputWriter that serializes a KnowledgeSpace.
• Configuration Reference — what the metadata.config snapshot captures.