# Claim Ledger in claude-obsidian: Data Structure, Validation, and Evidence Tracking

> Discover how the claim ledger in claude-obsidian stores falsifiable statements, risk classifications, and evidence for auditable knowledge management in Obsidian.

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

---

**The claim ledger in claude-obsidian is a JSON document stored at [`wiki/meta/ledgers/claim-ledger.json`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/wiki/meta/ledgers/claim-ledger.json) that records falsifiable statements, their risk classifications, assessment statuses, and supporting evidence to enable auditable knowledge management within Obsidian vaults.**

The claude-obsidian project implements a rigorous knowledge management system that tracks the provenance and evaluation of claims extracted from vault content. At the center of this system is the **claim ledger**, which captures structured representations of verifiable assertions alongside their review metadata and evidentiary links. This ledger works in tandem with the source ledger to create a traceable chain of knowledge validation according to the schema defined in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py).

## Core Data Fields in the Claim Ledger

Each claim entry uses a safe identifier prefixed with **clm-**, validated by the `_safe_ledger_id` function at line 44 of [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py). The entry contains nine distinct fields that record the claim's content, context, and evidentiary support.

### Falsifiable Statement and Risk Classification

The **text** field stores the actual falsifiable statement as a non-empty UTF-8 string, validated at lines 49-55. The **risk** field indicates potential impact as either `normal` or `high` (lines 55-58), which triggers additional validation requirements for high-risk entries.

### Assessment Status and Confidence Levels

Reviewers record their judgment in the **assessment** field, which accepts one of five enumerated values: `accepted`, `provisional`, `contested`, `unsupported`, or `deprecated` (lines 59-62). The **confidence** field complements this assessment with levels of `high`, `medium`, `low`, or `unknown` (lines 61-64).

### Vault Location Tracking

The **location** object specifies where the claim appears in the vault, containing:

- **path**: A canonical wiki file path starting with `wiki/...` (validated at lines 64-81)
- **anchor**: An optional reference to a heading or block ID using `^id` format or heading text

### Evidence Arrays and Temporal Metadata

The **reviewed_at** field stores an ISO date (validated at lines 30-34), while **notes** provides optional UTF-8 commentary (lines 46-50). Claims can reference superseded entries via **supersedes** (lines 51-53). Most critically, the **evidence** array links claims to sources, with each object containing:

- **source_id**: A safe source identifier with `src-...` prefix
- **relation**: One of `supports`, `contradicts`, or `context`
- **locator**: Optional human-readable location within the source

## Validation Constraints and Business Rules

The `validate_claim_ledger` function (starting at line 101 in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py)) enforces strict integrity constraints beyond basic schema validation.

### Path and Anchor Verification

Location paths must be vault-relative wiki paths without absolute components or parent directory traversal (`..`). The `_markdown_anchor_sets` function verifies that anchors reference existing headings or block IDs within the target page.

### Evidence Integrity Checks

Evidence objects must reference existing source IDs from the source ledger and use only allowed `EVIDENCE_RELATIONS` values. The system specifically validates that evidence links point to real sources rather than orphaned references.

### High-Risk Claim Requirements

High-risk accepted claims face additional scrutiny. The `_independent_group_count` validation ensures these claims have at least two independent supporting sources. Additionally, accepted claims require at least one fresh active supporting source that predates the claim's review date, preventing circular or post-dated justifications.

## Working with the Claim Ledger

The ledger follows the schema identifier defined by `CLAIM_SCHEMA` (line 22) and resides at the path specified by `CLAIM_PATH` (line 24). All timestamps use ISO-8601 UTC format, with a top-level `generated_at` field tracking ledger creation time.

### Creating a Claim Entry

Here is a complete example of a valid claim ledger entry:

```python
claim = {
    "schema": "claude-obsidian.claim-ledger.v1",
    "generated_at": "2026-08-28T12:00:00Z",
    "claims": {
        "clm-abc123def456": {
            "text": "Artificial intelligence can outperform humans in creative writing.",
            "risk": "high",
            "assessment": "accepted",
            "confidence": "high",
            "location": {
                "path": "wiki/ai/creative-writing.md",
                "anchor": "Artificial‑Intelligence‑Creativity"
            },
            "reviewed_at": "2026-08-27",
            "notes": "Multiple peer‑reviewed studies support this claim.",
            "supersedes": None,
            "evidence": [
                {
                    "source_id": "src-9f8e7d6c5b4a3",
                    "relation": "supports",
                    "locator": "Section 2.2"
                },
                {
                    "source_id": "src-1a2b3c4d5e6f7",
                    "relation": "supports",
                    "locator": None
                }
            ]
        }
    }
}

```

### Validating Against the Source Ledger

To validate a claim ledger, pass it to `validate_claim_ledger` along with the source ledger:

```python
from claude_obsidian.ledgers import validate_claim_ledger, empty_source_ledger

source_ledger = empty_source_ledger()
errors = validate_claim_ledger(claim, source_ledger)

if errors:
    for err in errors:
        print(f"{err['path']}: {err['message']}")
else:
    print("Claim ledger is valid.")

```

## Summary

- The **claim ledger** in claude-obsidian resides at [`wiki/meta/ledgers/claim-ledger.json`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/wiki/meta/ledgers/claim-ledger.json) and stores falsifiable statements with full provenance tracking.
- Each claim uses a **clm-** prefixed ID and contains fields for text, risk level, assessment status, confidence, vault location, review date, and linked evidence.
- **High-risk accepted claims** require at least two independent supporting sources and one fresh active source predating the review date.
- The `validate_claim_ledger` function enforces constraints on path formats, anchor existence, evidence relations, and temporal consistency.
- All timestamps use ISO-8601 UTC format, with a top-level `generated_at` field tracking ledger creation time.

## Frequently Asked Questions

### What is the file path for the claim ledger in claude-obsidian?

The claim ledger is stored at [`wiki/meta/ledgers/claim-ledger.json`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/wiki/meta/ledgers/claim-ledger.json) within the Obsidian vault. This path is defined by the `CLAIM_PATH` constant in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) at line 24. The file uses JSON format with a schema version identifier specified by `CLAIM_SCHEMA` at line 22.

### What are the valid assessment statuses for a claim?

According to the validation logic in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) (lines 59-62), the **assessment** field accepts five values: `accepted` (fully validated), `provisional` (pending further verification), `contested` (disputed by evidence), `unsupported` (lacking evidence), and `deprecated` (superseded by newer claims). Each status affects how the claim is treated during vault compilation and cross-referencing.

### How does claude-obsidian validate evidence links in the claim ledger?

The `validate_claim_ledger` function checks that every **source_id** in the evidence array references an existing entry in the source ledger. Evidence must use one of the allowed `EVIDENCE_RELATIONS` values: `supports`, `contradicts`, or `context`. For high-risk accepted claims, the system additionally verifies that at least two independent sources provide support using the `_independent_group_count` validation implemented within the ledger validation logic.

### Can a claim reference a specific location within an Obsidian note?

Yes. The **location** object contains a **path** field specifying the wiki file (e.g., [`wiki/ai/creative-writing.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/wiki/ai/creative-writing.md)) and an optional **anchor** field that references specific headings or block IDs. The validation function `_markdown_anchor_sets` verifies that these anchors exist in the target file, ensuring claims can be precisely located within the vault structure (validation logic at lines 64-81).