Portable format reference

Archive profile

A .denframepack is a ZIP archive with a fixed end-of-central-directory record at the end. Use one disk, ordinary 32-bit ZIP sizes, no archive comment, and regular file entries with no extra fields or comments. Entries use STORED or DEFLATE with an expansion ratio of at most 100:1. Names are unique, including after case folding. Encryption, links, directories, ZIP64 and executable content are refused.

V1 contains exactly manifest.json and definition.json at the root. V2 contains those two documents and exactly the resources declared in the definition. Resource names are assets/<lowercase SHA-256>.<png|jpg|webp|mp3>. No path traversal, undeclared files or remote-resource substitutes are accepted. The end record and directory budgets are checked before entry allocation.

The manifest uses format “denframepack”, entrypoint “definition.json”, a schema_version of 1 or 2, an id, version and definition_sha256. The definition schema version agrees with its manifest. The limits below count bytes, entries and decoded pixels separately.

JSON and canonical bytes

Documents are UTF-8 JSON without a byte-order mark, duplicate keys, NaN or Infinity. Keys and text cannot contain C0/C1 controls, DEL, or bidi embedding, override and isolate characters U+202A–U+202E and U+2066–U+2069. Ordinary right-to-left text and joiners remain valid. Strings are never Unicode-normalized.

A definition may carry localized: its name, mood and description in other languages, keyed by a canonical locale (a lowercase language, an optional title-case script, an optional uppercase region or three-digit area: bg, pt-BR, zh-Hant-TW, es-419), at least one and at most 16. Each entry has at least one of name (up to 100 characters), mood (60) and description (240), none blank: each needs a character that is neither whitespace nor a format character (zero-width spaces and joiners alone are blank); the same plain-text rules apply. Hosts show the page’s language where it is present and fall back to the base words field by field. A definition with localized requires localized-text-v1, a host token that no screen needs.

V1 hashes the raw definition.json bytes; equivalent whitespace can therefore produce a different digest. V2 requires the definition to equal its canonical encoding, with every model default written explicitly, including empty lists, objects and null values. Both use SHA-256 expressed as 64 lowercase hexadecimal characters. An archive digest hashes the entire ZIP and is a separate identity.

• Validate the model and expand defaults, then recursively sort object keys by Unicode code point. Preserve array order.
• Use commas and colons with no separator whitespace, and no final newline.
• Write UTF-8 characters directly. Escape quotation marks, backslashes and JSON control characters with JSON string escaping; reject unpaired surrogates.
• Write integers as decimal integers and booleans/null as their lowercase JSON literals. V2’s only number field is duration_seconds: a finite value from 0.01 through 30, using the shortest round-tripping decimal with a fractional digit. Thus 30 becomes 30.0 and 0.01 remains 0.01; no exponent notation is needed.
• V1 canonical author output preserves the historical omission of unauthored appearance fields and default block styles. Absent purpose/arrangement/localized, absent localized fields, absent source suggestions, empty setup lists and an empty portrait map are omitted too; existing release bytes stay unchanged. Its accepted non-strict boolean/integer values are normalized by the native model. Pack fields, portable overrides and explicitly strict appearance fields remain strict.

The shared conformance corpus pins defaults, Unicode ordering, duration boundaries and native/browser agreement. Browser inspection reports separate archive, JSON, schema, capability and contrast verdicts. Media and publisher trust remain “not checked”; an accepted preflight never grants installation or decoding permission.

Identity, versions and trust

An id is handle/name, at most 100 characters, matching ^[a-z0-9][a-z0-9.-]*/[a-z0-9][a-z0-9.-]*$. Use your own namespace. denframe/ and catalog-listed ids require authenticated catalog identity. local/ identifies an unsigned export from some Denframe; it does not establish ownership on another host.

Versions are exact three-part numeric strings, at most 30 characters. V2 uses ASCII digits; the legacy v1 schema accepts Unicode decimal digits. Version ranges and “latest” are not references. Published bytes for an id and version are immutable. V1 dependency locks contain an id, exact version and definition digest; cards also pin an archive digest and activity. Schema versions and dashboard revisions are separate numbers.

V1 license is MIT, CC0-1.0 or CC-BY-4.0; CC-BY requires attribution. V2 records credits per resource, with an attribution or license notice for MIT and CC-BY. A publisher string and a valid hash are claims, not authentication. The host verifies signed catalog provenance separately, refuses conflicting unsigned identities, and labels ordinary file imports as shared. Online catalog refresh and offline signature proofs are not part of this format-tool release.

Themes and appearance

