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

> Explore the claude-obsidian capture queue schema, schema version claude-obsidian capture queue v1. Learn about its essential fields: schema, revision, and entries for efficient file ingestion.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: deep-dive
- Published: 2026-08-29

---

**The capture queue in claude-obsidian follows the `claude-obsidian.capture-queue.v1` JSON schema defined in [`claude_obsidian/capture.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/capture.py), the canonical schema identifier is defined as a module constant:

```python
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:

```json
{
  "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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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:

```python
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:

```python
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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/capture.py):

```python
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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/cli.py) and unit tests in [`tests/test_capture.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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.