> ## Documentation Index > Fetch the complete documentation index at: https://docs.tallychannel.com/llms.txt > Use this file to discover all available pages before exploring further. # Evidence and Provenance > How Tally records what was verified, by whom, by what mechanism, and what auditors can check after the fact. Every attribute in a Tally snapshot can be linked to one or more evidence items. Each evidence item records a single verification event — the data, how it was obtained, who submitted it, and what artifacts can be independently validated. Tally records the mechanism. The grantee decides the risk. *** ## Evidence items Each snapshot contains an `evidence[]` array. Every item has a required `provenance` object that answers four questions: * **Authority** — who is the original source of truth? * **Write principal** — who called the `/attest` API and submitted this evidence? * **Verification** — what mechanism produced or checked the data? * **Custody artifacts** — what can be independently validated after the fact? ```json theme={null} { "evidence_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "evidence_type": "identity_document", "captured_at": "2026-06-20T14:32:00Z", "hash": { "alg": "sha-256", "value": "b6f4d0e6..." }, "provenance": { ... } } ``` The `attribute_paths` field on the envelope links each JSON Pointer path to the evidence items that support it: ```json theme={null} { "attribute_paths": { "/attributes/foundational/name": [ { "evidence_id": "3fa85f64-...", "role": "primary" } ] } } ``` *** ## `provenance` object ### `authority` — original source of truth Two variants, distinguished by `kind`: **`kind: "external_authority"`** — an institution outside Tally. ```json theme={null} { "kind": "external_authority", "authority_code": "usdos_passport", "authority_name": "U.S. Department of State", "authority_type": "government", "jurisdiction_code": "US" } ``` `authority_code` is a controlled vocabulary key, not a UUID. Known values include `usdos_passport`, `gleif`, `ny_dmv`, `sec_edgar`, `ny_dos`. The list is illustrative, not exhaustive. **`kind: "subject"`** — the subject record itself is the asserting authority. Used for self-asserted data by an individual or an organization. The subject may assert data through a service account (see `write_principal`). ```json theme={null} { "kind": "subject", "subject": { "subject_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "subject_type": "individual", "tenant_id": "b8f9c1a2-3d4e-5f60-7890-abcdef123456" } } ``` `subject_id` is always a server-generated UUID — no prefixes. ### `write_principal` — who submitted the evidence The principal that called the `/attest` endpoint. Always populated server-side from the auth context. The caller cannot supply this field. ```json theme={null} { "principal_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "principal_type": "service_account", "tenant_id": "b8f9c1a2-3d4e-5f60-7890-abcdef123456" } ``` `principal_type` is `"human" | "service_account" | "ai_agent"` — the same enum as the Tally principals table. `write_principal` and `authority` are deliberately separate fields: the iOS service account that submitted NFC-derived passport data is not the US Department of State. ### `verification` — what mechanism was used ```json theme={null} { "method": "nfc_chip_read" } ``` Known methods: | Value | Meaning | | ------------------------------ | -------------------------------------------------------------------------------------------------------------- | | `nfc_chip_read` | Data read from an NFC chip (ICAO 9303 passport or ISO 18013-5 mDL); passive authentication performed on-device | | `mobile_document_presentation` | ISO 18013-5 BLE/NFC holder-consent presentation flow | | `registry_fetch` | Data fetched programmatically from an authoritative public registry | | `api_fetch` | Data fetched from an authenticated API (non-registry) | | `manual_review` | A human principal reviewed a physical or digital document out-of-band | | `self_attested` | Principal directly asserts a value; no external verification | | `other` | Novel mechanism — pair with `method_code` to name it | For methods not in this list, use `method: "other"` and supply `method_code`: ```json theme={null} { "method": "other", "method_code": "bankid_presentation" } ``` ### `verification_signals` — mechanism-level facts An optional array of raw signals produced by the verification mechanism. Grantees and auditors read these to make their own trust judgment. Tally does not prescribe an assurance level. ```json theme={null} [ { "signal_type": "passive_authentication", "value": "success", "at": "2026-06-20T14:32:02Z" }, { "signal_type": "issuer_signature", "value": "valid", "at": "2026-06-20T14:32:03Z" }, { "signal_type": "csca_chain", "value": "valid", "at": "2026-06-20T14:32:03Z" } ] ``` Signal types are open strings. Known values include `passive_authentication`, `issuer_signature`, `csca_chain`, `registry_response_status`, `lei_registration_status`, `principal_authenticated`, `write_authorized_for_subject`. ### `custody_artifacts` — what auditors can verify An optional array of hashed, optionally signed artifacts. Each artifact is something a read-side verifier or compliance auditor can independently check after the fact — by re-fetching, re-hashing, or verifying a cryptographic signature. ```json theme={null} [ { "artifact_type": "mrtd_sod", "content_type": "application/octet-stream", "format": "icao9303_sod", "hash": { "alg": "sha-256", "value": "a1b2..." }, "signature": { "alg": "rsa-sha256", "key_ref": "csca:US:2024", "value": "MEQC..." } }, { "artifact_type": "dg1", "content_type": "application/octet-stream", "format": "icao9303_dg1", "hash": { "alg": "sha-256", "value": "b2c3..." } } ] ``` Known `artifact_type` values: `mrtd_sod`, `dg1`, `dg2`, `mdl_device_response`, `registry_api_response`, `assertion_payload`. Known `format` values: `icao9303_sod`, `icao9303_dg1`, `iso18013_5_device_response`, `gleif_lei_record`, `tally_self_assertion_v1`. *** ## Full examples ### NFC passport read ```json theme={null} { "evidence_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "evidence_type": "identity_document", "captured_at": "2026-06-20T14:32:00Z", "hash": { "alg": "sha-256", "value": "b6f4d0e6..." }, "notes": "Passport chip read via NFC. Passive authentication performed.", "provenance": { "authority": { "kind": "external_authority", "authority_code": "usdos_passport", "authority_name": "U.S. Department of State", "authority_type": "government", "jurisdiction_code": "US" }, "write_principal": { "principal_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "principal_type": "service_account", "tenant_id": "b8f9c1a2-3d4e-5f60-7890-abcdef123456" }, "verification": { "method": "nfc_chip_read" }, "verification_signals": [ { "signal_type": "passive_authentication", "value": "success" }, { "signal_type": "issuer_signature", "value": "valid" }, { "signal_type": "csca_chain", "value": "valid" } ], "custody_artifacts": [ { "artifact_type": "mrtd_sod", "content_type": "application/octet-stream", "format": "icao9303_sod", "hash": { "alg": "sha-256", "value": "a1b2..." }, "signature": { "alg": "rsa-sha256", "key_ref": "csca:US:2024", "value": "MEQC..." } } ], "verified_at": "2026-06-20T14:32:04Z" } } ``` ### Individual self-assertion ```json theme={null} { "evidence_id": "9b2c4e6f-8a1b-3c5d-7e9f-0a1b2c3d4e5f", "evidence_type": "self_assertion", "captured_at": "2026-06-20T10:00:00Z", "provenance": { "authority": { "kind": "subject", "subject": { "subject_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "subject_type": "individual", "tenant_id": "b8f9c1a2-3d4e-5f60-7890-abcdef123456" } }, "write_principal": { "principal_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "principal_type": "human", "tenant_id": "b8f9c1a2-3d4e-5f60-7890-abcdef123456" }, "verification": { "method": "self_attested" }, "verification_signals": [ { "signal_type": "principal_authenticated", "value": "true" } ], "verified_at": "2026-06-20T10:00:00Z" } } ``` ### Organization asserting data through a service account The authority is the organization subject; the write principal is the service account acting on its behalf. ```json theme={null} { "evidence_id": "c4d5e6f7-0a1b-2c3d-4e5f-6a7b8c9d0e1f", "evidence_type": "self_assertion", "captured_at": "2026-06-21T10:00:00Z", "provenance": { "authority": { "kind": "subject", "subject": { "subject_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567891", "subject_type": "organization", "tenant_id": "c9d0e1f2-a3b4-5c6d-7e8f-9a0b1c2d3e4f" } }, "write_principal": { "principal_id": "e2f3a4b5-c6d7-8901-bcde-f12345678902", "principal_type": "service_account", "tenant_id": "c9d0e1f2-a3b4-5c6d-7e8f-9a0b1c2d3e4f" }, "verification": { "method": "self_attested" }, "verification_signals": [ { "signal_type": "service_account_authenticated", "value": "true" }, { "signal_type": "write_authorized_for_subject", "value": "true" } ], "verified_at": "2026-06-21T10:00:00Z" } } ``` *** ## Envelope and schema versions Every snapshot envelope contains two version fields: | Field | Tracks | Example | | ------------------ | --------------------------------------------------------------------- | -------------------------------------------- | | `envelope_version` | Container structure (snapshot\_id, attributes, evidence, audit, diff) | `"entity_state_envelope_v1"` | | `schema_version` | Canonical attribute vocabulary inside `attributes` | `"2.0"` (individual), `"1.0"` (organization) | These advance independently. A snapshot can have `envelope_version: "entity_state_envelope_v1"` and `schema_version: "2.0"` — the container is unchanged; the attributes inside follow the v2 grouped vocabulary. For full field-level change history by schema version, see `tally_ops/registries/schema_tag_registry.json`.