@bsv/dpp-core 0.3.0-beta.1

package/schemas/epcis-import.schema.json

@@ -0,0 +1,212 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bsv-blockchain.github.io/dpp/contracts/epcis-import.schema.json",
+  "title": "DPP EPCIS import record, version 1",
+  "description": "The durable record of one retained EPCIS source under the epcis-json@1 profile (spec/epcis-interoperability.md section 2): what was received, where its exact bytes are kept, how it was interpreted, what each event's validation and mapping found, which events conflict with earlier ones, what was published from it under separate authority, and how far a pull got. Operational state never substitutes for a verification report, and no field of this record is a token operation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["importVersion", "importId", "requestId", "sourceId", "receivedAt", "mediaType", "byteLength", "sha256", "bytesRef", "sourceLocation", "contextRefs", "profileRefs", "policyId", "state", "events", "progress"],
+  "properties": {
+    "importVersion": { "const": "1" },
+    "importId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The stable internal identity of this import." },
+    "requestId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The caller's idempotency key, bound to requestDigest: an identical retry resumes or returns this import, a reuse with different bytes is a conflict." },
+    "requestDigest": { "$ref": "#/$defs/sha256", "description": "SHA-256 of the canonical request the idempotency key is bound to." },
+    "sourceId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The configured source identity events are scoped under. It names a configured origin, never an account type." },
+    "receivedAt": { "$ref": "#/$defs/dateTime" },
+    "mediaType": { "enum": ["application/json", "application/ld+json"] },
+    "byteLength": { "type": "integer", "minimum": 0 },
+    "sha256": { "$ref": "#/$defs/sha256", "description": "The digest of the exact received bytes; export returns bytes with this digest or nothing." },
+    "bytesRef": { "type": "string", "minLength": 1, "description": "Where the exact bytes are retained: a store key, a path or a content address, as the deployment names it." },
+    "sourceLocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "description": "Provenance, never authentication proof. Credentials are never recorded here.",
+      "properties": {
+        "kind": { "enum": ["file", "query", "single-event"] },
+        "origin": { "type": "string", "format": "uri", "description": "The configured repository origin a query was made to, without credentials." },
+        "query": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The standard query parameters used, by name." },
+        "page": { "type": "integer", "minimum": 1 },
+        "filename": { "type": "string" }
+      }
+    },
+    "contextRefs": {
+      "type": "array",
+      "description": "The context declarations of the source exactly as found, each with its pinned digest or the statement that it is unpinned.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "value", "pinned"],
+        "properties": {
+          "kind": { "enum": ["iri", "inline"] },
+          "value": { "type": "string", "minLength": 1 },
+          "digest": { "$ref": "#/$defs/sha256" },
+          "pinned": { "type": "boolean" },
+          "scope": { "type": "string", "description": "document, or the pointer of the event that declared it." }
+        }
+      }
+    },
+    "profileRefs": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "pattern": "^[a-z][a-z0-9.-]*@[0-9][0-9a-z.-]*$" },
+      "description": "The interoperability and credential profiles this import was interpreted under, for example epcis-json@1 and epcis-vsc@1."
+    },
+    "policyId": { "type": "string", "minLength": 1, "description": "The named operator policy the limits, source scope and any automation were read from." },
+    "limits": { "type": "object", "additionalProperties": { "type": ["integer", "string"] }, "description": "The limits in force for this import, as the profile discloses them." },
+    "state": { "enum": ["received", "evaluated", "publication-pending", "published", "blocked"], "description": "received: bytes retained, not yet evaluated. evaluated: validation and mapping findings recorded, nothing published. publication-pending: a separately authorised publication was requested and is unresolved. published: at least one event was published as a credential. blocked: a conflict or a refused publication needs explicit resolution. Never a verification verdict." },
+    "envelope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "enum": ["EPCISDocument", "EPCISQueryDocument"] },
+        "schemaVersion": { "type": "string" },
+        "creationDate": { "type": "string" },
+        "queryName": { "type": "string" },
+        "hasHeader": { "type": "boolean" },
+        "hasMasterData": { "type": "boolean" }
+      }
+    },
+    "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" }, "description": "Document-level findings: envelope, schema and context findings that are not about one event." },
+    "events": { "type": "array", "items": { "$ref": "#/$defs/event" } },
+    "progress": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pagesRead", "complete", "completenessLimits"],
+      "properties": {
+        "checkpoint": { "type": "string", "description": "The durable pull checkpoint (the next page token, or the record-time cutoff reached), written only after the page's imports and results are durable." },
+        "checkpointExpiresAt": { "$ref": "#/$defs/dateTime" },
+        "pagesRead": { "type": "integer", "minimum": 0 },
+        "bytesRead": { "type": "integer", "minimum": 0 },
+        "complete": { "type": "boolean", "description": "True only when the source answered the whole bounded query without a next page and within the limits; never an assertion of complete history." },
+        "completenessLimits": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Every reason the result is not complete history: the query scope, a page limit reached, an expired cursor, a timestamp-only bound." },
+        "sourceOutcome": { "$ref": "#/$defs/sourceOutcome" },
+        "sourceDetail": { "type": "string" }
+      }
+    },
+    "createdAt": { "$ref": "#/$defs/dateTime" },
+    "updatedAt": { "$ref": "#/$defs/dateTime" }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "dateTime": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$" },
+    "pointer": { "type": "string", "pattern": "^(/[^/]*)*$", "description": "An RFC 6901 JSON pointer into the retained document; the empty pointer is a single event accepted as the whole source." },
+    "sourceOutcome": {
+      "enum": ["source-link-missing", "source-authentication-required", "source-forbidden", "source-unavailable", "unexpected-media-type", "invalid-source", "partial-history", "ok"],
+      "description": "The outcome of reaching a source: no discovered EPCIS link; the source demanded authentication; the source refused this caller; the source did not answer or answered an error; the source answered a media type that is not EPCIS (an HTML login page with status 200 is this, never success); the bytes were refused before retention; the bounded query ended before the source did; or the bounded query completed. A successful query with zero matching events is ok with an empty event list, never any other outcome."
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "path", "message", "severity"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "path": { "type": "string" },
+        "message": { "type": "string", "minLength": 1 },
+        "severity": { "enum": ["error", "warning", "info"] }
+      }
+    },
+    "identifier": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "value", "scheme"],
+      "properties": {
+        "path": { "$ref": "#/$defs/pointer" },
+        "value": { "type": "string" },
+        "scheme": { "enum": ["gs1-sgtin", "gs1-lgtin", "gs1-sgtin-pattern", "gs1-digital-link", "epc-other", "other"] },
+        "gtin": { "type": "string", "pattern": "^\\d{14}$" },
+        "serial": { "type": "string" },
+        "lot": { "type": "string" },
+        "checkDigitValid": { "type": "boolean" },
+        "problem": { "type": "string" }
+      }
+    },
+    "event": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pointer", "identity", "identityKind", "eventType", "bodyDigest", "validation", "mapping"],
+      "properties": {
+        "pointer": { "$ref": "#/$defs/pointer" },
+        "eventId": { "type": "string", "format": "uri", "description": "The event's own eventID, when it carries one." },
+        "identity": { "type": "string", "minLength": 1, "description": "The scoped identity duplicates and conflicts are decided under: the eventID, or the local identity." },
+        "identityKind": { "enum": ["event-id", "local"] },
+        "eventType": { "type": "string", "minLength": 1 },
+        "eventTime": { "type": "string" },
+        "recordTime": { "type": "string" },
+        "bodyDigest": { "$ref": "#/$defs/sha256", "description": "The canonical event-body digest: RFC 8785 over the event without recordTime and errorDeclaration plus the sorted context digests." },
+        "identifiers": { "type": "array", "items": { "$ref": "#/$defs/identifier" } },
+        "preservedExtensions": { "type": "array", "items": { "type": "string" } },
+        "validation": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schema", "findings"],
+          "properties": {
+            "schema": { "enum": ["pass", "fail", "unknown"], "description": "Whether the pinned schema accepted the document this event belongs to; unknown when validation was not run." },
+            "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } }
+          }
+        },
+        "errorDeclaration": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["correctiveEventIDs", "resolution"],
+          "properties": {
+            "declarationTime": { "type": "string" },
+            "reason": { "type": "string" },
+            "correctiveEventIDs": { "type": "array", "items": { "type": "string" } },
+            "resolution": { "enum": ["resolved", "unresolved"], "description": "resolved only when every corrective event named is held under this source; an EPCIS error declaration is never a VSC correction." },
+            "missing": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "mapping": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["outcome", "missing", "unmapped"],
+          "properties": {
+            "profile": { "type": "string", "pattern": "^[a-z][a-z0-9.-]*@[0-9][0-9a-z.-]*$" },
+            "outcome": { "enum": ["lossless", "transformed", "unsupported", "insufficient-data", "not-attempted"] },
+            "missing": { "type": "array", "items": { "type": "string" } },
+            "unmapped": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "arrival": { "enum": ["new", "duplicate", "new-observation", "conflict"], "description": "How this event relates to what the source already held under the same identity." },
+        "conflict": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["withImportId", "withBodyDigest", "state"],
+          "description": "A different body under the same scoped identity; both bodies stay retained and visible until a person resolves it by name.",
+          "properties": {
+            "withImportId": { "type": "string" },
+            "withPointer": { "$ref": "#/$defs/pointer" },
+            "withBodyDigest": { "$ref": "#/$defs/sha256" },
+            "state": { "enum": ["open", "resolved"] },
+            "resolution": { "type": "string" },
+            "resolvedAt": { "$ref": "#/$defs/dateTime" }
+          }
+        },
+        "publication": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["state"],
+          "description": "The separately authorised publication of this event as a credential, if one was requested. The credential's bytes and identity are persisted before anchoring; a retry after an uncertain answer resumes this record and never issues again.",
+          "properties": {
+            "state": { "enum": ["requested", "issued", "submitted", "anchored", "refused", "unavailable"] },
+            "credentialId": { "type": "string", "format": "uri" },
+            "digest": { "$ref": "#/$defs/sha256", "description": "The digest of the exact issued credential bytes." },
+            "representation": { "type": "string" },
+            "operationId": { "type": "string", "description": "The durable operation the publication runs under." },
+            "anchor": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["txid", "outputIndex"],
+              "properties": { "txid": { "$ref": "#/$defs/sha256" }, "outputIndex": { "type": "integer", "minimum": 0 } }
+            },
+            "refusal": { "type": "string" },
+            "authorisedBy": { "type": "string", "description": "The server-side authority that permitted publication; never a role the request body supplied." },
+            "at": { "$ref": "#/$defs/dateTime" }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/evidence-export.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bsv-blockchain.github.io/dpp/contracts/evidence-export.schema.json",
+  "title": "DPP evidence export part, version 1",
+  "description": "One part of a complete export (spec/portable-evidence.md section 2): a dpp-evidence-package@1 over the states of one passport whose source sequence lies in the part's range within one snapshot, beside the coverage record a reader needs to join the parts. The coverage record (exportVersion, passportId, snapshot, part, final, manifestSha256 and the signature's suite and signer) is signed by the exporter with the same key as the package manifest and bound to that manifest by its digest, so no unsigned field establishes coverage or finality; the cursor and the package bytes stay outside it. The parts of one snapshot tile its sequence range from 1 to the snapshot's sequence with no gap and no overlap; a part is complete for its own range and never for the snapshot, unless it is the only part. The package inside is inspected exactly as any other; the record is what says how the packages compose, and a signature over it attributes the assertion to the exporter without proving the exporter held everything that exists elsewhere.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["exportVersion", "passportId", "snapshot", "part", "nextCursor", "final", "manifestSha256", "signature", "package"],
+  "properties": {
+    "exportVersion": { "const": "1" },
+    "passportId": { "type": "string", "minLength": 1, "maxLength": 512 },
+    "snapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "id", "sequence"],
+      "properties": {
+        "source": { "type": "string", "minLength": 1, "description": "The service the snapshot was taken of." },
+        "id": { "type": "string", "minLength": 1, "description": "The snapshot identifier every part of this export and its package manifest name." },
+        "sequence": { "type": "integer", "minimum": 0, "description": "The source's highest sequence within the snapshot; the last part's range ends here." }
+      }
+    },
+    "part": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["index", "sequenceRange", "states"],
+      "properties": {
+        "index": { "type": "integer", "minimum": 1, "description": "1 for the first part; consecutive." },
+        "sequenceRange": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["from", "to"],
+          "properties": {
+            "from": { "type": "integer", "minimum": 0 },
+            "to": { "type": "integer", "minimum": 0 }
+          },
+          "description": "The sequences this part covers: from the position after the previous part to the last state here, or to the snapshot's sequence on the final part. Consecutive parts tile the snapshot."
+        },
+        "states": { "type": "integer", "minimum": 0, "description": "How many states of the passport lie in the range; each is in the package or declared absent by outpoint." }
+      }
+    },
+    "nextCursor": { "type": ["string", "null"], "description": "Opaque, bound to the passport and the snapshot; null on the final part. Outside the signed coverage record: a resumption token, never a statement about coverage." },
+    "final": { "type": "boolean", "description": "Signed. True exactly when the part ends at the snapshot's sequence; nextCursor is then null." },
+    "manifestSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Signed. SHA-256 of the canonical JSON of package.manifest exactly as signed, signature value included, binding the record to that package and no other." },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["suite", "signer", "value"],
+      "properties": {
+        "suite": { "const": "bsv-ecdsa-der", "description": "bsv-ecdsa-der: ECDSA over SHA-256 of the canonical JSON of the coverage record (exportVersion, passportId, snapshot, part, final, manifestSha256 and signature without value; object keys sorted recursively, no whitespace), DER encoded." },
+        "signer": { "type": "string", "pattern": "^0[23][0-9a-f]{64}$", "description": "The exporter's compressed key; the same key that signed package.manifest." },
+        "value": { "type": "string", "minLength": 1 }
+      }
+    },
+    "package": {
+      "type": "object",
+      "required": ["manifest", "files"],
+      "description": "The part's dpp-evidence-package@1 in the JSON envelope form: the signed manifest beside every inventoried file, base64 by path.",
+      "properties": {
+        "manifest": { "$ref": "./evidence-package.schema.json" },
+        "files": {
+          "type": "object",
+          "additionalProperties": { "type": "string", "contentEncoding": "base64" }
+        }
+      }
+    }
+  }
+}

