# Bundle Schema for Transactions in Claude-Obsidian: Complete JSON Reference

> Explore the bundle schema for transactions in claude-obsidian. Understand the JSON contract for atomic vault changes, versioning, and SHA-256 verification. Get the complete reference.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: api-reference
- Published: 2026-08-28

---

**The bundle schema for transactions in claude-obsidian is a versioned JSON contract that defines how atomic vault changes are structured, validated, and applied, requiring mandatory fields for versioning, operations with SHA-256 verification, and optional metadata for audit trails.**

The **claude-obsidian** repository provides a transactional interface for programmatically managing Obsidian vault content. Every automated modification—whether creating a note, updating metadata, or deleting a ledger—must be packaged according to the **bundle schema for transactions in claude-obsidian** to ensure atomicity and reproducibility. This schema dictates the exact JSON structure that the transaction engine validates before executing any knowledge changes against the vault.

## Core Schema Structure

The schema follows the strict version identifier **`claude-obsidian.transaction.v1`** and consists of four top-level fields that govern how bundles are processed. According to the source code in [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py), the `TransactionBundle` class enforces this structure during instantiation, serialization, and validation.

### The version Field

Every bundle must declare its schema compatibility using the **`version`** string. This mandatory field must exactly match `"claude-obsidian.transaction.v1"` to be accepted by the transaction engine. The version identifier ensures that outdated or incompatible bundle formats are rejected before any vault modifications occur, maintaining backward compatibility as the API evolves.

### The operations Array

The **`operations`** field is a JSON array containing the atomic actions to be applied. Each operation object requires three specific sub-fields:

- **`target`**: The relative vault path (e.g., `"wiki/notes/example.md"`) that the operation modifies.
- **`expected_sha256`**: The SHA-256 hash of the file's current content. This hash acts as a concurrency check; if the target file has changed since bundle creation, the transaction aborts to prevent race conditions.
- **`draft`**: The new content to write to the target. Setting this value to `null` explicitly signals a deletion operation.

### The metadata Object

While optional, the **`metadata`** object stores contextual information essential for audit trails and debugging. Common keys implemented in the schema include:

- **`author`**: The identifier of the agent or user creating the bundle.
- **`timestamp`**: ISO-8601 formatted creation time (e.g., `"2026-08-28T14:35:00Z"`).
- **`description`**: A human-readable explanation of the transaction's purpose and scope.

### The conflict_resolution Object

To handle scenarios where the `expected_sha256` check fails, the optional **`conflict_resolution`** field specifies the engine's failure behavior. The **`strategy`** key accepts string values such as `"abort"` (the default) to cancel the entire transaction, or `"force"` to apply changes regardless of content mismatches, depending on the vault's consistency requirements.

## Source Code Implementation

The bundle schema is implemented in **[`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py)**, which defines the `TransactionBundle` dataclass or Pydantic model with strict field validation. This module also exposes the **`apply_bundle()`** function, the primary entry point for executing validated bundles atomically against the vault filesystem.

Human-readable documentation describing the transaction lifecycle, field constraints, and error handling appears in **[`skills/wiki/references/operation-transactions.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/skills/wiki/references/operation-transactions.md)**. Unit tests verifying schema compliance and edge cases are located in **[`tests/test_transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/tests/test_transaction.py)**.

## Creating and Applying Transaction Bundles

Developers interact with the schema through the Python API provided by the transaction module.

### Creating a Valid Bundle

The following example constructs a bundle with multiple operations, including content creation and deletion:

```python
from claude_obsidian.transaction import TransactionBundle

bundle = TransactionBundle(
    version="claude-obsidian.transaction.v1",
    operations=[
        {
            "target": "wiki/notes/example.md",
            "expected_sha256": "d41d8cd98f00b204e9800998ecf8427e",
            "draft": "# Example\n\nNew content for the note."

        },
        {
            "target": "wiki/meta/ledgers/example.json",
            "expected_sha256": "a3f5c9e2e6c93b5a2c6d1e9f1d4b7a2f",
            "draft": None  # Indicates deletion

        },
    ],
    metadata={
        "author": "auto-research-agent",
        "timestamp": "2026-08-28T14:35:00Z",
        "description": "Add example note and clean up ledger."
    },
    conflict_resolution={"strategy": "abort"},
)

json_blob = bundle.to_json()

```

### Applying a Bundle

Once serialized, bundles are executed using the `apply_bundle` function, which validates the schema and applies changes atomically:

```python
from claude_obsidian.transaction import apply_bundle

result = apply_bundle(json_blob)
if result.success:
    print("Transaction applied successfully.")
else:
    print("Transaction failed:", result.error)

```

### Validating Schema Compliance

The test suite in **[`tests/test_transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/tests/test_transaction.py)** ensures that malformed bundles trigger validation errors before touching the vault:

```python
def test_bundle_schema_validation():
    bundle = {
        "version": "claude-obsidian.transaction.v1",
        "operations": [],
    }
    # Missing required fields raise ValidationError

    with pytest.raises(ValidationError):
        TransactionBundle.from_dict(bundle)

```

## Summary

- The **bundle schema** requires the version identifier `claude-obsidian.transaction.v1` for all transactions processed by the engine.
- Each **operation** must specify a target path, an `expected_sha256` hash for optimistic concurrency control, and draft content (or `null` for deletions).
- **Metadata** fields provide optional but recommended audit context including author identity, timestamps, and descriptions.
- The **`TransactionBundle`** class in [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py) enforces schema compliance, while **`apply_bundle()`** executes validated bundles atomically, ensuring all operations succeed or fail together.

## Frequently Asked Questions

### What is the current schema version for claude-obsidian transactions?

The current version is **`claude-obsidian.transaction.v1`**, which must appear in the mandatory `version` field of every transaction bundle. This identifier allows the transaction engine to reject incompatible legacy formats and maintain predictable behavior as the codebase evolves.

### How does the bundle schema prevent race conditions?

The schema implements **optimistic concurrency control** through the `expected_sha256` field. Before applying any operation, the engine calculates the current SHA-256 hash of the target file and compares it to the expected value. If the hashes differ—indicating another process modified the file—the engine aborts the transaction or executes the specified conflict resolution strategy, preventing silent overwrites.

### Where is the bundle schema defined in the source code?

The schema definition, validation logic, and `TransactionBundle` class reside in **[`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py)**. Detailed human-readable specifications appear in **[`skills/wiki/references/operation-transactions.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/skills/wiki/references/operation-transactions.md)**, while **[`tests/test_transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/tests/test_transaction.py)** contains the validation test suite ensuring schema integrity across updates.

### Can a single transaction bundle modify multiple files?

Yes, the **`operations`** field is a JSON array that supports any number of atomic actions. A single bundle can create a note, update a metadata ledger, and delete a temporary cache file simultaneously. The engine treats the entire operations list as an atomic unit, guaranteeing that either all changes persist to the vault or none do, maintaining filesystem consistency.