On this page
Define what the fingerprint covers
The source dates shown in this guide identify documentation checks on 22 October 2026, not original publication dates. Name the identity target: one file, a directory manifest, a logical dataset, a query result, or a pipeline snapshot. Record algorithm, encoding, object type, path normalization, line-ending policy, and whether metadata is included. A digest of one archive is not automatically a digest of the files it contains.
| Identity input | Record | Stop if |
|---|---|---|
| Members | Stable member ids and inclusion rule | Directory order is implicit |
| Bytes | Hash algorithm and exact bytes | Text normalization is unknown |
| Metadata | Schema, manifest, or sidecars included | Metadata scope is unstated |
| Source | Version, query, and capture point | Remote source is mutable |
| Ordering | Canonical sort and separators | Manifest can reorder |
| Result | Fingerprint and creation record | Only a short label remains |
The Git, (opens in a new tab) documentation is a useful reminder that object type, path filters, and content affect an object id. Choose a simpler explicit contract for a dataset manifest if that is what the consumer needs, and write the contract beside the fingerprint.
Freeze the source boundary before hashing
A snapshot is a statement about what was observed at a capture boundary. Record retrieval time, source version or generation, query parameters, pagination completion, and any source-side consistency guarantee. If a source can change while files are being read, the fingerprint can still be repeatable for the bytes captured while failing to represent one coherent source state.
| Boundary | Evidence | Open risk |
|---|---|---|
| File set | Manifest and member hashes | Member changed during read |
| API result | Cursor completion and query | Concurrent mutation |
| Object store | Generation or version id | Latest pointer moved |
| Pipeline stage | Inputs and config version | Dependency not frozen |
| Archive | Archive bytes and extracted manifest | Archive metadata changes |
The Data Version Control, (opens in a new tab) command describes a reproducibility workflow state. It can help a team avoid rerunning a stage, but it does not replace the input manifest or prove that the source itself stopped changing. Keep “workflow frozen,” “source versioned,” and “bytes fingerprinted” as separate fields.
Reconcile members, schema, and derived outputs
Produce a manifest with one row per included member, stable logical path or id, byte length, content fingerprint, source version, and exclusion reason for anything omitted. Hash the manifest itself after canonical ordering. If a transformed table or subset is part of the package, give it its own derivation record and fingerprint rather than implying that the source fingerprint covers it.
- Capture the source boundary and immutable identifiers.
- Enumerate members with explicit inclusion and exclusion rules.
- Hash exact bytes under a named algorithm and encoding policy.
- Canonicalize and fingerprint the manifest.
- Record schema and transformation artifacts separately.
- Repeat the check and compare every identity input.
Use a synthetic snapshot fixture
Synthetic manifest and freeze record
snapshot=fixture-2026-01; source_generation=G7; algorithm=fixture-hash; order=logical_id ASC
member | bytes | included | reason
fixture-a | 12 | yes | in scope
fixture-b | 7 | yes | in scope
fixture-c | unknown | no | excluded:temporary
manifest_fingerprint=fixture-digest
workflow_frozen=yes; source_mutability=unknown; query=fixture-filter-v2| Test | Expected result | Hold condition |
|---|---|---|
| Order | Same logical order on rerun | Filesystem order used |
| Excluded member | Reason retained | Omission is silent |
| Source generation | Generation recorded | Latest pointer only |
| Schema output | Separate derived fingerprint | Covered by source digest |
| Freeze state | Workflow and source fields distinct | Freeze called completeness |
Every identifier and digest in this fixture is synthetic. Add a changed byte, changed manifest order, a new source generation, and a query-version change. Each should alter the identity or produce a visible unresolved finding under the chosen contract.
Keep snapshot identity separate from rights or quality conclusions
Fingerprint review can show what bytes and metadata a package claims to contain. It cannot establish completeness, ownership, authorization, quality, security, or suitability for a use. Keep source authority, access decisions, and quality findings in separate records.
Pair this guide with dataset file manifest and checksums for member-level evidence and dataset subset filter evidence for selection provenance. After a supported non-health scope, authority to describe the collection, and a controlled snapshot packet are established, the qualified appraisal request path may be a preparation step. It does not hash files, freeze sources, create a quote, match a buyer, or grant a license.
Takeaways
- Define fingerprint scope, algorithm, ordering, filters, and metadata inputs.
- Capture source generation or query boundary before reading members.
- Keep member, manifest, schema, and derived-output fingerprints distinct.
- Record workflow freeze separately from source immutability.
- Do not treat a stable digest as proof of completeness or rights.