A theme has kind “theme” and empty blocks/source_slots. Choose a compiled look and optional appearance values; theme tokens overlay that look’s base palette. All colors are six-digit hexadecimal values prefixed with #. The complete merged palette must clear the contrast gate below.

Token roles: accent, accentText, background, border, captionSurface, mutedText, negative, positive, surface, text. Appearance vocabulary, defaults and limits are generated under the field reference. Layouts, backgrounds, fonts and styles name compiled behavior; packages cannot contain custom CSS, HTML, JavaScript, remote fonts or local media/source identifiers.

Blocks and content collections

A block preset contains exactly one instance; a content collection contains one to twelve ordered instances. Instance and source-slot ids are unique. Every declared source slot is used, and each referencing block has the same kind as its slot. All non-clock, non-card blocks require a source slot. Cards use exact content references instead. A slot carries a portable capability, never household credentials or bindings.

A source slot may suggest a kind matching its own and an optional public preset id: image accepts bundled-open-art or the-met-open-access-highlights; news accepts nasa-jpl-space. Suggestions never contain household ids, credentials or configuration. Content layouts may carry setup prompts with source_slot, field and required (default false): weather accepts city and units, market accepts watchlist. Slot/field pairs are unique and carry no answers. Suggestions, setup and portable image mat_style require layout-setup-v1. Image mats use modern, museum, full_bleed or shadow_box.

Compiled kinds: calendar, card, clock, custom, guest, home, image, market, meal, media, news, notes, package, tasks, transport, weather. Placement carries region and importance hints. A content layout may also declare purpose (glance, gallery, home or media) and an arrangement behind layout-arrangement-v1. Its landscape map names every block on a 12 × 6 grid; an optional portrait map overrides cells on a 6 × 12 grid. Each cell requires col_start, row_start, col_span and row_span, must fit, and cannot overlap another authored cell. Arrangements require appearance.layout = grid. Without a portrait override, the shared renderer derives portrait from landscape. Only market instances carry symbol queries, with distinct symbols. Styles use typed fields and omit default values in v1 author output.

The reserved settings.overrides object carries choices for the kinds below. It is validated strictly; null fields and empty objects are removed. Household profile_ids never travel. Card settings use their own schema. Other settings are refused.

A custom block may declare settings.responsive with at least one of glance, line, compact or full. Each form names distinct item fields: value, label, unit, status or detail. A row may join up to three other distinct fields, never itself. Vital/hero rows use one line. Legacy hero/secondary roles map to vital/incidental; the original vocabulary is preserved unless any row uses a v2 role. Defaults and remaining row/form limits are in the field reference.

Capability admission

Declare each required token once. Missing triggered capabilities are refused; unsupported requirements prevent activation on the host or receiver. Extra unneeded tokens produce a warning. The last column is the first format toolchain release (format-v…) whose validator admits the token; a Denframe host admits it once it carries that toolchain.

The full contrast gate

Each pair below requires a contrast ratio of at least 4.5:1. Convert every sRGB channel c from a byte to c/255, then linearize with c/12.92 when c ≤ 0.04045, otherwise ((c + 0.055)/1.055)^2.4. Luminance is 0.2126R + 0.7152G + 0.0722B. Contrast is (lighter + 0.05)/(darker + 0.05), evaluated before display rounding.

For the picture scrim, light text means luminance(text) > luminance(background). Inverse-linearize the captionSurface luminance L: g = 12.92L when L ≤ 0.0031308, otherwise 1.055L^(1/2.4) − 0.055, with L clamped to [0,1]. The gray byte is 255g. Raw alpha is 1 − g for light text and g otherwise; round alpha upward to two decimal places. Composite black over a white pixel for light text, or white over black otherwise. Round the resulting byte half upward and clamp to [0,255]; that gray is the scrim surface tested above. Report a failing ratio rounded downward to two decimal places.

The v1 stored model retains its older pairs without scrim so older data can load. New import/author validation applies the full gate. Download the algorithm and conformance vectors as palette-contrast.json.

Multimedia v2 and media validation

A pack contains declared locales, unique items, resources and reveal-sequence-v1 activities. Each item supplies every declared locale, with prompt and reveal faces. Images require alternative text. Audio cues declare a locale, phase, narration/effect role and transcript. Activities reference existing items in order; every item and resource is used. Current sequences provide prompt, recall, reveal and dwell timing; they do not implement scored answers or learner accounts.

