Technical / Overview

The DBNF-1 Specification

Dynamic Beverage Nutrition Facts — the complete technical standard for computing, formatting, and exchanging nutrition facts for made-to-order beverages, as ordered.

DBNF-1 · Version 1.0-draft Status: Working Draft License: open, royalty-free Reference impl.: BevFacts app

DBNF exists because the nutrition of a made-to-order drink is decided at the register — by size, sweetness level, syrup pumps, milk choice, and toppings — while every disclosure regime in force today describes a base recipe nobody actually ordered. DBNF closes that gap with three normative pieces: a label format consumers already know how to read, a deterministic calculation model any point-of-sale system can implement, and an interchange format with APIs so labels are machine-readable, addressable, and auditable.

The key words MUST, SHOULD, and MAY are used per RFC 2119 throughout. Content marked Live is implemented in the reference implementation today; content marked Draft is specified ahead of implementation and open for comment.

§Specification documents

PART 1

Label format

Geometry, typography, the element stack, print production (thermal & laser), the compact linear format for small labels, on-screen rendering, and accessibility.

PART 2

Calculation engine

The six-stage modifier pipeline, formulas, milk-substitution and topping reference tables, ice displacement, invariants, numeric precision, and test vectors.

PART 3

Rounding & daily values

Declaration rounding per 21 CFR 101.9(c), the DV tables, %DV computation order, declared-string grammar, warning thresholds, and edge-case vectors.

PART 4

Data model & schema

The DBNF document, entity definitions, the full JSON Schema (2020-12), canonical serialization rules, and document versioning.

PART 5

APIs

The live URL deep-link API and window.BevFacts JavaScript API; the draft REST API with auth, idempotency, pagination, webhooks, and error envelopes.

PART 6

QR & cup identity

QR payload forms, the dbnf1: URI scheme, cup ID grammar with Luhn mod-16 check digits, the lifecycle state machine, deposits, and privacy.

PART 7

Conformance

Levels L1–L3, the normative checklists, self-certification, the test suite, badge usage, and the versioning/governance policy.

§System architecture

A conforming DBNF system is three components with clean seams:

┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────────────┐
│ Recipe database │ ──▶ │  Calculation engine  │ ──▶ │  Presentation surfaces  │
│  base recipes   │     │  modifier pipeline   │     │  printed label (Part 1) │
│  modifier defs  │     │  (Part 2)            │     │  DBNF document (Part 4) │
│  (per vendor)   │     │  rounding (Part 3)   │     │  QR / APIs (Parts 5–6)  │
└─────────────────┘     └──────────────────────┘     └─────────────────────────┘

The seams are deliberate: a POS vendor can implement only the engine; a printer vendor only the presentation; a café only maintains recipes. Any component can be swapped as long as the interchange format (Part 4) is honored.

§Reading order

Implementing a label printer or POS plugin? Parts 2 → 3 → 1, then validate against the Part 7 checklist.
Integrating with BevFacts today? Part 5 (§1–2 are live), with Part 4 for the payload shape.
Building a cup deposit/return program? Part 6, then Part 5 §3 for the return endpoints.
Evaluating for policy or procurement? Part 7, then the Manifesto for the legislative context.

§Terminology

Term	Definition
Base recipe	The vendor's published nutrient vector for a drink at a named size, before any customization.
Modifier	A typed, ordered transformation of the nutrient vector (size scale, sweetness factor, syrup pump, espresso shot, milk substitution, topping).
Computed values	The unrounded output of the calculation pipeline for the as-ordered drink.
Declared values	Computed values after declaration rounding (Part 3) — what is printed.
DBNF document	The canonical JSON record of one as-ordered drink: base + modifiers + computed + declared (Part 4).
Nutrient vector	The 12-tuple: calories, total fat, saturated fat, trans fat, cholesterol, sodium, total carbohydrate, fiber, total sugars, added sugars, protein, caffeine.
Fleet	The set of returnable cups operated by one deposit program (Part 6).

§Changelog

Version	Changes
`1.0-draft.3`	Split the spec into Parts 1–7; added compact linear format, milk/topping reference tables, JSON Schema, webhook signatures, Luhn mod-16 check digits, conformance checklists.
`1.0-draft.2`	Single-page spec; live JS API (`window.BevFacts`); hashchange deep-link handling.
`1.0-draft.1`	Initial draft: label format, calculation, rounding, URL API.

Open the reference implementation Start with Part 1 →