Understanding the Schema for the Capture Queue in Claude-Obsidian: A Technical Deep Dive

The capture queue in claude-obsidian follows the claude-obsidian.capture-queue.v1 JSON schema defined in claude_obsidian/capture.py, requiring three top-level fields—schema, revision, and entries—where each entry tracks source_path, dest_path, size, SHA-256 hash, mtime, and optional metadata to enable durable, content-addressed file ingestion.

The capture queue serves as the durable, content-addressed inbox that stores raw source files before they are ingested into the vault. In the AgriciDaniel/claude-obsidian repository, this queue is implemented as a validated JSON document that ensures data integrity across capture operations. Understanding the schema for the capture queue in claude-obsidian is essential for developers extending the capture workflow or debugging ingestion failures.

Top-Level Structure of the Capture Queue

The queue is governed by a strict contract enforced through a schema version string and a predictable JSON structure.

The QUEUE_SCHEMA Constant

In claude_obsidian/capture.py, the canonical schema identifier is defined as a module constant:

QUEUE_SCHEMA = "claude-obsidian.capture-queue.v1"

This string acts as a versioned contract. Any on-disk queue file must include this exact value in its schema field; otherwise, the validator raises a QUEUE_INVALID error with the message "capture queue must use claude‑obsidian.capture‑queue.v1".

Required Fields Overview

Every valid capture queue document must contain the following three top-level keys:

• schema: A string fixed to claude-obsidian.capture-queue.v1.
• revision: An integer representing a monotonically increasing version number that helps detect concurrent modifications.
• entries: A list of entry objects representing the ordered backlog of files awaiting ingestion.

Entry Object Schema and Fields

Each item within the entries array is a dictionary that captures the immutable metadata required to reconstruct a source file inside the vault.

Core Metadata Fields

An entry object must provide these five fields:

• source_path: String representing the original file location relative to the vault root.
• dest_path: String indicating the destination path inside the vault where the immutable copy will reside.
• size: Integer specifying the byte size of the captured file.
• hash: String containing the content-addressed SHA-256 hash of the file.
• mtime: Integer representing the Unix timestamp of the source file at the moment of capture.

Optional Provenance Data

Entries may also include an optional metadata field containing a dictionary of additional provenance data. This flexible key-value store allows the capture system to record context such as MIME types, extraction hints, or custom tags without breaking schema validation.

The complete entry structure looks like this in practice:

{
  "source_path": "inbox/example.pdf",
  "dest_path": ".raw/2024-03-01/example.pdf",
  "size": 124578,
  "hash": "a3f5c9e8d4b2...",
  "mtime": 1712489600,
  "metadata": {
    "type": "pdf",
    "title": "Example Document"
  }
}

Validation Rules and Error Handling

According to the AgriciDaniel/claude-obsidian source code in claude_obsidian/capture.py, the queue undergoes rigorous validation on every read and write operation to prevent corruption.

Schema Version Enforcement

Validators first check that q["schema"] matches QUEUE_SCHEMA. A mismatch immediately raises QUEUE_INVALID. The code also verifies that revision is an integer and that entries is a list; failure on either count produces the same QUEUE_INVALID error with the message "capture queue has invalid revision or entries".

Size and Entry Limits

To prevent unbounded growth, the implementation enforces configurable limits:

• Entry count: Validators check against MAX_QUEUE_ENTRIES. Exceeding this limit raises QUEUE_INVALID with "capture queue exceeds the ${MAX_QUEUE_ENTRIES}-entry limit".
• Byte size: The cumulative size of the queue is checked against MAX_QUEUE_BYTES. Violations trigger QUEUE_INVALID with "capture queue exceeds the ${MAX_QUEUE_BYTES}-byte limit".

Practical Implementation Examples

The following patterns demonstrate how to construct and manipulate the queue while respecting the schema.

Creating an Empty Queue

When initializing a new capture plan, the system generates a compliant empty queue:

empty_queue = {
    "schema": "claude-obsidian.capture-queue.v1",
    "revision": 0,
    "entries": []
}

Appending New Entries

To add a captured file to the queue, append a validated entry dictionary and increment the revision counter:

new_entry = {
    "source_path": "downloads/report.docx",
    "dest_path": ".raw/2024-06-15/report.docx",
    "size": 45200,
    "hash": "e3b0c44298fc1c149afbf4c8996fb924...",
    "mtime": 1718451200,
    "metadata": {"project": "Q3-Review"}
}

queue["entries"].append(new_entry)
queue["revision"] += 1

Validating Queue Integrity

Although the library handles validation internally, the logic follows this pattern as implemented in claude_obsidian/capture.py:

def validate_queue(q):
    if q.get("schema") != "claude-obsidian.capture-queue.v1":
        raise ValueError("QUEUE_INVALID: invalid schema version")
    if not isinstance(q.get("revision"), int):
        raise ValueError("QUEUE_INVALID: revision must be an integer")
    if not isinstance(q.get("entries"), list):
        raise ValueError("QUEUE_INVALID: entries must be a list")
    # Additional size and byte-limit checks follow...

Summary

• The capture queue schema is versioned under claude-obsidian.capture-queue.v1 and defined in claude_obsidian/capture.py.
• Three top-level fields are mandatory: schema, revision, and entries.
• Each entry must specify source_path, dest_path, size, hash, and mtime, with an optional metadata dictionary.
• Validation enforces schema version, data types, MAX_QUEUE_ENTRIES, and MAX_QUEUE_BYTES limits, raising QUEUE_INVALID errors on violations.
• The CLI commands in claude_obsidian/cli.py and unit tests in tests/test_capture.py exercise and enforce these schema rules.

Frequently Asked Questions

What is the exact schema version string for the claude-obsidian capture queue?

The schema version string is "claude-obsidian.capture-queue.v1". This constant is exported as QUEUE_SCHEMA from claude_obsidian/capture.py and serves as the sole valid identifier for the queue’s schema field.

What fields are required for each entry in the capture queue?

Every entry must include five required fields: source_path (original file location), dest_path (vault destination), size (bytes), hash (SHA-256 content hash), and mtime (Unix timestamp). An optional metadata dictionary can be appended to store additional provenance information.

How does claude-obsidian validate the capture queue before processing?

The validator, implemented in claude_obsidian/capture.py, checks that the schema matches QUEUE_SCHEMA, that revision is an integer, and that entries is a list. It also verifies that the queue does not exceed MAX_QUEUE_ENTRIES or MAX_QUEUE_BYTES. Any violation raises a QUEUE_INVALID error with a descriptive message.

What happens if the capture queue exceeds the configured size limits?

If the queue exceeds MAX_QUEUE_ENTRIES or MAX_QUEUE_BYTES, the validation logic raises QUEUE_INVALID with messages indicating which limit was breached. These guards prevent memory exhaustion and ensure the capture workflow remains performant when processing large backlogs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}