generated from coulomb/repo-seed
114 lines
3.4 KiB
Markdown
114 lines
3.4 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
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.
|