SDF Format
Specification v0.1

An SDF file is a valid ZIP archive with the .sdf extension. The extension is a content-type signal, not a structural one — renaming to .zip MUST produce a valid ZIP archive.

File Manifest

Size Limits

Consumer Processing Order

Consumers MUST process archive entries in this order:

1. Verify the file is a valid ZIP. If not: SDF_ERROR_NOT_ZIP.
2. Validate all entry paths (traversal check). If unsafe: SDF_ERROR_INVALID_ARCHIVE.
3. Check size limits. If exceeded: SDF_ERROR_ARCHIVE_TOO_LARGE.
4. Verify all required entries are present. If missing: SDF_ERROR_MISSING_FILE.
5. Parse and validate meta.json.
6. Parse and validate schema.json.
7. Parse and validate data.json against schema.json.
8. Process visual.pdf.
9. Verify signature.sig if present.

meta.json is the identity and provenance record of an SDF document. It answers: what is this document, who issued it, and when was it created? It is intentionally separate from data.json so that SDF metadata can evolve independently of business document schemas.

Fields

{
  "sdf_version": "0.1",
  "document_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "document_type": "invoice",
  "issuer": "Acme Supplies GmbH",
  "issuer_id": "DE123456789",
  "created_at": "2026-03-15T14:30:00+01:00",
  "recipient": "Global Logistics AG",
  "locale": "de-DE"
}

data.json carries the structured business data of the document. Its schema is defined by the bundled schema.json. SDF makes no assumptions about the shape of business data — producers define the schema, and consumers validate against it.

Constraints

• data.json MUST validate against the bundled schema.json before the archive is written.
• Monetary amounts MUST be represented as {"amount": "string", "currency": "ISO4217"}. Bare numeric values are prohibited.
• Dates MUST be ISO 8601 strings. Numeric timestamps are not permitted.
• SDF metadata fields (sdf_version, document_id) MUST NOT appear in data.json.

// Correct monetary amount
{ "amount": "1250.00", "currency": "EUR" }

// Wrong — bare numeric value, precision loss risk
{ "total": 1250.50 }

// Correct date
{ "issue_date": "2026-03-15" }

// Wrong — numeric timestamp
{ "issue_date": 1742169600 }

schema.json is a JSON Schema Draft 2020-12 document bundled inside the SDF archive. Every .sdf file is self-validating: it carries its own schema, enabling validation decades after creation without network access.

Rules

• schema.json MUST be valid JSON Schema Draft 2020-12. The $schema keyword MUST be present and set to "https://json-schema.org/draft/2020-12/schema".
• External $ref URIs MUST NOT be used. All referenced sub-schemas MUST be bundled inline using JSON Schema $defs.
• Consumers MUST NOT fetch external resources during validation. Parsing and validation are offline operations.

visual.pdf is the human-readable PDF layer. It is generated from data.json by the producer. It must be fully self-contained and security-safe.

Self-Containment

• All fonts MUST be embedded. No system font references.
• All images and color profiles MUST be embedded.
• MUST NOT reference any external resources by URL.

Security

• Producers MUST NOT embed JavaScript, macros, or AcroForm scripts in visual.pdf.
• Consumers MUST NOT execute any scripts found in visual.pdf.
• Consumers SHOULD use a PDF renderer in a sandboxed environment.

SDF supports optional digital signatures via the signature.sig file. A signed SDF document provides cryptographic assurance that the four required layers have not been modified since signing.

Algorithms

What Is Signed

The signature covers the canonical content of all four required entries:

signing_input = SHA256(meta.json) || SHA256(data.json) || SHA256(schema.json) || SHA256(visual.pdf)
signature     = Sign(private_key, signing_input)

The concatenation order is deterministic and MUST NOT vary between implementations. signature.sig itself and vendor/* entries are not included.

signature.sig Structure

{
  "algorithm": "ECDSA-P256",
  "key_id": "tenant-key-2026-03",
  "signature": "<base64url-encoded signature bytes>",
  "signed_at": "2026-03-15T14:30:05+01:00"
}

SDF validation is a sequential pipeline. Each step MUST succeed before the next begins. A failure at any step produces a standard error code and halts validation.

Conformance Levels

The SDF version is declared in meta.json via the sdf_version field. The current version is 0.1.

Version Negotiation

• Consumers MUST reject documents with an sdf_version higher than their supported version with SDF_ERROR_UNSUPPORTED_VERSION.
• Consumers SHOULD accept documents with a lower sdf_version (forward compatibility).
• Patch releases (e.g. 0.1.1) are backward-compatible. Minor releases (e.g. 0.2) may introduce new optional fields. Major releases (e.g. 1.0) may introduce breaking changes.

All SDF error codes are defined here. Implementations MUST NOT invent new codes outside this list. New codes require a spec update via the GitHub repository.

This specification uses the following normative keywords per RFC 2119: