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
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: []

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

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.

3.4 KiB Raw Blame History