Pricing Model Schema

Status: draft, implementation-facing.

Purpose

This document defines the canonical pricing-model schema now used by the repository runtime. It is the implementation companion to the conceptual vocabulary in research/PricingOntology.md.

The schema is designed to:

preserve compatibility with the Coulomb observatory MVP
represent richer pricing structures than a single subscription amount
support later validation, solver, and provider-publication milestones

Model Shape

Each pricing model contains:

identity and lifecycle metadata
normalized recurring access-fee fields for compatibility
explicit charge components
commitments
tunable parameters
optional customer assurance claims with typed tenancy-posture minimums
eligibility and provider hints
free-form metadata for deployment-specific details

Canonical Fields

id: string
name: string
model_type: flat_subscription | hybrid_subscription_usage | ...
lifecycle_phase: exploration | introduction | growth | maturity | saturation | decline
currency: EUR | USD | ...
status: active | candidate | retired
description: string

# Compatibility fields derived from the access component when omitted
access_fee_amount: decimal
access_fee_cadence: monthly | annual | one_time | ...
included_usage: string | null
overage_meter: string | null

charge_components:
  - id: string
    kind: access | setup | usage | support | discount | risk_adjustment
    amount: decimal | null
    cadence: string | null
    meter: string | null
    unit: string | null
    unit_price: decimal | null
    included_units: decimal | null
    label: string | null
    billing_treatment: recurring | metered | included | one_time | ...
    metadata: {}

commitments:
  - id: string
    kind: minimum_turnover | contract_duration | prepayment | committed_usage | ...
    value: string
    unit: string | null
    description: string

tunable_parameters:
  - key: string
    parameter_class: fixed | seller_controlled | customer_tunable | calculated | constrained | provider
    data_type: string
    description: string
    default_value: string | null
    min_value: decimal | null
    max_value: decimal | null
    options: []

# Optional. Absence means the tier makes no assurance claim.
assurance_claims:
  - id: string
    kind: isolation | availability | retention | performance
    customer_wording: string
    minimum_levels:
      I: 0..3
      A: 0..4
      E: 0..4
      P: 0..4
      R: 0..4
      V: 0..4
    delivering_service: string
    evidence_ref: string
    maximum_erasure_horizon_days: integer | null
    provider_contract_ref: string | null
    resource_governor_ref: string | null
    erasure_mechanism: row-deletion | key-destruction | null

eligibility:
  - string

provider_hints: {}
metadata: {}

Parameter Classes

fixed: immutable in the selected model
seller_controlled: adjustable only by the seller or internal workflow
customer_tunable: intended to become solver-visible customer choice
calculated: derived from other fields or economics
constrained: externally set but bounded by validation rules
provider: implementation-only parameter for execution backends

Validation Rules

Current runtime validation enforces:

model ids are unique
charge component ids are unique within a model
exactly one access charge component exists
access components define amount and cadence
usage components define a meter
hybrid_subscription_usage models include a usage charge component
tunable parameter keys are unique
customer_tunable parameters declare bounds or enumerated options
commitment ids are unique
assurance claim ids are unique and each claim names a supported kind, customer wording, typed in-range minimums, delivering service, and evidence
retention horizons are positive integers and erasure mechanisms use the canonical vocabulary

assurance_claims records the internal minimum that supports a customer-facing promise; it does not expose the framework ladder on a price page. The boundary engine checks coupled floors and wording, including E4/P3, retention horizons, resource-governed performance, and availability failure scope. Adding, changing, or removing a claim is assessed once at tier definition by assess_tier_definition_assurance(). An unchanged claim is not a per-campaign approval gate.

Transitional Compatibility

The Coulomb observatory still consumes access_fee_amount, access_fee_cadence, included_usage, and overage_meter. The canonical loader back-fills these from charge_components when the explicit top-level fields are omitted.

This keeps the current observatory stable while later milestones replace hard-coded observatory assumptions with generic pricing-core behavior.

4.7 KiB Raw Blame History