Evidence and Provenance

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?

{
  "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:

{
  "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.

{
  "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).

{
  "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.

{
  "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

{ "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:

{ "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.

[
  { "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.

[
  {
    "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

{
  "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

{
  "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.

{
  "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.

Overview

Concepts

Evidence items

`provenance` object

`authority` — original source of truth

`write_principal` — who submitted the evidence

`verification` — what mechanism was used

`verification_signals` — mechanism-level facts

`custody_artifacts` — what auditors can verify

Full examples

NFC passport read

Individual self-assertion

Organization asserting data through a service account

Envelope and schema versions

​Evidence items

​provenance object

​authority — original source of truth

​write_principal — who submitted the evidence

​verification — what mechanism was used

​verification_signals — mechanism-level facts

​custody_artifacts — what auditors can verify

​Full examples

​NFC passport read

​Individual self-assertion

​Organization asserting data through a service account

​Envelope and schema versions

Evidence items

`provenance` object

`authority` — original source of truth

`write_principal` — who submitted the evidence

`verification` — what mechanism was used

`verification_signals` — mechanism-level facts

`custody_artifacts` — what auditors can verify

Full examples

NFC passport read

Individual self-assertion

Organization asserting data through a service account

Envelope and schema versions