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

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, 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, 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. Unit tests verifying schema compliance and edge cases are located in 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:

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:

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 ensures that malformed bundles trigger validation errors before touching the vault:

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 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. Detailed human-readable specifications appear in skills/wiki/references/operation-transactions.md, while 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.

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