Contract version
Version 1.0 is the current public contract baseline.
Public calculator contract
The public calculator contract is the runtime-neutral boundary that adapters and delivery surfaces must consume. It is intentionally narrow so the public docs can explain what the calculator accepts and returns without duplicating formula logic.
Calculator identifiers
Stable lower-case names such as acute identify the calculator surface.
Pricing years
Use the four-digit IHACPA label form, for example 2025.
Batch schema
Section titled “Batch schema”The contract is batch-first. Adapters accept a batch envelope and return a batch result envelope. The row payloads stay runtime-neutral so Python, Rust, and future bindings can share the same public shape.
Request envelope
Section titled “Request envelope”calculator: lower-case calculator identifier such asacute.pricing_year: four-digit IHACPA year label such as2025.rows: array of input row objects.reference: year-scoped reference values required by the calculator.adjustments: batch-scoped adjustment inputs or override factors.
Each row must include the required input columns for the requested calculator. Adapters may ignore extra fields only when those fields do not affect contract validation.
Response envelope
Section titled “Response envelope”calculatorpricing_yearresults: row-aligned outputs, including any row-level validation errors.batch_errors: non-row-scoped errors such as unsupported calculators, missing reference bundles, or contract-level failures.
Acute contract
Section titled “Acute contract”Required inputs
Section titled “Required inputs”DRGLOSICU_HOURSICU_OTHERPAT_SAMEDAY_FLAGPAT_PRIVATE_FLAG
Required outputs
Section titled “Required outputs”NWAU25for pricing year2025
Validation shape
Section titled “Validation shape”- Contract violations should surface structured, explainable errors.
- Missing or invalid contract values should be rejected during contract construction.
- Missing input or output columns should surface explicit boundary errors.
Error mapping
Section titled “Error mapping”Adapters should map contract failures into stable, machine-readable codes and preserve the field path or row index whenever they can.
| Contract condition | Suggested code | Notes |
|---|---|---|
| Missing required batch field or row column | missing_required_field | Include the field path and row index. |
| Value has the wrong type or format | invalid_value | Include the field path and expected shape. |
| Calculator is not supported | unsupported_calculator | Use before any core execution starts. |
| Pricing year is not supported | unsupported_pricing_year | Use when the year is outside the published contract surface. |
| Required reference data is missing | missing_reference_bundle | Use when the adapter cannot resolve the shared reference payload. |
| Rust path is present but not opted in | experimental_calculator_disabled | Keep the Python fallback available. |
| Core execution raises an unexpected failure | internal_calculator_error | Keep stack traces out of user-facing docs. |
Adapter mapping
Section titled “Adapter mapping”Adapters may parse inputs, validate the contract, select the requested year, and format outputs.
Adapters must not:
- embed calculator math,
- hide source-bundle lookup behavior, or
- change the core schema for different delivery surfaces.
This same contract should remain consumable by Rust, Python, C#, web, Power Platform, R, Julia, Go, and TypeScript surfaces without changing the core schema.
Generation readiness
Section titled “Generation readiness”This contract shape is a good candidate for later OpenAPI or client model generation because it already exposes explicit schema versions, supported identifiers, required columns, and structured validation errors.
The machine-readable schema is published alongside this page at
/contracts/public-calculator-contract.v1.schema.json.