Specification, Draft 2.3
The Universal Model Protocol (UMP) is a shared language for marketing measurement. It lets a test result, a model and a budget plan pass between tools without losing what the numbers mean, so two analysts asking the same question reach the same answer, or can see exactly why they differ.¶
The problem. A budget decision rarely rests on one source. A marketing mix model says one thing, a geo test says another, a vendor sends a spend table, and the plan has to be set by Thursday. Each number can be right on its own and still be wrong to combine, because the numbers answer different questions: return against zero spend or against a 30% cut, two weeks of effect or full carryover. Section 1 tells the story that started UMP.¶
Where UMP sits. Tools never pass files to each other. Each speaks to one core through an adapter, and every crossing is a typed UMP object checked by a gate (section 3). Models, experiments and planners keep working as they do today; UMP is the layer between them that keeps the meaning attached.¶
Click any box to see what crosses there and which gates check it.
Evidence flows up
Drafts flow down; a named person approves
One adapter per tool
Models
Experiments and data
Tools never pass files to each other. Each one speaks to a single core through an adapter. Every crossing is a typed UMP object, and a gate checks it on the way through.
Models and tests keep working as they do today. The core keeps the meaning attached to every number: which question it answers, how sure it is, where it came from and how far it can be trusted.
The core does not fit models and does not make decisions. Machines draft; named people approve.
What every number carries.¶
- Its estimand: seven fields that say which question the number answers (section 5).¶
- Its uncertainty: an interval in a form that can be combined honestly, never a bare point.¶
- Its provenance: which model, test or plan produced it, and from which data (section 6).¶
- Its trust level: how far it got through the acceptance bar, and any fallback it used (section 14).¶
Gates degrade before they block. When two pieces of evidence do not line up, UMP gives the best answer it can still defend, widens the range to cover what it assumed, and labels the assumption. Only eight gates stop work outright, where going ahead would be unsafe: privacy, record integrity and approver identity, and agent tool separation (section 15). A decision made on a labelled best guess beats one made in an unlabelled spreadsheet.¶
Machines draft, people approve. UMP does not fit models and does not make decisions. It carries evidence to the people who do, lets an agent draft but never approve (section 17), and seals each approved decision in a log that anyone holding the published checkpoints and the log’s public key can check for tampering (section 18).¶
Click a step to open it. Click it again to close.
- UMP coreGates, lineage, events
One loop, eight steps. A model is fitted. Tests are ranked by what they could change, then designed and run. Their results calibrate the model, the budget moves, a named person decides, and the record is sealed. When the decision comes up for review, what really happened feeds the next fit.
Every step writes its work through the core: gates check it, lineage links it to what it was built from, and an event announces the change.
What is normative. The prose and the published JSON Schemas are normative; the Python packages are informative reference implementations. Where they disagree, the spec wins and the package has a bug. Section 21 explains how the spec, schema, registry and suite versions relate.¶
Where to start
Section titled “Where to start”| You are | Start with |
|---|---|
| A planner or marketing lead¶ | Sections 1, 5 and 12: the problem, what a number means, how a plan becomes a decision |
| An analyst or modeller¶ | Sections 5, 7, 8, 10 and 14: estimands, model tiers, fallback, calibration, the acceptance bar |
| An engineer building a tool¶ | Sections 2, 3 and 19: conformance classes, architecture, events and errors |
| Governance, risk or audit¶ | Sections 15, 17 and 18: gates, decision agents, integrity of records |
How to read this specification
Section titled “How to read this specification”Normative words. The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY and OPTIONAL in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals. Lower-case must, should and may carry their ordinary English meaning. Declarative statements in normative sections, and in paragraphs marked normative, define required behaviour. Sections 1, 22, 23 and 24, stories, worked examples and notes marked informative are informative. All other sections are normative unless marked. A requirement that names a gate ID is enforced by the gate engine at run time. A requirement that names neither a gate ID nor a requirement ID is tested by the conformance suite fixture family that covers its section (section 21). Requirement IDs (REQ-<section>-NN) are being assigned; the conformance checklist published with the suite maps each ID assigned so far to its classes.¶
Status of numbers in this draft. Thresholds marked proposed are starting values to be calibrated in the pre-rollout studies (section 22). They are not established standards, and the review says so too.¶