package/schemas/evidence-package.schema.json

@@ -0,0 +1,307 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bsv-blockchain.github.io/dpp/contracts/evidence-package.schema.json",
+  "title": "DPP evidence package manifest, version 1",
+  "description": "The signed manifest of a dpp-evidence-package@1 (spec/portable-evidence.md section 2): exact identities, export time, profile and policy references, source observations, disclosure scope, completeness declarations and a content-addressed inventory. The signature authenticates the exporter and the inventory, never the truth or exhaustiveness of what is inventoried.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "format",
+    "version",
+    "passportId",
+    "exportedAt",
+    "exporter",
+    "disclosure",
+    "completeness",
+    "sources",
+    "inventory",
+    "signature"
+  ],
+  "properties": {
+    "format": {
+      "const": "dpp-evidence-package"
+    },
+    "version": {
+      "const": "1"
+    },
+    "passportId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512
+    },
+    "genesis": {
+      "$ref": "#/$defs/outpoint"
+    },
+    "selectedTip": {
+      "$ref": "#/$defs/outpoint"
+    },
+    "exportedAt": {
+      "$ref": "#/$defs/dateTime"
+    },
+    "exporter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "role"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A DID or a compressed identity key of the party that assembled and signed the package."
+        },
+        "role": {
+          "enum": [
+            "registry",
+            "overlay",
+            "writer",
+            "reader",
+            "other"
+          ]
+        },
+        "software": {
+          "type": "string"
+        }
+      }
+    },
+    "profiles": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9.-]*@[0-9][0-9a-z.-]*$"
+      }
+    },
+    "policyId": {
+      "type": "string"
+    },
+    "disclosure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "scope",
+        "recoveryBackup"
+      ],
+      "properties": {
+        "scope": {
+          "enum": [
+            "public",
+            "public-and-owner",
+            "public-and-legitimate",
+            "public-and-authority",
+            "all-tiers"
+          ]
+        },
+        "recipient": {
+          "type": "string",
+          "description": "Who the restricted tiers are encrypted to, when any are included."
+        },
+        "recoveryBackup": {
+          "type": "boolean",
+          "description": "True only for a package that carries every tier for the operator's own recovery; a public-scope package is never one."
+        }
+      }
+    },
+    "completeness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "snapshots",
+        "withheld",
+        "absent"
+      ],
+      "properties": {
+        "snapshots": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "source",
+              "snapshotId",
+              "completeForSnapshot"
+            ],
+            "properties": {
+              "source": {
+                "type": "string"
+              },
+              "snapshotId": {
+                "type": "string"
+              },
+              "completeForSnapshot": {
+                "type": "boolean"
+              },
+              "scope": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "withheld": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Material known to exist and deliberately not included, by reference."
+        },
+        "absent": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Material referenced by included evidence that the exporter could not obtain."
+        }
+      }
+    },
+    "sources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "kind",
+          "observedAt",
+          "result"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "overlay-lookup",
+              "spend-status",
+              "header-source",
+              "registry",
+              "other"
+            ]
+          },
+          "observedAt": {
+            "$ref": "#/$defs/dateTime"
+          },
+          "result": {
+            "enum": [
+              "unspent",
+              "spent",
+              "not-found",
+              "unavailable",
+              "conflicting"
+            ]
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "blockHash": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          }
+        }
+      }
+    },
+    "inventory": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "category",
+          "mediaType",
+          "byteLength",
+          "sha256"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\x00]+$",
+            "description": "Relative, no traversal."
+          },
+          "category": {
+            "enum": [
+              "transactions",
+              "proofs",
+              "native-claims",
+              "external-credentials",
+              "evidence",
+              "schemas",
+              "authority",
+              "status",
+              "reports"
+            ]
+          },
+          "mediaType": {
+            "type": "string",
+            "minLength": 1
+          },
+          "byteLength": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "encrypted": {
+            "type": "boolean"
+          },
+          "represents": {
+            "type": "string",
+            "description": "What the file is: an outpoint, a credential id, a claim digest, a schema id."
+          },
+          "representation": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "suite",
+        "signer",
+        "value"
+      ],
+      "properties": {
+        "suite": {
+          "const": "bsv-ecdsa-der",
+          "description": "bsv-ecdsa-der: ECDSA over SHA-256 of the canonical JSON of this manifest without signature.value (object keys sorted recursively, no whitespace, arrays in order, strings, booleans and safe integers only), DER encoded."
+        },
+        "signer": {
+          "type": "string"
+        },
+        "value": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  },
+  "$defs": {
+    "dateTime": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
+    },
+    "outpoint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "txid",
+        "outputIndex"
+      ],
+      "properties": {
+        "txid": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "outputIndex": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}