An art collection is a v2 definition of kind gallery, required capabilities pack-format-v2 and gallery-pack-v1. It declares a landscape or portrait shape, a default presentation (fit, mat, placard and cadence seconds), a WebP strip of its first works and up to 200 works. Each work names its JPEG image and WebP thumbnail, alternative text, its pixel size and the orientation that size gives, which must match the collection’s shape, a focal point, an average colour, a placard (title, creator, date, institution and canonical HTTPS link, with medium and dimensions when known) and its rights: CC0 only, with the provider’s field, value, image URL and observation time as evidence. Every resource is used and dedicated CC0. A host installs a collection into its gallery; a screen never receives the pack.

Each resource’s path, SHA-256, length and media_type must agree. Images are PNG, JPEG or WebP, match their bytes, contain one frame, and fit the decoded-pixel/working-set budget and 20,000-pixel side limit. Validation inspects metadata before loading pixels. PNG allows IHDR, PLTE, tRNS, IDAT and IEND; WebP allows VP8, VP8L, VP8X and ALPH. JPEG allows ordinary image segments and a standard JFIF header without thumbnails, and refuses COM and APP1–APP15 metadata. No trailing metadata is accepted.

MP3 uses complete MPEG Layer III frames, at least two, with a supported sample rate and non-free bitrate. The actual duration must match the declared duration within 0.1 seconds. ID3v2.3/v2.4 may contain one plain-text TSSE encoder tag; no other tags, flags, footer, ID3v1 or trailing data. The ID3 tag including its header is bounded to 4,096 bytes and the TSSE frame payload to 1,024 bytes. Frame validation stops once duration exceeds 30 seconds plus the encoder tolerance.

Playback is separate from import. Sound requires the screen’s explicit audio policy. Every animated transition honors prefers-reduced-motion. Browser preflight only checks bounded structure and image headers; native media validation runs before any imported media reaches a renderer.

Limits and field grammar

Byte counts are integers, with 1 KiB = 1,024 bytes and 1 MiB = 1,048,576 bytes. Constants below come from the native validator. Storage, staging, jobs and window/checkpoint limits are host/runtime budgets rather than extra archive fields.

Every schema field’s range, length, pattern and explicit default is listed below. Optional fields with model factories expand to their model’s defaults during canonical encoding. Object models reject extra properties; settings and token dictionaries have their separate allow-lists above. JSON Schema describes structure; cross-reference, capability, contrast and media checks still apply.

Download the contracts

• composition/block-instance.schema.json
• composition/content-ladder.schema.json
• composition/local-composition.schema.json
• composition/package-manifest.schema.json
• composition/portable-definition.schema.json
• packs/audio-policy.schema.json
• packs/card-settings.schema.json
• packs/definition.schema.json
• packs/gallery-definition.schema.json
• packs/manifest.schema.json
• vocabulary.json
• Pack capability inventory
• Generated reference tables

Composition schemas include the portable format and the local composition/block-instance contracts. Local-only bindings are not permitted in portable definitions; portable arrangements carry only bounded cell coordinates keyed by authored block ids. The schemas, vocabulary, generated tables and contrast vectors are served directly from the same contracts used by Denframe.

Author and validate

Install the standalone tool from its tagged release in the public library repository with python -m pip install "denframe-format @ git+https://github.com/atanasster/denframe-library@format-v0.3.0#subdirectory=format", or download the wheel attached to the format-v0.3.0 release. It has no dependency on the host application. Start a theme, block, content collection or text-only pack, then validate and build:

denframe-author new theme studio/my-theme /tmp/my-theme.json --name "My theme"
denframe-author validate /tmp/my-theme.json
denframe-author build /tmp/my-theme.json /tmp/my-theme.denframepack
denframe-author validate /tmp/my-theme.denframepack --json
denframe-author inspect /tmp/my-theme.denframepack
denframe-author unpack /tmp/my-theme.denframepack /tmp/unpacked

denframe-author new pack studio/my-pack /tmp/my-pack.json --name "My pack"

The source wrapper accepts id, version and definition, plus optional publisher, slug and explicit manifest metadata. Explicit manifests preserve attribution, dependencies and publisher. Put pack assets beside the source under their digest filenames. Build and unpack refuse to overwrite existing outputs. Validate does not install or authenticate a publisher.

The repository wrapper scripts/library-author.py provides the same commands and renderer previews with synthetic data. Use preview --activity, --locale and --item for packs, or --forms for block variants. Test import, source binding, use, updates and removal in a disposable host; preserve exact dependency archives when sharing. To offer a finished file to the Denframe Library, use Submit an asset: it runs the browser checks above and opens a summary-only public issue.

• Download theme source JSON
• Download block source JSON
• Download content source JSON