On this page
Record four evidence layers before naming a mismatch
The source dates shown in this guide identify documentation checks on 22 October 2026, not original publication dates. Follow each citation for the evidence vocabulary being discussed. Start with a controlled artifact reference and capture observations without changing the source. The layers are related but not interchangeable.
| Layer | What it observes | What it cannot establish alone |
|---|---|---|
| Filename hint | Extension or URL suffix | Actual bytes or decoder support |
| Declared MIME | Source, transport, or manifest label | That the bytes have that format |
| Leading-byte signature | Bounded prefix or magic pattern | Complete validity or semantic meaning |
| Decoder result | One reader opening, identifying, or rejecting bytes | Universal support, provenance, or content quality |
The Python Software Foundation, (opens in a new tab) documentation maps a filename or URL to a MIME type and notes platform-dependent data. Use it as a filename-layer observation, not a content test. The WHATWG, (opens in a new tab) standard is a source for byte-signature vocabulary and user-agent behavior; it is not a universal server policy. State which layer produced each value and which implementation produced a decoder result.
- Retain the controlled artifact id, digest, and byte length.
- Record the filename hint exactly as received and the declared MIME value with its source.
- Read only the bounded prefix needed for the selected signature check and record the signature class or unavailable state.
- Run an approved decoder in a bounded environment and record format identification, lazy-open, full-read, or stable failure class.
- Assign a mismatch class only after comparing the layers, not before.
Use a mismatch matrix instead of a single verdict
A mismatch is an observation about the contract, not a diagnosis of cause. A mislabeled derivative, an incomplete transfer, a polyglot or container format, a decoder limitation, and an incorrect source declaration can produce different combinations. Preserve the evidence and ask a narrow next question.
| Synthetic case | Four observations | Disposition |
|---|---|---|
| A | .png, image/png, PNG signature, decoder identifies image | Layers agree for this decoder; continue separate provenance and content review |
| B | .png, image/png, ZIP signature, image decoder rejects | Declared and decoder layers disagree; hold and identify the producing contract |
| C | .bin, unavailable, JSON-looking prefix, text decoder reads | Extension is uninformative; preserve byte evidence and declare the selected interpretation |
| D | .jpg, image/jpeg, JPEG prefix, lazy open succeeds but full read fails | Identification is not complete-read evidence; retain a partial decoder finding |
| E | .json, text/plain, unknown prefix, decoder unavailable | No format conclusion; mark decoder and signature evidence unavailable |
The cases are synthetic. Do not turn a matching row into a general validity or quality claim. Likewise, a mismatch is not automatically evidence of a harmful file or an unauthorized source. Keep the artifact in a controlled handling process while its owner decides whether a corrected derivative is allowed.
Bound the signature and decoder checks
A signature check should state the prefix length, byte representation, expected pattern class, and result. It should not copy arbitrary bytes into a public report. A decoder check should state whether it identified the header, read metadata, decoded a bounded sample, or reached end-of-input. Those stages answer different questions.
Synthetic evidence ledger
artifact_ref | filename | declared_mime | signature_class | decoder_stage | mismatch_class
synthetic-a | photo.png | image/png | png-prefix | identified | none-observed
synthetic-b | photo.png | image/png | zip-prefix | rejected | declaration-signature
synthetic-c | data.bin | unavailable | json-prefix | metadata-read | filename-unknownThe ledger is invented and intentionally records classes instead of raw content. For a Pillow-based image check, Pillow, (opens in a new tab) documents that Image.open identifies lazily and that processing or load reads actual image data. Use that distinction when designing a bounded check. Another decoder may have different stages, so do not copy Pillow behavior to every format.
| Decoder stage | Safe wording | Avoid |
|---|---|---|
| Unavailable | No decoder evidence was collected | Calling the artifact invalid |
| Header identified | The decoder identified a format at open | Calling all data readable |
| Metadata read | Selected metadata was read | Calling payload complete |
| Bounded sample read | A named sample decoded under policy | Generalizing to the whole file |
| End reached | The selected decoder reached end-of-input | Declaring provenance or semantic accuracy |
| Stable failure | The decoder stopped with a classified failure | Publishing raw error text or private values |
Use synthetic fixtures and preserve uncertainty
Build a fixture set with matching layers, a wrong extension, a wrong declaration, a recognized signature with decoder rejection, a lazy-open versus full-read difference, and an unavailable decoder. Use synthetic names and short prefixes. Keep actual media or document bytes out of a public worksheet unless the owner has approved the handling and redaction boundary.
| Check | Observation to retain | Decision boundary |
|---|---|---|
| Filename mapping | Extension, mapping source, and result | Hint only, or contract field if owner says so |
| Declared MIME | Value, source, and timestamp if available | Claim from that source, not byte proof |
| Signature | Prefix policy and stable class | Bounded evidence only |
| Decoder | Implementation, version, stage, and limit | Result applies to that run |
| Mismatch | Pair or set of conflicting layers | Hold, request clarification, or document exception |
| Derivative | New reference, transformation, and digest | Never overwrite the source identity |
A remediation can be a corrected declaration, a renamed derivative, a re-export, or an explicit exception. Do not perform it silently. If a file is kept because the owner accepts a mismatch, record that decision and the evidence it does not resolve.
Keep MIME evidence separate from downstream decisions
MIME, signature, and decoder evidence can explain a format mismatch for one artifact and one run. It cannot establish ownership, permission to retain or share content, privacy clearance, semantic accuracy, or commercial demand. Keep those questions in their own provenance, privacy, rights, and owner-approved records.
Pair this guide with text encoding checks for byte-to-text issues and the data provenance log for artifact identity. After the owner has a supported non-health scope, authority to describe the collection, and a controlled mismatch ledger or synthetic fixture, the qualified appraisal request path may be a next preparation step. It does not validate files, rename artifacts, create a quote, match a buyer, issue a legal opinion, or grant a license.
Takeaways
- Keep filename, declared MIME, byte signature, and decoder result in separate fields.
- Label decoder stage and implementation so a lazy identification is not mistaken for a complete read.
- Use mismatch classes and synthetic fixtures instead of a single valid or invalid verdict.
- Preserve source identity and record any corrected derivative separately.
- Keep format evidence separate from provenance, privacy, rights, accuracy, and demand decisions.