package/schemas/native-evidence-extension.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bsv-blockchain.github.io/dpp/contracts/native-evidence-extension.schema.json",
+  "title": "DPP native evidence extension, version 1",
+  "description": "A reference, carried inside a credential in an external representation, to evidence that already exists on the native rails (spec/exchange.md section 5). A verifier resolves and verifies each reference independently; the credential's own signature is over these references, so no digest is circular. Identified by urn:bsv:dpp:native-evidence:1.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "passportId", "state", "nativeProfile", "mappingVersion"],
+  "properties": {
+    "type": { "const": "urn:bsv:dpp:native-evidence:1" },
+    "passportId": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The exact passport identifier the referenced state carries in field 3." },
+    "state": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["txid", "outputIndex"],
+      "properties": {
+        "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "outputIndex": { "type": "integer", "minimum": 0 },
+        "op": { "enum": ["ACTIVATE", "SOLD", "RESOLD", "REPAIRED", "RECYCLED", "EDIT", "TRANSFER"] }
+      }
+    },
+    "genesis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["txid", "outputIndex"],
+      "properties": {
+        "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "outputIndex": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "nativeClaim": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["representation", "digest"],
+      "properties": {
+        "representation": { "const": "dpp-lifecycle-json-v1" },
+        "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the complete signed native claim's canonical bytes, the digest the anchor commits to." },
+        "issuer": { "type": "string", "maxLength": 512 },
+        "eventType": { "enum": ["Origin", "Transfer", "Transformation", "Disposition"] }
+      }
+    },
+    "anchor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["txid", "outputIndex", "format"],
+      "properties": {
+        "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "outputIndex": { "type": "integer", "minimum": 0 },
+        "format": { "const": "bsv-attestation-anchor-v1" },
+        "anchoredBy": { "type": "string", "pattern": "^0[23][0-9a-f]{64}$" }
+      }
+    },
+    "nativeProfile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "version": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "mappingVersion": { "type": "string", "minLength": 1, "description": "The version of the exchange profile's mapping under which the external credential was produced from the native evidence." },
+    "mappingResult": { "enum": ["lossless", "transformed", "unsupported", "insufficient-data"] },
+    "losses": { "type": "array", "items": { "type": "string" }, "description": "What the mapping could not carry, in words; never silent." }
+  }
+}