LRFS conformance

This chapter specifies what a third-party implementation must do to claim conformance with LLM-Ready File Specification v1. Three conformance levels (L1–L3) are defined; an implementation MAY claim the highest level it fully supports.

1. Conformance levels

LRFS defines three levels of conformance, each building on the previous:

• L1 (Read) — The implementation can parse LRFS payloads from all 6 supported file formats (JPEG, PNG, PDF, MP3, WAV, M4A), extract all defined layers, and return layer contents to the caller. Signature verification is NOT required at L1. L1 readers can load unsigned payloads or payloads with unknown signatures.
• L2 (Write) — The implementation produces LRFS payloads that any conformant L1 reader can parse and extract. Layers MAY be written without signatures. L2 writers MUST produce valid RDF and correct XMP packet placement per format. File-level checksums are recommended at L2.
• L3 (Signed Read + Write) — Full L1 + L2 capabilities plus cryptographic signature verification (both HMAC-SHA256 and ed25519) and signature generation. L3 writers MUST produce signed layers and file-level checksums. L3 readers MUST verify all signatures before accepting payload content.

An implementation MAY claim multiple levels. For example, an implementation might claim "L2 writer and L3 reader" — it can write unsigned payloads but can read and verify signed payloads.

2. L1 requirements (Read)

An L1-conformant reader MUST:

• Parse XMP packets from all 6 supported file formats (JPEG APP1, PNG iTXt, PDF Metadata stream, MP3 ID3v2 PRIV, WAV RIFF, M4A XMP box) according to ISO 16684-1 and format-specific guidelines.
• Extract all llmind:* properties from the RDF graph and return them to the caller with their types intact.
• Gracefully ignore unknown llmind:* properties (those not defined in v1.0 or added in v1.1+). Forward compatibility is mandatory.
• Reject payloads with non-UTF-8 encoding and report the error distinctly.
• Parse RDF/XML that conforms to RDF 1.1. Reject malformed RDF.

An L1 reader SHOULD report parse errors distinctly from signature errors. An L1 reader MAY cache parsed layers in memory.

3. L2 requirements (Write)

An L2-conformant writer MUST:

• Produce valid XMP packets placed correctly per each host file format (JPEG APP1 segment, PNG iTXt chunk, PDF Metadata stream, etc.).
• Bind the llmind: prefix to the namespace URI https://llmind.org/ns/1.0/ in the RDF document.
• Use UTF-8 encoding throughout and declare encoding="UTF-8" in the XML declaration.
• Produce RDF/XML that parses as valid RDF 1.1 under standard tools (e.g., RDF parsers from Apache Jena, W3C RDF libraries, or equivalent).
• NOT write properties outside the LRFS v1.x-defined set unless using a clearly distinct namespace prefix (e.g., custom:, myapp:).
• Compute file-level SHA-256 checksums and store them as llmind:file_checksum.

An L2 writer SHOULD preserve any existing XMP packet content (e.g., Dublin Core properties like dc:creator, rights properties like xmpRights:*) when adding LRFS properties. Overwriting existing metadata is permitted but not recommended.

4. L3 requirements (Signed)

An L3-conformant implementation MUST support both reading and writing signed layers:

• Signing algorithms: Implement both HMAC-SHA256 and ed25519 signatures. An L3 writer MUST sign all layers using at least one algorithm; an L3 reader MUST verify signatures computed with either algorithm.
• Canonicalization: Canonicalize each layer per the payload-format chapter (§4, RDF Dataset Canonicalization) before signing or verifying.
• File-level checksums: Compute SHA-256 file-level checksums per the signing-scheme chapter (§3). L3 readers MUST verify checksums; L3 writers MUST generate them.
• Verification: Implement the verification algorithm (signing-scheme §4). Any verification error (invalid signature, checksum mismatch, missing signature) MUST cause the operation to REJECT the payload and report an error.
• Fail closed: Do NOT silently ignore signature errors or fall back to unsigned data. Signature failures are fatal.

L3 readers SHOULD support key caching and TTL management for ed25519 public keys fetched from URLs. L3 writers SHOULD use secure key management (HSM, KMS, secure enclaves) for ed25519 private keys.

5. Test vectors

A public conformance test suite lives at /spec/test-vectors/ on this site. Each vector is a self-contained JSON file with inputs and expected fields that any LRFS implementation (in any language) can validate against. The machine-readable index at /spec/test-vectors/index.json enumerates every vector with its category and spec section. The test suite covers:

• Sample files in all 6 formats with LRFS payloads
• Signed and unsigned payloads
• Intentionally malformed payloads for error handling
• Canonicalization test cases
• Key references and test keys for ed25519 and HMAC

Implementations claim conformance by running the test suite and publishing their results (PASS/FAIL per test).

6. Claiming conformance

An implementation MAY state one of the following:

• "Conforms to LRFS v1.0, level L1" — Read-only
• "Conforms to LRFS v1.0, level L2" — Write (unsigned)
• "Conforms to LRFS v1.0, level L3" — Full signed read+write

Conformance is self-reported; there is no central certification body. Third parties can challenge a conformance claim by running the official test suite against the implementation.

Implementations SHOULD document:

• Which file formats are supported (subset of JPEG, PNG, PDF, MP3, WAV, M4A)
• Which layers are supported (subset of description, entities, structure, transcription, lineage, ocr)
• For L3: which cryptographic algorithms are implemented (HMAC-SHA256, ed25519, or both)

Failure-mode conformance

Beyond the canonicalization, signing, and file-checksum vectors, LRFS v1.0 publishes failure-mode test vectors that a conformant reader MUST handle correctly. A reader that passes every happy-path vector may still crash on malformed input or silently accept tampered files — failure-mode coverage is the distinction between a parser and a conformant verifier.

The published failure-mode categories cover:

• Tampered signatures — the reader MUST reject payloads whose signatures fail verification.
• Malformed XMP — the reader MUST surface a structured parse error, not crash, on syntactically invalid input.
• Algorithm/length mismatch — the reader MUST reject payloads whose declared signing algorithm is inconsistent with the signature byte length.
• Empty payload — the reader MUST distinguish a valid but empty LRFS container (no layers, no signature) from a corrupt payload, returning an empty layer set without error.
• Unknown namespace version — per LRFS v1.0 §7, readers of v1.x MUST ignore payloads using a future major-version namespace (e.g., /ns/2.0/) rather than attempt to parse them.

Each fixture is a self-contained JSON file with inputs, an expected_outcome (one of reject, ignore, or parse_error), and a reason field that explains the spec requirement. Implementations self-report conformance by running these fixtures against their reader; see /spec/implementations/ for the published implementations directory.

7. Related chapters

• Payload format — Normative RDF and canonicalization rules
• Signing scheme — Normative signing and verification algorithms
• File enrichment glossary — definitions of terms used throughout the specification