145 lines
4.7 KiB
Markdown
145 lines
4.7 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
|
|
- optional customer assurance claims with typed tenancy-posture minimums
|
|
- 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: []
|
|
|
|
# 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.
|