# Universal Paper > Universal Paper is a free, open language for group purchasing agreements between GPOs, suppliers and members. Every party holds the same agreement, every change is signed, and anyone can verify it offline. Created by Uppercentile, offered free under CC BY 4.0 and Apache-2.0. Universal Paper (UP) is a first-order language, not an application: a vocabulary, a grammar and a set of validity rules for agreements between group purchasing organizations (GPOs), suppliers and members. Every Term definition, Agreement, Event and State is identified by the SHA-256 hash of its canonical JSON (RFC 8785). Changes are Ed25519-signed Events with fixed transition rules. Any evaluator recomputes the same State, so every party holds the same truth. Private values can be sealed. AI agents act under bounded Mandates. The language never sets or suggests prices (axiom A6). Creator and steward: Uppercentile (https://uppercentile.com). Offered free to the market. Licenses: specification, Term library, docs and site text CC BY 4.0; code and JSON Schemas Apache-2.0; example agreements and traces CC0 1.0. No account, fee or license key is ever required. Current version: UP/0.1-draft (working draft; Terms not yet reviewed by counsel; all example parties and values are hypothetical). When citing, use: "Universal Paper, created by Uppercentile, https://universalpaper.org/". ## Pages - [Home and Playground](https://universalpaper.org/): what Universal Paper is, a vision of apps and agents built on it, an in-browser Playground, and conformance results - [Developers](https://universalpaper.org/developers/): primitives, the 16-Term library, code examples, the CLI and test vectors - [FAQ](https://universalpaper.org/faq/): plain-language answers for GPOs, suppliers, members and developers - [Licenses](https://universalpaper.org/license/): what is licensed how, and how to credit it - [Specification index](https://universalpaper.org/spec/) - [Source code and full repository](https://github.com/Uppercentile/universal-paper): spec, reference interpreter, JavaScript engine, examples, tests ## Specification (Markdown) - [Overview](https://universalpaper.org/spec/overview.md): What Universal Paper is, why universality buys speed, its engineered properties, design principles and boundaries (antitrust, enforceability, regulation). - [Domain](https://universalpaper.org/spec/domain.md): The things that exist in Universal Paper: canonical JSON and hashes, Identifier, Seal, Party, Role, Term, Agreement, Event, State, Mandate, Commitment and Bundle. - [Predicates and functions](https://universalpaper.org/spec/predicates-functions.md): What can be asked of a Universal Paper agreement: the predicates and functions every evaluator provides. - [Axioms](https://universalpaper.org/spec/axioms.md): The thirteen consensus rules (A1 to A13) that every valid Universal Paper agreement and event satisfies. - [Inference](https://universalpaper.org/spec/inference.md): How a State and an Event yield the next State: clause forms, exceptions and precedence, rendering and simulation. - [Lifecycle](https://universalpaper.org/spec/lifecycle.md): The agreement status model and the transition rule for every Event kind: who must sign and what must be true. - [Term library](https://universalpaper.org/spec/terms.md): The initial Universal Paper Term library: sixteen reusable, value-neutral clauses for GPO, supplier and member agreements. - [Mapping guide](https://universalpaper.org/spec/mapping-guide.md): How rosters, eligibility files and ASC X12 845, 844, 849 and 867 EDI sets map onto Universal Paper events. - [Neutrality charter](https://universalpaper.org/spec/neutrality-charter.md): Who owns Universal Paper (no one), how the steward discloses affiliations, and how the specification changes. - [Design notes](https://universalpaper.org/spec/design-notes.md): What was cut, merged or added while drafting Universal Paper, and the open questions for the steward. ## Optional - [Full specification in one file](https://universalpaper.org/llms-full.txt) - [JSON Schema](https://universalpaper.org/schema/universal-paper.schema.json) - [Example bundle: conventional GPO agreement](https://universalpaper.org/examples/conventional/bundle.json) ## FAQ ### The basics **What is Universal Paper?** Universal Paper is an open, first-order language for agreements between group purchasing organizations (GPOs), suppliers and members. It is a vocabulary, a grammar and a set of validity rules. It is not an application, a contract-management plug-in or a template library. Anyone can check an agreement written in it, offline, from the specification alone. (Source: spec/00-overview.md) **Who created Universal Paper, and who owns it?** Universal Paper was created by Uppercentile. Uppercentile offers it to the market for free, under open licenses, and acts as its steward rather than its owner. Nobody owns the language: anyone may use, implement, extend or fork it, for any purpose, without permission or payment. The neutrality charter commits the steward to publish its affiliations and to hand stewardship to a neutral body once the language has users across segments. (Source: spec/08-neutrality-charter.md) **Is Universal Paper free to use?** Yes. The specification, the Term library, the reference code and the example agreements are all free, including for commercial use. Using the language never requires an account, a payment, a license key or a connection to any particular company. The neutrality charter forbids the core from requiring any of those. (Source: spec/08-neutrality-charter.md §2) **What does "universal paper" mean?** Today each party contracts on its own paper: its own template, its own system and its own copy of the record, which then has to be reconciled with everyone else's. Universal Paper is paper that belongs to no party. The GPO, the supplier and each member use the same agreement form, each keeps its own copy, and every copy computes to the same answer about what was agreed, what state the agreement is in and what is owed. (Source: spec/00-overview.md §2) **What problem does it solve?** The same deal usually lives in three places: the GPO's system, the supplier's system and the member's system. Rosters, tiers, contract prices and administrative fees drift apart, and teams spend months reconciling them. Universal Paper replaces reconciliation with computation. Every change is a signed event, and every party recomputes the same state from the same events. **Is Universal Paper a product or a platform?** No. It is a language, in the way Incoterms, double-entry bookkeeping or GS1 identifiers are shared conventions. The software in the repository is a reference implementation of the language, never the language itself. Anyone, including Uppercentile, may build commercial products on it, but no product may claim to be the language or to be required to use it. (Source: spec/08-neutrality-charter.md §6) ### How it works **How can every party be sure they hold the same agreement?** Every Term definition, Agreement, Event and State is identified by the SHA-256 hash of its canonical JSON (RFC 8785). If two parties hold the same hash, they hold the same agreement, byte for byte. Change one character and the hash changes, so an edit can't go unnoticed. (Source: spec/01-domain.md §1) **How are changes to an agreement approved?** Each change is an Event signed with Ed25519 (RFC 8032). Every Event kind has a fixed rule that says who must sign and what must already be true. Validity is computed, not granted: every evaluator applies the same rules to the same events and reaches the same verdict. No central authority approves anything. (Source: spec/05-lifecycle.md · axioms A1 to A13) **What is a Term?** A Term is a reusable clause with typed parameters, such as an administrative fee, pricing tiers, a purchase commitment or a termination right. An agreement pins each Term by the hash of its definition, so later edits to the library never change an existing agreement. The initial library has sixteen Terms, including UP:Admin-Fee, UP:Tiers, UP:Sales-Reporting, UP:Fee-Disclosure and UP:Overlay. (Source: spec/06-terms/) **Can it calculate what each party owes?** Yes. From the chain of signed events, any evaluator can derive an agreement's status, current tier, contract prices and open obligations at any moment, for example the administrative fee due on a quarter's reported sales. The same events and the same evaluation time always give the same result. (Source: spec/04-inference.md · axiom A4) **Does Universal Paper use a blockchain?** No. It doesn't need a ledger, a network or a server. An agreement can be verified with the specification, a SHA-256 implementation and an Ed25519 verifier. A ledger or a hosted service could carry Universal Paper events, but the language depends on none of them. (Source: spec/00-overview.md §3) **Where do our agreements live?** With the parties. A bundle is plain JSON that you can keep in your contract system, ERP or a file share. Hosted services may store and route bundles for you, but nobody needs one to verify an agreement. (Source: spec/01-domain.md §12) **Do we have to renegotiate existing contracts?** No. The UP:Overlay Term describes a contract you already have, identified by its document hash, so you get computed obligations immediately while the signed document stays the governing one. (Source: spec/06-terms/UP-Overlay.md · spec/07-mapping-guide.md) **How do confidential prices stay private?** Any private value, such as a price, rate, roster or volume, can be replaced by a Seal: a salted SHA-256 commitment. Hashes and signatures cover the sealed form, so a party who sees none of the values still reaches the same verdicts and state hashes. Values are disclosed only to the parties who need them. (Source: spec/01-domain.md §3 · axiom A10) **Can AI agents act on behalf of a party?** Yes, within limits. A Mandate gives an agent its own key and bounds on the event kinds, Roles, Terms and values it may use. An event outside those bounds is invalid on arrival, for every party. (Source: axiom A9) **How does it work with EDI?** Side by side. The mapping guide shows how rosters, eligibility files and the ASC X12 845, 844, 849 and 867 transaction sets correspond to Universal Paper events. Existing identifiers such as GS1 GTIN and GLN, HIBCC HIN and NDC are reused, never replaced. (Source: spec/07-mapping-guide.md) ### For GPOs, suppliers and members **Does the language set or suggest prices or fees?** Never. Universal Paper standardizes process, definitions and compliance mechanics, not economics. No Term carries a default, suggested or typical value for any price, discount, fee, rate, threshold, volume or period. The parties supply every number. (Source: axiom A6 · spec/00-overview.md §7.1) **Is a Universal Paper agreement legally binding?** A Universal Paper agreement must still be a valid contract under the applicable law. Every agreement has a deterministic human-readable rendering suitable for signature, fixed by the same hash the parties sign. The language gives shared, verifiable truth about what was agreed and what state it is in. It does not replace courts. The current draft Terms have not yet been reviewed by counsel. (Source: spec/00-overview.md §7.2) **Does it address the GPO safe harbor in U.S. healthcare?** The fee Terms (UP:Admin-Fee and UP:Fee-Disclosure) can express the written-agreement and disclosure elements that GPO fee arrangements commonly need. The specification encodes no legal conclusion; whether a given agreement satisfies any law is a question for the parties and their counsel. (Source: spec/00-overview.md §7.3) **Is it neutral between GPOs, suppliers and members?** Yes, by design. Rules refer to Roles, never to specific organizations, and every Term reads the same whichever party reads it. The language favors no segment and depends on no company, including its creator. (Source: axiom A7 · spec/08-neutrality-charter.md) ### For developers **How do I try Universal Paper?** Open the Playground to write an agreement in your browser and watch its fingerprint, signatures and obligations update. To work locally, install the Python reference interpreter, which provides the up command (validate, apply, derive, simulate, render, trace, hash). The developer page walks through both. **How is the reference implementation tested?** About 170 tests cover every axiom, transition rule, clause form and Term. A second, independent engine in JavaScript must reproduce every Python trace, rendering and simulation byte for byte, and differential tests compare both engines on tens of thousands of random inputs. The results are published on the conformance section. **Can I write my own implementation?** Yes. The specification is the language, so any implementation that produces the same hashes and the same verdicts for the same events speaks Universal Paper. The example traces (CC0) and test vectors (Apache-2.0) are free to reuse for conformance testing. (Source: spec/03-axioms.md) ### Licensing and governance **What licenses does Universal Paper use?** All open licenses. The specification, Term library, documentation and this website's text are licensed under Creative Commons Attribution 4.0 (CC BY 4.0). The reference interpreter, the JavaScript engine, the JSON Schemas and the tools are licensed under the Apache License 2.0. The example agreements and traces are dedicated to the public domain under CC0 1.0. See Licenses for details. **Can I use Universal Paper commercially?** Yes. All three licenses allow commercial use, modification and redistribution, at no cost. CC BY 4.0 asks you to credit the source (for example, "Universal Paper, created by Uppercentile, CC BY 4.0"), link to the license and say if you changed anything. Apache-2.0 asks you to keep the license and notices with the code, and it includes a patent grant from contributors. CC0 asks for nothing. **Who governs the specification, and how does it change?** Uppercentile is the current steward. Each published version is immutable, and agreements pin one version, so a later change never alters an existing agreement. Changes are proposed through a public, numbered request-for-comment process and recorded in a public changelog. Detailed governance rules are still being defined. (Source: spec/08-neutrality-charter.md §4) **What is the current status of the specification?** Version UP/0.1-draft is a working draft. Until version 1.0, the meaning of the spec and the hashes of Term definitions may change. Every example on this site uses hypothetical parties, identifiers, prices and dates. (Source: spec/00-overview.md §9) --- # Full specification text (CC BY 4.0, by Uppercentile) # Universal Paper — Overview **Spec version:** `UP/0.1-draft` · **Status:** working draft, not stable · **License:** CC BY 4.0 > Provisional markers. Text tagged **[PROVISIONAL]** records an assumption made so drafting could continue. Each one ties to an open question in [DESIGN_NOTES.md](../DESIGN_NOTES.md#6-open-questions-for-the-steward) and may change. ## 1. What Universal Paper is Universal Paper (UP) is a first-order language for agreements between group purchasing organizations, suppliers, and members. It is a vocabulary, a grammar, and a set of validity rules. It is not an application, a contract-management plug-in, an editor, a template library, or a business. Tools, agents, and applications can be built on it later, by anyone. The core does not know or care what they are. ## 2. Thesis: universality in exchange for speed Today every party contracts on "its own paper". Bespoke paper gives the strongest party leverage over the terms, and over the record itself, because whoever runs the larger system holds the master copy. Universal Paper belongs to no party. In exchange for giving up bespoke paper, every party gets: - **Speed.** Nothing that doesn't matter needs redlining. - **Shared, verifiable truth** about what was agreed and what state it is in. - **Interoperability** with any system or agent that speaks the language. ## 3. The ontological test > If every piece of software disappeared tomorrow, would Universal Paper still exist and still work? It must. The models are Incoterms, double-entry bookkeeping, GS1 identifiers, and the bill of lading. This specification is the language. Software is a reference implementation of it. Concretely, a person with this document, a SHA-256 implementation, an Ed25519 verifier, and patience can check by hand whether an agreement is valid, what state it is in, and what is owed under it. Nothing in this spec may require a particular program, server, registry, or ledger. ## 4. Validity is computed, not granted As in a consensus protocol, the validity of an agreement, and of every change to it, is a property computed from intrinsic rules. Every evaluator applies the same rules to the same data and reaches the same answer. No authority approves anything. ## 4a. Lessons from prior art | Prior effort | What Universal Paper takes from it | |---|---| | Ricardian contracts | Prose and machine form bound to one hash ([A8](03-axioms.md)), plus the domain vocabulary they lacked. | | Common Paper, Bonterms, oneNDA | Cover page plus standard terms incorporated by reference (Agreement plus Term library), CC BY 4.0, and Term provenance for a future cross-segment drafting committee. | | Accord Project | Stay domain-specific. Six clause forms, not a general programming language. | | ISDA Common Domain Model | Model lifecycle events, not just documents, and adopt incrementally through mapping ([07](07-mapping-guide.md)) and overlays. | | MediLedger | Universal Paper is a language a network could speak, not a network. Confidentiality is designed in. | | TradeLens | Credible neutrality from day one ([08-neutrality-charter](08-neutrality-charter.md)). | | ASX CHESS replacement | Never lead with a ledger. The core is substrate-agnostic and small. | | GS1 in healthcare | Reuse existing identifiers through multi-scheme Identifiers. Never mint a competing scheme. | | Catala | Exceptions and precedence are first-class and deterministic ([04 §4](04-inference.md#4-exceptions-and-precedence), [A13](03-axioms.md)). | | Agent Payments Protocol (AP2) | A Mandate primitive for bounded delegated authority ([A9](03-axioms.md)). Universal Paper is the agreement layer payment protocols can reference. | ## 5. Engineered properties | Property | Meaning in this spec | |---|---| | Self-describing | An agreement, bundled with the Term definitions it pins by hash, carries its full meaning. ([01-domain §Bundle](01-domain.md#12-bundle)) | | Content-addressed | Every Term definition, Agreement, Event, and State is identified by the SHA-256 hash of its canonical JSON. ([01-domain §1](01-domain.md#1-encoding-canonical-form-and-hashes)) | | Self-validating | Validity is checkable offline, by anyone, without permission. ([03-axioms](03-axioms.md)) | | Intrinsic transition rules | Each Event kind has a fixed rule saying who must sign and what must be true. ([05-lifecycle](05-lifecycle.md)) | | Fault tolerant | The truth is the valid chain of signed Events, not any party's database. | | Deterministic | The same chain and the same evaluation time give the same State, for every evaluator. ([A4](03-axioms.md)) | | Confidential by construction | Prices, rosters, and volumes can be sealed field by field. Validity and every State hash can be checked from Seals alone. ([01-domain §3](01-domain.md#3-seal), [A10](03-axioms.md)) | | Describes before it replaces | An existing agreement can be expressed as an overlay, without renegotiation. ([UP:Overlay](06-terms/UP-Overlay.md), [07-mapping-guide](07-mapping-guide.md)) | ## 6. Design principles 1. **Minimal.** As few primitives as possible. Each primitive is a permanent commitment. 2. **Orthogonal.** Each primitive does one thing. 3. **Composable.** Complex agreements are built from simple ones, never special-cased. A member's participation is itself an Agreement that references another Agreement. 4. **Use-case blind.** The core has no concept of onboarding, simulation, or agents. 5. **Value-neutral.** The language can express a price, fee, rate, threshold, or period, but defines no default for any of them and never suggests one. 6. **Role-based.** Rules refer to roles, never to specific organizations. One party may hold several roles. 7. **Human- and machine-readable.** Every construct has a canonical machine form and a deterministic human rendering. Prose is a rendering of a Term, not the Term itself. ## 7. Boundaries ### 7.1 Antitrust Universal Paper standardizes **process, definitions, and compliance mechanics**. It never standardizes **prices or economic terms**. No Term in this specification, and no conforming Term library, may carry a default, suggested, typical, or recommended value for any price, discount, fee, rate, threshold, volume, or period. Every such value is a parameter that the parties supply. Examples in this repository use values that are explicitly hypothetical and carry no meaning beyond illustration. ([A6](03-axioms.md)) ### 7.2 Legal enforceability A Universal Paper agreement must still be a valid contract under the applicable contract law. The engineering guarantees shared, verifiable truth about *what was agreed* and *what state it is in*. It does not replace courts, and it does not decide disputes about facts in the world. Every agreement has a deterministic human-readable rendering suitable for signature ([04-inference §7](04-inference.md#7-rendering)), and the rendering is fixed by the same hash the parties sign. ### 7.3 Regulatory awareness In U.S. healthcare, GPO administrative fees are subject to the federal anti-kickback statute's GPO safe harbor. The fee Term family ([UP:Admin-Fee](06-terms/UP-Admin-Fee.md), [UP:Fee-Disclosure](06-terms/UP-Fee-Disclosure.md)) can express the written-agreement and disclosure elements that arrangements commonly need. The spec does not encode any legal conclusion. Whether a given agreement satisfies any law is outside the language. ### 7.4 Neutrality of voice Every Term rendering reads the same whichever party reads it. Renderings name roles ("the Supplier"), never "you" or "we", and never characterize one party's position favorably. ## 8. Document map | File | Contents | |---|---| | [01-domain.md](01-domain.md) | Things that exist: encoding, Identifier, Seal, Party, Role, Term, Agreement, Event, State, Mandate, Commitment, Bundle | | [02-predicates-functions.md](02-predicates-functions.md) | What can be asked of the domain | | [03-axioms.md](03-axioms.md) | Consensus rules that always hold | | [04-inference.md](04-inference.md) | How a State and an Event yield the next State; clause forms; rendering; simulation | | [05-lifecycle.md](05-lifecycle.md) | Agreement status model and the rule for every Event kind | | [06-terms/](06-terms/README.md) | Initial Term library | | [07-mapping-guide.md](07-mapping-guide.md) | How rosters, eligibility files, and X12 EDI sets map onto Universal Paper | | [08-neutrality-charter.md](08-neutrality-charter.md) | Who owns the language (no one) and how it is governed | ## 9. Versioning and governance [PROVISIONAL] Each spec version is immutable once published. An Agreement declares exactly one spec version ([A1](03-axioms.md)). Changes are proposed through a public RFC-style process and recorded in a public changelog ([08-neutrality-charter](08-neutrality-charter.md)). The brief names Uppercentile as steward (not owner). The name the spec is published under is an open question (see DESIGN_NOTES). Version strings take the form `UP/.[-draft]`. A Term definition's hash changes whenever its text changes, so an Agreement that pins a hash is unaffected by later edits to the library. # 01 — Domain The domain is the set of things that exist in Universal Paper. | Kind | Name | Authored or derived | Section | |---|---|---|---| | Primitive | **Party** | authored | §4 | | Primitive | **Role** | closed vocabulary | §5 | | Primitive | **Term** | authored in the Term library | §6 | | Primitive | **Agreement** | authored by parties | §7 | | Primitive | **Event** | authored and signed by parties or their agents | §8 | | Primitive | **State** | derived from a chain of Events | §9 | | Primitive | **Mandate** | authored and signed by a principal Party | §10 | | Value primitive | **Identifier** | a reference into an existing scheme | §2 | | Value primitive | **Seal** | a salted commitment to a confidential value | §3 | | Derived | Commitment | derived from a State at a time | §11 | | Container | Bundle | packaging for offline verification | §12 | Seven primitives, two value primitives, one derived object. Candidates from the first-pass draft that are no longer primitives: **Tier** became a Term built on the *Selection* clause form, **Attestation** became an Event kind, **Item** became an Identifier, and **Signature** became part of the encoding. Reasons are in [DESIGN_NOTES.md](../DESIGN_NOTES.md). --- ## 1. Encoding, canonical form, and hashes ### 1.1 Canonical JSON Every object is a JSON object. Its **canonical form** is its serialization under RFC 8785 (JSON Canonicalization Scheme, JCS), encoded as UTF-8. To keep canonical forms identical across languages: - JSON numbers MAY appear only as integers in the range −(2⁵³−1) to 2⁵³−1. Every other number (prices, rates, quantities with fractions) is a **Decimal** string (§2). As in RFC 8785, a number is a value, not a spelling: `100`, `100.0` and `1e2` are the same integer and canonicalize as `100`. A number with a fractional part, NaN, or Infinity is invalid. - Object keys are ASCII. - Strings MUST NOT contain unpaired surrogates (I-JSON, RFC 7493, on which RFC 8785 relies). - `null` is not used. An absent optional field is omitted. - A JSON text with a duplicate key in one object is invalid. (The reference CLI rejects such files when it reads them.) ### 1.2 Content hash `hash(o) = "sha256:" + lowercase-hex( SHA-256( JCS( strip(o) ) ) )` `strip(o)` removes the top-level field `sigs`, if present. No other field is removed. Signatures therefore never change the identity of what they sign. Every hashed object carries `"type"` and `"spec"` fields, so two objects of different types or spec versions can never share a hash. Confidential values are always hashed in their **sealed** form (§3). The hash of an object is therefore the same for a party that sees every value and for one that sees none. ### 1.3 Keys and signatures - A **public key** is written `"ed25519:" + lowercase-hex(32 bytes)`. - A **signature** is an Ed25519 signature (RFC 8032) whose message is the **32 raw bytes** of the SHA-256 digest inside `hash(o)`. - Signatures are attached in a top-level `sigs` array of `{ "key": PublicKey, "sig": "", "mandate"?: Hash }`, sorted by `key`. `mandate` is present when the signer is an agent acting under a Mandate (§10). A signature is valid iff it verifies under its key for the hash of the object it is attached to, under these **strict** rules, which every implementation applies identically: 1. The key matches `ed25519:[0-9a-f]{64}` and the signature matches `[0-9a-f]{128}` (lowercase only, no whitespace). 2. The key is canonically encoded (its y-coordinate is less than p = 2²⁵⁵ − 19) and is **not of small order**. The eight points of order dividing 8 have the y-coordinates 0, 1, p − 1, and the two values listed in `src/universal_paper/crypto.py`. A key that is one of them would let anyone produce "signatures" that verify, so it is never a valid Party or agent key, and an Agreement that lists one is invalid (A1). 3. R (the first 32 bytes of the signature) is canonically encoded (y < p), and S (the last 32 bytes, little-endian) is less than the group order L. 4. The verification equation is the cofactorless one of RFC 8032 §5.1.7: [S]B = R + [k]A. Without these rules, two correct Ed25519 libraries can disagree about edge-case signatures, and two evaluators would then disagree about validity (A4). --- ## 2. Value types | Type | Form | Notes | |---|---|---| | Hash | `"sha256:<64 lowercase hex>"` | §1.2 | | PublicKey | `"ed25519:<64 hex>"` | §1.3 | | Time | RFC 3339 UTC, second precision, `Z` suffix, e.g. `"2027-01-01T00:00:00Z"` | Years 0001 to 9999. A real calendar date and a time of 00:00:00 to 23:59:59. ASCII digits only. No time zones or fractional seconds | | Decimal | String matching `-?(0\|[1-9][0-9]*)(\.[0-9]+)?`, at most 64 characters | No exponent, no leading `+`, ASCII digits only | | Amount | `{ "value": Decimal, "currency": "" }` | Currency is three uppercase ASCII letters | | Rate | Decimal, as a fraction (`"0.025"` is two and a half percent) | | | Period | `{ "unit": "day"\|"month"\|"quarter"\|"year", "count": int }` | count from 1 to 10 000. Arithmetic in [04-inference §2](04-inference.md#2-time-and-period-arithmetic) | | Rounding | `{ "scale": int, "mode": "half-even"\|"half-up"\|"down"\|"up" }` | scale from 0 to 18. No default ([04-inference §6](04-inference.md#6-arithmetic)) | | int | A JSON integer from 0 to 2⁵³ − 1 | Counts such as `max_renewals` | | string | Any JSON string | Free text. Sealable | | Name | A non-empty string that other fields refer to | Clause names, option (tier) names. Structural, never sealed | | **Identifier** | `{ "scheme": string, "id": string }` | See below | | ClaimType | `"/"` | e.g. `"UP:Tier-Selection/selects"` | | ChainId | Hash | The hash of a chain's genesis Event (§8.3) | | **Seal** | `{ "seal": "sha256:<64 hex>" }` | §3 | ### Type expressions Term parameters (`params..type`) and claim data fields (`claims..data.`) declare their types with a small expression language, which every evaluator parses the same way: - a type name from the table above (`Time`, `Period`, `Decimal`, `Rate`, `Amount`, `Identifier`, `Hash`, `ChainId`, `Role`, `Rounding`, `string`, `Name`, `int`); - `[T]`, a list of T; - `{a: T, b: U}`, an object with exactly those fields; - `{: T}`, a non-empty object whose keys are chosen by the parties (for example tier names) and whose values are T; - `"x" | T | …`, one of several alternatives, where `"x"` is a literal string. A value has a type only if it matches it exactly (no extra or missing fields). A Seal may stand in place of an `Amount`, `Rate`, `Decimal`, `string`, or an Identifier's `id`, and nowhere else (§3.3). A TermDefinition that uses an unrecognized type expression is invalid (A1). ### Identifier A typed reference to a Party, location, or Item in an **existing** identifier scheme. Universal Paper never mints a competing scheme. - `scheme` names the scheme: for example `GTIN`, `GLN`, `HIN`, `DEA`, `NPI`, `340B`, `NDC`, or `DUNS`. The list is open, because schemes exist outside the language. A scheme name is matched exactly, case-sensitively. - `UP:Local` is reserved for something with no external identifier. Its `id` is meaningful only inside the Agreement that uses it, which must describe it. - A Party or Item may carry several Identifiers. Two Identifiers refer to the same thing only if scheme and id are equal. The language never infers that a HIN and a GLN name the same facility. An **Item** is just an Identifier used where an Item is expected. --- ## 3. Seal A salted hash commitment to a confidential value. A Seal proves that a value exists and has not changed, while the value stays hidden from anyone who has not been given it. ### 3.1 Sealing To seal value `v` (any JSON value): 1. Choose a fresh 32-byte random `salt`, written as 64 lowercase hex characters. A salt is never reused. 2. `seal(v, salt) = { "seal": "sha256:" + hex( SHA-256( JCS( { "salt": salt, "value": v } ) ) ) }` The Seal object then appears **in place of** the value, everywhere: in the Agreement, in Event bodies, in State. Every hash and every signature covers the sealed form. The salt is what stops a reader from guessing a low-entropy value (a price, a rate) by hashing candidates. ### 3.2 Disclosure A **Disclosure** reveals one sealed value to whoever receives it: ```json { "seal": "sha256:…", "salt": "<64 hex>", "value": } ``` It is valid iff recomputing `seal(value, salt)` gives `seal`. Disclosures are never hashed into an Agreement or Event. They travel separately, to the parties who need each value. Because every field is sealed separately, each can be revealed on its own. ### 3.3 What may be sealed Only values that are commercially sensitive and that no validity check depends on: | May be sealed | May not be sealed (structural) | |---|---| | Amount, Rate, Decimal quantities, free-text strings (descriptions, bases, conditions), Identifier `id`s inside claim data and Agreement parameters | Roles, PublicKeys, Times, Periods, Roundings, ints, Hashes, ChainIds, ClaimTypes, Names (clause names, option names), Term ids, Event kinds, and every field of a Mandate's scope other than its bounds | This split is what makes [A10](03-axioms.md) achievable: every validity check reads only structural fields. Values that depend on sealed fields (a price, a fee amount, whether a payment covered it) are **computed values**. An evaluator without the Disclosure reports them as `sealed`, and still agrees with everyone on validity and on the State hash. ### 3.4 Forward compatibility The `"sha256:"` prefix names the commitment scheme. A later spec version may add schemes that support zero-knowledge proofs (for example, range proofs over committed amounts) under a new prefix, without changing the shape of any object. --- ## 4. Party Any entity that can sign. ```json { "key": "ed25519:…", "name": "Hypothetical Health Purchasing Alliance", "ids": [ { "scheme": "GLN", "id": "0614141000005" } ] } ``` - A Party **is** its public key. `name` and `ids` are labels. They become binding only when every party signs an Agreement that pairs them with that key. - A Party may be a person, an organization, or software acting for either. The language does not distinguish them. Software that acts *for* a Party with bounded authority does so through a Mandate (§10). - One Party may hold several Roles in one Agreement. Party is not a hashed object on its own. It appears inside an Agreement. --- ## 5. Role The function a Party performs **within a specific Agreement**. `Role ∈ { aggregator, supplier, member }` **[PROVISIONAL: closed set of three; see open question 4]** | Role | Function | |---|---| | aggregator | Aggregates demand and contracts on behalf of members (the GPO function). | | supplier | Provides Items. | | member | Buys Items under an aggregator's agreement. | A Role is held relative to an Agreement. The same Party may be a member in one Agreement and an aggregator in another. New Roles can be added only by a new spec version. --- ## 6. Term A canonical unit of meaning with a stable ID. Terms live in the Term library ([06-terms/](06-terms/README.md)), not inside individual agreements. This is incorporation by reference: the Agreement is the cover page (parties and variables), and Terms are the standard terms it incorporates. ### 6.1 Term definition ```json { "type": "TermDefinition", "spec": "UP/0.1-draft", "id": "UP:Admin-Fee", "title": "Administrative fee", "params": { "": { "type": "", "doc": "…" } }, "forms": [ …clause forms (04-inference §3) bound to parameters… ], "claims": { "": { "data": {…}, "doc": "…" } }, "render": "…rendering template (04-inference §7)…", "provenance": { "drafted_by": "…", "reviewed_by": [ { "segment": "aggregator" | "supplier" | "member", "reviewer": "…", "date": Time } ], "supersedes"?: Hash, "change_note"?: "…" } } ``` - `id` is stable across spec versions. A changed meaning gets a new id. - `params` declares every parameter by name and value type. **A Term definition MUST NOT declare a default value for any parameter.** There is no field for one. ([A6](03-axioms.md)) - `forms` is the machine definition, expressed only in the clause forms of [04-inference §3](04-inference.md#3-clause-forms). - `render` is the human definition. It is part of the hashed definition, so the prose is fixed by the same hash as the machine meaning ([A8](03-axioms.md)). - `provenance` records who drafted the definition, which segments' counsel reviewed it, and the previous version it replaces. Following `supersedes` links gives the version history. It exists so a future cross-segment drafting committee can give the library legitimacy. Provenance is part of the hash, so a review is recorded by publishing a new version of the definition. ### 6.2 Clause A **Clause** is a Term applied with parameter values inside an Agreement. It is not a separate primitive. ```json { "n": "fee", "term": "UP:Admin-Fee", "def": "sha256:…", "params": { … }, "over"?: [ "" ] } ``` - `n` is a local name, unique within the Agreement. - `def` pins the exact Term definition by hash. - `params` binds every declared parameter. A sealable parameter value may be a Seal. - `over` declares this Clause an **exception** that takes precedence over the named Clauses where they conflict ([04-inference §4](04-inference.md#4-exceptions-and-precedence)). --- ## 7. Agreement A composition of Clauses binding Parties in Roles. ```json { "type": "Agreement", "spec": "UP/0.1-draft", "parties": [ { "role": "aggregator", "party": { "key": "ed25519:…", "name": "…" } }, { "role": "supplier", "party": { "key": "ed25519:…", "name": "…" } } ], "clauses": [ …Clauses… ], "label": "optional free text" } ``` - `parties` is sorted by `(role, key)`. Every Party listed is a **required signer**. - An Agreement references another agreement's chain only through a Clause built on the Link form ([04-inference §3.6](04-inference.md#36-link)). There is no special "sub-agreement" construct. - An Agreement may **describe** an existing paper contract rather than replace it, by including an [UP:Overlay](06-terms/UP-Overlay.md) clause ([property 8](00-overview.md#5-engineered-properties)). - An unsigned Agreement is a **draft**. Drafts are just data. --- ## 8. Event Something that happens to an Agreement: a signed, timestamped, hash-linked record. ```json { "type": "Event", "spec": "UP/0.1-draft", "kind": "propose" | "accept" | "attest", "chain": "", // omitted on the genesis event "prev": "", // omitted on the genesis event "at": "