OpenPricing Data Specification

Version: draft-01 Status: Draft Date: 2026-06-17

Abstract

OpenPricing defines a provider-independent format for representing the pricing and packaging of a service: its features, the meters that measure usage, the packages (plans) it offers, the rate cards that price each feature within a package, and the add-ons, discounts, credit grants, and qualifying conditions that apply. A document in this format — the OpenPricing object — represents one provider's pricing model using a fixed, vendor-neutral vocabulary, so that pricing models from different providers share a common representation.

A document MAY be produced by any means, including manual authoring and extraction from a published pricing page. The format does not depend on how a document is produced.

This specification is the normative contract for the document. It is intended for:

• Producers that emit documents in this format, by any means.
• Consumers that read documents in this format.
• Validators that check a candidate document for conformance.

The contract is expressed as a JSON Schema ($id https://openpricing.io/draft-01/schema.json, drafted against JSON Schema 2020-12). This document defines the data model that the JSON Schema encodes: the meaning, value format, nullability, and cross-field requirements of every field. The JSON Schema constrains the shape of each field; this specification additionally states the referential and cross-field requirements that a conformant document MUST satisfy and that validation of fields in isolation does not capture. Both are normative.

Status of This Document

This is a draft specification. The specification identity is draft-01:

While the specification is in draft, fields, defaults, and constraints MAY change between revisions without a formal deprecation cycle, and backward compatibility of documents is not guaranteed between draft revisions. The Migration and Versioning section describes the policy that applies once the specification stabilizes.

This document and the JSON Schema artifact describe one contract. A disagreement between them is a defect to be reconciled; neither takes precedence over the other. Any change to a field, default, value format, allowed value, or requirement is a change to this specification.

Scope

This specification covers the structure, field semantics, value formats, and conformance rules of a single OpenPricing document.

In scope:

• The structure and meaning of every object, field, enumeration, and primitive in the document.
• The required-field and default-value conventions.
• The value formats for keys, numerics, currencies, durations, dates, and URLs.
• The referential-integrity and cross-field requirements a conformant document must satisfy.
• Versioning of the specification.

Explicitly out of scope:

• Hidden or contractual pricing logic. A document describes a provider's published pricing and packaging model, not privately negotiated terms, internal rate sheets, or undisclosed billing-engine behavior.
• Runtime billing computation. The document describes how a feature is priced; it does not specify how a billing system meters events, rates usage, applies proration, or settles invoices.
• Storage, transport, and provenance. How a document is serialized to a file, persisted, diffed, scraped, or extracted is not constrained by this specification. A conformant document is valid regardless of how it is produced or stored.
• Companion documents. Any provider metadata or change-history documents that an implementation may keep alongside a catalog have their own schemas and are not part of this specification.

Design Goals and Principles

1. Provider independence. A fixed, vendor-neutral vocabulary (service categories, meter aggregations, price types, entitlement types, condition operators) represents the pricing of any service in a single model, independent of how a given provider presents it. Documents from different providers share one representation and are interoperable without per-provider adapters.
2. One contract. A single data model governs all producers and consumers. The JSON Schema artifact and this specification describe that model and are kept in agreement.
3. Conformance as an invariant. A conformant document satisfies the full contract — both the per-field constraints and the cross-field requirements. A producer that cannot satisfy the contract does not emit a partial document.
4. Explicit over implicit. Every field is required. A field with a documented default is emitted with that default value (null, "", []) rather than omitted, so that an absent field and a field set to its default are never ambiguous. See Normative Language and the required-field convention.
5. Stated values only. A document represents the pricing model as the provider states it. Where a fact is not stated, the corresponding field carries its documented null or empty default; a producer does not infer or invent a value.
6. Extension through attributes. Provider-specific data that has no first-class field is carried as attributes key-value pairs rather than dropped, and does not occupy a typed field.
7. Alignment with metering and billing systems. Metering and pricing concepts (meters, aggregations, entitlements, graduated/volume tiers, credit grants) correspond to the primitives of usage-metering and billing engines, so a document maps onto such a system without re-modeling, yet the model is not specific to any one of them.

Terminology

Normative Language

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

Normative and informative content

Unless explicitly marked as non-normative, this specification is normative. Examples, JSON snippets, and explanatory text introduced with "For example" are informative: they illustrate the normative requirements and do not create conformance requirements beyond the stated MUST, SHOULD, and MAY statements. Where an example and a normative requirement appear to conflict, the requirement governs.

Required-field convention

Every field on every object is REQUIRED, including fields that have a documented default. A producer MUST emit each field explicitly rather than omitting it:

• A nullable field MUST carry JSON null when no value is stated. The key MUST NOT be dropped.
• A field MUST NOT use the JSON string "null" in place of the JSON literal null.
• A string field whose default is "" MUST carry "" when no value is stated. A producer MUST NOT invent text to fill it.
• An array field whose default is [] MUST carry [] when no entries are stated.

This format favors canonical, validator-friendly documents over sparse, source-preserving ones. A fully-populated document has a fixed shape: a consumer reads any field without testing for its presence, and "absent" never has to be distinguished from "set to its default". A producer that extracts from a pricing page MUST normalize an unstated value to the field's documented default (null, "", or []) rather than omit the field. Documents therefore carry explicit null, "", and [] for facts the source does not state; this is intended, not a defect.

Throughout this document, the Requirement column and the per-field Requirements sections use "REQUIRED" to mean "the key MUST be present"; nullability is stated separately. A field may be both REQUIRED (present) and nullable (its value MAY be null).

Feature levels

Each field and rule carries a feature level that maps to the normative keywords above:

Every field is REQUIRED to be present, so the presence obligation is Mandatory for all fields. The distinctions among fields are therefore expressed through nullability (whether the value MAY be null) and the conditional cross-field rules in Document Requirements.

Conformance

A document is conformant with this specification when it satisfies, together:

1. Field requirements — every field is present, correctly typed, within its value format and length bounds, draws from its allowed values, and respects its nullability, as defined in Value Formats and each field's table and Requirements.
2. Document requirements — the referential-integrity and cross-field rules in Document Requirements (R1–R16) hold across the whole document.

Both sets of requirements are normative. A document that satisfies the per-field rules but violates a document requirement (for example, a rate card that references a feature key absent from features) is not conformant.

Conforming actors

Document Requirements

These requirements constrain relationships across fields and objects — references that must resolve, keys that must be unique, and fields whose obligation depends on another field's value. They cannot be expressed by validating one field in isolation, so they are stated here as document-level rules. Each rule carries a feature level: Mandatory and Conditional rules are MUST-level (Conditional meaning the MUST applies only when the stated condition holds), and Recommended rules are SHOULD-level.

Rules R15 and R16, and the enumerated form of R12, are introduced in draft-01 by this specification. They constrain a conformant document beyond what the per-field JSON Schema expresses; a producer MUST satisfy them, and a document that violates them is non-conformant whether or not a given validator checks them.

A consumer SHOULD treat a document that satisfies every field requirement but violates a document requirement as structurally readable yet not catalog-complete, and SHOULD surface the violation rather than acting on the affected portion.

Rate-card cadence relationships

R12 governs a rate card whose billing_cadence differs from its package's. The divisor relationship applies only when both the package cadence and the rate-card cadence are ISO 8601 Durations; the BillingCadence values "one_time" and "negotiated", on either side, are non-recurring or custom terms and never participate in R12. Usage measured on the rate card's cadence aggregates up into the package's billing period, so the rate-card Duration cadence MUST be a sub-period that composes a whole number of times into the package period. To keep this check mechanical and free of calendar arithmetic, the allowed (package cadence → rate-card cadence) pairs are enumerated rather than derived by dividing one ISO 8601 duration by another:

A rate-card cadence equal to the package cadence is always allowed; it is expressed as null. A pair not listed above is non-conformant. For example, a package cadence of P1M with a rate-card cadence of P1W is non-conformant, because a week does not compose a whole number of times into a calendar month. A package or rate-card cadence outside this enumeration is not defined for cross-cadence rate cards in draft-01; a rate card whose cadence is outside the enumeration MUST equal its package cadence.

Companion taxonomy overrides

An implementation MAY annotate a catalog (in a companion metadata document, outside this specification) with overrides to its assigned service_category / service_subcategory. Where such an override mechanism exists, each override MUST name a value drawn from the ServiceCategory or ServiceSubcategory vocabulary defined here and MUST carry a non-empty human-readable reason. The override document's own structure is out of scope.

Data Model

An OpenPricing document is a single nested JSON object. Its structure is:

OpenPricing (root)
├── service_category / service_subcategory   (taxonomy enums)
├── features[]            Feature   ── meter_key ─────────┐
├── meters[]              Meter     ◄─────────────────────┘
├── custom_currencies[]   CustomCurrency
├── packages[]            Package
│   ├── rate_cards[]      RateCard ── feature ──► Feature.key
│   │   ├── price         Price        (one of: free|flat|unit|graduated|volume|custom)
│   │   ├── entitlement   Entitlement  (one of: included|limit|configuration)
│   │   ├── discount      Discount?    (one of: percentage|usage)
│   │   ├── unit_config   UnitConfig?
│   │   ├── commitments   SpendCommitments?
│   │   └── conditions    Conditions
│   ├── credit_grants[]   CreditGrant
│   ├── available_addons[] ── key ──► Addon.key
│   └── conditions        Conditions
└── addons[]              Addon
    ├── rate_cards[]      RateCard
    └── credit_grant      CreditGrant?

Shared identity fields. The root object and each named, referenceable object — OpenPricing, Feature, Meter, Package, and Addon — carry the same four identity fields: key, name, description, and attributes. They are defined once as the Resource fields and are not repeated in each object's field table.

Cross-references. All references are by Key string, never by embedding the referenced object:

• a feature's meter_key → a meter's key
• a rate card's feature → a feature's key
• a package's available_addons[] → an add-on's key
• a credit grant's feature_scope[] → a feature's key
• any custom currency / credit grant unit code → a custom currency's code

Every cross-reference MUST resolve; see Document Requirements.

Orthogonality of price and entitlement. On every rate card, price specifies how each unit is billed and entitlement specifies what the customer receives. Both are REQUIRED and independent; their valid combinations are described under RateCard.

Array order. Array order is not semantically meaningful except for the arrays named below. Only these carry order meaning:

• packages, and a package's or add-on's rate_cards, preserve the provider's presentation order (for example, free before pro before enterprise). A consumer MAY render them in document order.
• A graduated or volume price's tiers are order-sensitive and MUST be ordered by up_to_amount per R11.

For every other array in the document, order is not meaningful: a consumer MUST NOT assign meaning to it, and a producer MAY emit it in any order, including sorted by key (or, for entries without a key, by serialized value).

The rest of this specification defines each object and its fields. Each object section opens with a Containment line stating where instances appear and what one instance represents.

Value Formats

These formal definitions are referenced by the per-field tables. Where a field's type is one of these, the format rule below applies in full. Each value-format rule carries a stable identifier (VF-…) so that a validator can report a violation by rule ID; the identifiers do not change between specification revisions once assigned.

Key

Rule ID: VF-KEY-001

A cross-resource identifier.

Lowercase letters, digits, and single underscores between segments. Producers SHOULD prefer full, human-readable names over abbreviations (monthly_active_users, not mau). Uniqueness of a key within its collection is a document requirement (R3), not a value-format rule.

Numeric

Rule ID: VF-NUM-001

An arbitrary-precision number encoded as a string.

All monetary amounts, tier bounds, percentages, conversion factors, limits, and credit amounts are Numeric. They MUST be encoded as JSON strings, never JSON numbers, to preserve precision. A producer MUST NOT emit 0.029; it MUST emit "0.029".

URL

Rule ID: VF-URL-001

An absolute HTTP or HTTPS URL.

DateTime

Rule ID: VF-DTM-001

Duration

Rule ID: VF-DUR-001

BillingCadence

The billing cadence shared by Package.billing_cadence and RateCard.billing_cadence. A union of a Duration and two string literals, plus null:

"negotiated" is an extractable fact (the page says terms are custom), distinct from null (silence). A producer MUST NOT use null to mean "negotiated". CreditGrant.cadence uses the subset Duration | "one_time" | null: a grant is never "negotiated".

CurrencyCode

Rule ID: VF-CUR-001

A union of two string subtypes:

The 3-character versus 4-or-more-character length distinguishes a fiat code (USD, as in "$10 in credits") from a custom code (CREDITS, as in "300 provider credits"). A custom code used anywhere MUST be declared in top-level custom_currencies (R10).

Attributes

Rule ID: VF-ATTR-001

A flexible list of string key-value pairs for metadata that does not fit a first-class field.

Producers MUST prefer typed fields over attributes and MUST NOT use attributes to carry commercial logic that belongs in a typed field. Consumers MUST ignore unrecognized attributes keys. This is the format's extension mechanism.

Within a single array of this Attributes format — any attributes field, and EntitlementConfiguration.values — key values MUST be unique. A consumer MAY therefore treat one such array as a string-to-string map.

Condition and Conditions

A Condition is a structured qualifier; Conditions is an array of conditions combined with logical AND.

Condition fields:

ConditionOperator allowed values:

Use conditions for region, deployment model, audience, model, or quantity qualifiers rather than encoding those rules in attributes. Examples:

• region in ["us", "eu"]
• deployment_model in ["cloud", "self_hosted"]
• model eq "gpt-5.5"

Objects

Each subsection below defines one object. The Containment line states where instances appear and what one instance represents. Field tables use these columns: Column ID (the JSON field name), Type, Requirement (REQUIRED — the key MUST be present), Nullable (whether the value MAY be null), Default, and Description.

Resource fields

Description

The four common identity fields shared by the root object and by each named, referenceable object — OpenPricing, Feature, Meter, Package, and Addon. These fields appear inline on each such object; "Resource fields" is a naming shorthand, not a separate object in the document.

Containment

Present on the root object and on every Feature, Meter, Package, and Addon.

Fields

OpenPricing (root object)

Description

The root object. It carries provider identity (the shared identity fields), service taxonomy, the provider and pricing-page URLs, and the five top-level collections that the rest of the catalog references: features, meters, custom currencies, packages, and add-ons.

Containment

The single root object. One instance per provider catalog.

Fields

Notes

• A document with empty features or packages may satisfy every per-field rule, but it is not conformant: R2 requires at least one of each.
• Packages encode commercial variants (monthly vs annual, region-specific, enterprise) as separate package objects connected by shared feature keys, with a naming convention such as pro_monthly / pro_annual. A single offering uses the bare name (pro).

Allowed Values — ServiceCategory

The highest-level classification. Exactly one value per catalog.

Allowed Values — ServiceSubcategory

A secondary classification namespaced as <category>.<subcategory>, so each value's parent is unambiguous. The chosen value's parent prefix MUST match service_category (R13). Use the <category>.other member when no specific subcategory fits within the chosen category, and the top-level other.other when the category itself is other. The complete enumeration, grouped by parent service_category:

ai_and_machine_learning

analytics

business_applications

compute

databases

developer_tools

identity

integration

internet_of_things

management_and_governance

media

migration

mobile

multicloud

networking

security

storage

web

other

Feature

Description

A distinct capability or billable dimension. Features are defined once in the top-level features collection and referenced by rate cards via the feature key. A metered (usage-based) feature also references a meter and may narrow it to a specific slice with conditions.

Containment

OpenPricing.features[]. One instance per distinct billable capability across the whole catalog.

Fields

Notes

For example, the meter_conditions for a "GPT-5.5 input tokens" feature on a tokens meter are [{key:"model",operator:"eq",value:"gpt-5.5"},{key:"type",operator:"eq",value:"input"}].

Meter

Description

Defines how raw usage events are aggregated into a billable quantity. One meter can be shared by several features that filter on different dimensions.

Containment

OpenPricing.meters[]. One instance per usage-event aggregation definition.

Fields

Allowed Values — MeterAggregation

A meter SHOULD set value_property for every aggregation except count, which operates on the event itself. The "requires value_property" column above states this expectation; count is the sole aggregation for which value_property MAY be null.

CustomCurrency

Description

Declaration of a provider-specific currency (credits, points). Declared once here and referenced by code wherever a CurrencyCode is accepted.

Containment

OpenPricing.custom_currencies[]. One instance per proprietary currency.

Fields

Package

Description

A bundle of rate cards with a single currency and billing cadence, plus optional trial, bundled credit grants, available add-ons, and applicability conditions. A package corresponds to what a pricing page usually labels a "plan" or "tier"; this format uses the name Package.

Containment

OpenPricing.packages[]. One instance per commercial package variant, such as a monthly Pro plan or an annual Pro plan; monthly and annual are separate packages.

Fields

currency has no schema-level default and MUST be emitted explicitly. billing_cadence, trial_period, and variant_of default to null but, like every field, MUST still be present.

Addon

Description

An optional, on-demand purchasable extension to a package — extra features or capacity. Add-ons are defined once in top-level addons and referenced from packages via available_addons.

Containment

OpenPricing.addons[]. One instance per purchasable extension.

Fields

currency has no schema-level default and MUST be emitted explicitly. max_quantity defaults to null (unlimited) but, like every field, MUST still be present — as an integer ≥ 1 or null.

A single-instance add-on (max_quantity = 1) — e.g. "Enterprise support" — may be added once; a multi-instance add-on (max_quantity > 1 or null) — e.g. additional seats or custom domains — may be added repeatedly to raise an entitlement limit.

RateCard

Description

The pricing-and-entitlement entry for one feature within one package or add-on, typically corresponding to a single cell in a pricing table. price and entitlement are orthogonal and both REQUIRED: price specifies how each unit is billed; entitlement specifies what the customer receives.

Containment

Package.rate_cards[] and Addon.rate_cards[]. One instance per priced feature within one package or add-on, qualified by its conditions. The same feature MAY appear in more than one rate card of the same package when each instance carries different conditions (for example one rate card for region=us and another for region=eu). A consumer resolving the price of a feature in a package MUST use the rate cards' conditions to select the applicable instance.

Fields

Allowed Values — PaymentTerm

payment_term is nullable: when the source does not state the billing timing, it is null, and a producer MUST NOT default it to either value.

Price × Entitlement combinations

Both are required and independent. Common combinations:

No percentage price. Take rates, revenue share, and cost-plus margins are a unit price over a currency-denominated meter: the meter reports the base value (payment volume, net license fees, upstream cost) and the unit amount is the multiplier — "0.029" for a 2.9% take rate, "0.30" for a 30% revenue share, "1.1" for a 10% cost-plus margin. A separate discount percentage (the DiscountPercentage model) is unrelated and concerns price reductions, not this multiplier.

Effective currency

A rate card has an effective currency, resolved as:

1. rate_card.currency, when non-null;
2. otherwise the currency of the containing package or add-on.

The containing package or add-on currency is non-nullable, so the effective currency is always defined. Every currency-denominated Numeric amount within the rate card is interpreted in the effective currency: the amount of a flat or unit price, the flat_price and unit_price amounts of graduated and volume tiers, PriceCustom.estimated_amount, and commitments.minimum_amount / commitments.maximum_amount. A tier's up_to_amount is a quantity bound, not a monetary amount, and is not interpreted in any currency.

The effective currency does not apply to amounts that carry their own denomination or are not monetary: a credit grant's amount and max_balance are denominated in the grant's own unit; DiscountPercentage.percent is a ratio; and DiscountUsage.units is a quantity of usage units, not a monetary amount.

Discriminated Unions

Price, Entitlement, and Discount are discriminated unions. The discriminator is an inline type property on the object — the variant is not wrapped in a named envelope. A unit price is serialized as:

{ "type": "unit", "amount": "0.20" }

It is NOT wrapped as { "unit": { "amount": "0.20" } }. A consumer MUST select the variant by reading the type property.

Price

Discriminator: type (PriceType). Variants:

PriceCustom. qualifier is a short commercial-posture label (contact_sales, negotiated, contract_required, quote_only). estimated_amount carries an indicative starting price when the page shows one, else null.

Choosing how to represent an unclear or non-standard price. A price is always present and typed; the representation depends on what the source states:

A null value is used for an unstated optional field (for example payment_term or a rate-card currency override), not in place of a price. attributes records non-commercial annotation and structural detail that no typed field captures; it does not substitute for a price type.

Graduated vs Volume.

• Graduated — each tier's rate applies only to units within that tier's range (marginal). "First 10k at X, next 40k at Y."
• Volume — the total quantity selects a single tier whose rate applies to all units. "Once usage reaches this tier, that rate applies to every unit."

PriceTier

Used by graduated and volume prices.

Tier-structure rules (R11): a graduated or volume price MUST contain at least one tier; tiers MUST be ordered lowest→highest; the final tier MUST have up_to_amount = null and no other tier may; each tier MUST carry flat_price, unit_price, or both.

Entitlement

Discriminator: type (EntitlementType). Variants:

EntitlementLimit. Use for a fixed included allowance or a usage cap. A soft threshold that continues with paid overage is modeled as a PriceUnit rate card with a DiscountUsage, not as this entitlement. usage_period is the allowance reset cadence when it differs from the billing cadence (P1D for "100 generations per day" on a monthly plan); null inherits the rate-card or package cadence. A rate limit needs no extra field: value plus usage_period (PT1M) already expresses "100 requests per minute".

scope names what the cap applies to when it is not organization-wide, e.g. "project" for Neon's "100 CU-hours per project". null reads as organization-wide (the default reading of an unscoped limit). It is an open string, not a closed enum, because providers scope caps unpredictably; recommended values are project, user, workspace, database.

Discount

Discriminator: type (DiscountType). At most one discount per rate card. Variants:

DiscountUsage is meaningful only for usage-based features and is the canonical way to encode an "included allowance, then paid overage" pattern alongside a PriceUnit.

DiscountUsage.units is expressed in the rate card's billing units: the unit the price operates on, after any unit_config conversion. When the rate card has a unit_config, the free allowance is counted in converted units, not raw quantity. units and the price amount are therefore stated in the same unit. For example, on a rate card priced per million tokens (unit_config divide by 1000000, display_unit "M"), a free allowance of five million tokens is DiscountUsage { units: "5" }, not units: "5000000".

Supporting Models

UnitConfig

Description

Unit conversion applied before pricing and entitlement comparison, letting a rate card bill in a transformed unit (per GB, per million invocations) while the feature is described in its natural unit (bytes, raw invocations).

Containment

RateCard.unit_config (nullable).

Fields

Computation: for divide, billed = raw / conversion_factor; for multiply, billed = raw * conversion_factor.

Allowed Values — UnitConfigOperation

Allowed Values — UnitConfigRoundingMode

SpendCommitments

Description

Published commitments for a rate card: spend floors and caps in the rate card's effective currency, plus the one quantity floor (minimum_quantity).

Containment

RateCard.commitments (nullable).

Fields

The floor applies per rate card. When both are stated, the smallest bill is max(minimum_amount, minimum_quantity × unit price), and the two floors compose (a plan can carry both a platform fee and a seat minimum). Encode a stated quantity minimum as minimum_quantity, never as a derived minimum_amount.

CreditGrant

Description

A prepaid value pool bundled with a package or granted by an add-on purchase. Emit a credit grant only when the page names a credit-like currency (credits, points, tokens) that one or more features draw from. A single feature's included quota is an EntitlementLimit or DiscountUsage, not a credit grant.

Containment

Package.credit_grants[] and Addon.credit_grant (nullable).

Fields

Common patterns: "resets monthly, no rollover" → cadence P1M, expires_after P1M; "150 credits daily" on a monthly plan → cadence P1D; "credits roll over, valid two years" → expires_after P2Y; "500 signup credits, one-time" → cadence "one_time".

Common Attributes

Rules that apply uniformly across many fields:

• Strings. UTF-8. name fields are 1–256 chars; description fields are 0–1024 chars with a "" default. Producers MUST NOT invent text for an empty description.
• Decimals / numerics. All numeric quantities are Numeric strings. A Numeric field MUST NOT be a JSON number. The two integer fields (Addon.max_quantity, UnitConfig.precision) are JSON integers within the IEEE-754 safe-integer range.
• Dates / times. DateTime is RFC 3339 in UTC.
• Durations. Duration is ISO 8601 (P…).
• Currencies. CurrencyCode; custom codes MUST be declared (R10).
• Nulls. null denotes "not stated". The string "null" is not a valid substitute. A nullable field MUST be present with value null, not omitted.
• Arrays / objects. Empty collections are emitted as [], present and explicit.
• Attributes. Attributes is [{key,value}] with both values string-typed, used for extension data only.

Extensions

The object shapes are closed: a conformant document MUST NOT add keys that this specification does not define to any object. Provider-specific data that has no first-class field is carried in the attributes array ([{key,value}]) present on every object that has the shared identity fields and on RateCard.

Rules for extension data:

• Producers MUST place provider-specific qualifiers in attributes, not in an undefined field.
• Producers MUST NOT use attributes for commercial logic that a typed field already models (price, entitlement, discount, unit_config, conditions, commitments).
• Consumers MUST ignore attributes keys they do not recognize and MUST NOT reject a document for carrying unfamiliar attribute keys.
• New first-class vocabulary (a new enum member, a new field) is a change to this specification, released through versioning, not carried in attributes.

Validation Rules

A validator checks a candidate document against this specification and classifies each violation. The two classes of rule are independent; a validator SHOULD check both and SHOULD report each violation with the JSON path of the offending value.

A field violation can be detected by inspecting a single value against its definition. A document violation requires looking at more than one field or object at once (a reference and its target, a key and its siblings, a price type and a feature's meter_key). Both render a document non-conformant; the distinction is informational, to help a validator locate and explain the failure. Conformance does not depend on any particular validator implementation.

Validator profiles

A tool that validates OpenPricing documents conforms to one of two profiles. A tool MUST state which profile it implements.

The JSON Schema (drafted against JSON Schema 2020-12) expresses the field requirements but cannot express the referential-integrity and cross-field requirements R1–R16. A schema validator therefore accepts documents that a conforming OpenPricing validator rejects. A tool that checks only the JSON Schema MUST NOT describe its result as full OpenPricing conformance.

Examples

Minimal conformant catalog

A flat-priced single plan with one included feature:

{
  "key": "acme",
  "name": "Acme",
  "description": "",
  "attributes": [],
  "service_category": "developer_tools",
  "service_subcategory": null,
  "provider_url": "https://acme.example",
  "pricing_page_url": "https://acme.example/pricing",
  "features": [
    {
      "key": "core_platform",
      "name": "Core platform",
      "description": "",
      "attributes": [],
      "meter_key": null,
      "meter_conditions": []
    }
  ],
  "meters": [],
  "custom_currencies": [],
  "packages": [
    {
      "key": "pro",
      "name": "Pro",
      "description": "",
      "attributes": [],
      "currency": "USD",
      "billing_cadence": "P1M",
      "trial_period": null,
      "rate_cards": [
        {
          "feature": "core_platform",
          "price": { "type": "flat", "amount": "20" },
          "entitlement": { "type": "included" },
          "unit_config": null,
          "billing_cadence": null,
          "currency": null,
          "conditions": [],
          "discount": null,
          "commitments": null,
          "payment_term": "in_advance",
          "attributes": []
        }
      ],
      "credit_grants": [],
      "available_addons": [],
      "conditions": []
    }
  ],
  "addons": [],
  "last_updated": null
}

Metered feature with a graduated price

The fragments below show a metered token feature and a graduated unit-priced rate card. The meter aggregates a tokens property by sum; the feature narrows it to a model+direction slice; the rate card prices it per million tokens via unit_config.

{
  "meters": [
    {
      "key": "tokens",
      "name": "Tokens",
      "description": "",
      "attributes": [],
      "event_type": "token_usage",
      "value_property": "tokens",
      "aggregation": "sum",
      "dimensions": ["model", "type"]
    }
  ],
  "features": [
    {
      "key": "gpt_5_5_input_tokens",
      "name": "GPT-5.5 input tokens",
      "description": "",
      "attributes": [],
      "meter_key": "tokens",
      "meter_conditions": [
        { "key": "model", "operator": "eq", "value": "gpt-5.5" },
        { "key": "type", "operator": "eq", "value": "input" }
      ]
    }
  ]
}

A graduated rate card for that feature, billed per million tokens:

{
  "feature": "gpt_5_5_input_tokens",
  "price": {
    "type": "graduated",
    "tiers": [
      { "up_to_amount": "10", "flat_price": null, "unit_price": { "type": "unit", "amount": "1.25" } },
      { "up_to_amount": null, "flat_price": null, "unit_price": { "type": "unit", "amount": "1.00" } }
    ]
  },
  "entitlement": { "type": "included" },
  "unit_config": {
    "operation": "divide",
    "conversion_factor": "1000000",
    "rounding": "none",
    "precision": null,
    "display_unit": "M"
  },
  "billing_cadence": null,
  "currency": null,
  "conditions": [],
  "discount": null,
  "commitments": null,
  "payment_term": "in_arrears",
  "attributes": [{ "key": "model_id", "value": "gpt_5_5" }]
}

Take rate (no percentage price type)

A 2.9% payment-processing take rate, modeled as a unit price over a currency-denominated meter (payment_volume in USD), the unit amount being the multiplier:

{
  "feature": "payment_processing",
  "price": { "type": "unit", "amount": "0.029" },
  "entitlement": { "type": "included" },
  "unit_config": null,
  "billing_cadence": null,
  "currency": null,
  "conditions": [],
  "discount": null,
  "commitments": null,
  "payment_term": "in_arrears",
  "attributes": []
}

Schema Artifact

This specification is accompanied by a machine-readable JSON Schema that encodes the per-field portion of the contract — the field set, types, value formats, length bounds, allowed values, and nullability defined above. It is identified by:

Validating a document against the JSON Schema checks the field requirements. It does not check the document requirements (R1–R16), which constrain relationships across fields and objects; those are checked separately. A document is conformant only when it satisfies both. The JSON Schema and this document describe one contract; a divergence between them is a defect to be reconciled.

Canonical Encodings

One blessed encoding per otherwise-ambiguous construct, so two producers do not legitimately diverge:

Migration and Versioning

• Identity. The specification's identity is the JSON Schema $id, https://openpricing.io/draft-01/schema.json. The version segment (draft-01) advances when the contract changes incompatibly.
• During draft. While the version is draft-01, the contract MAY change without a deprecation cycle, and documents are not guaranteed to remain valid across draft revisions. A producer re-emits a document against the current revision rather than relying on in-place migration.
• Field lifecycle. Adding a new enum member or a new union variant is additive for existing documents. Because every field is REQUIRED, adding a field is not backward compatible for producers (they must now emit it) even though consumers tolerate it; such changes are batched into a version bump.
• Stabilization. When the specification leaves draft, a stable $id version (e.g. v1) is assigned, introduced and deprecated fields carry an "Introduced In" marker, and a defined compatibility and deprecation policy replaces the re-emit approach described above.
• Introduced In. Every field and enum member in this specification was introduced in draft-01.

Changelog