Schema reference

Use this page when you need the canonical schema names for SDK, HTTP and test fixtures.

CalculatorRunRequest

CalculatorRunRequest is the public request body schema for a calculator run. It is owned by @taxkit/calculators.

Field	Type	Notes
`facts`	`CalculatorRunFacts`	A union of rule-owned scenario input schemas.
`jurisdiction`	optional `CalculatorJurisdiction`	Omit only when the selected calculator has one supported context.
`taxYear`	optional `CalculatorTaxYear`	Omit only when the selected calculator has one supported tax year.

The table describes the JSON form. In decoded TypeScript requests, context fields are nested Options: None for a missing key, Some(None) for a present undefined key, and Some(Some(value)) for a value. Use the owning request constructor to supply defaults; do not send Option objects as raw HTTP JSON. The same rule applies to optional help/filter fields and returned optional question, help and duplicate-provider permission fields.

The facts union is intentionally composed from canonical rule package schemas. Do not mirror request DTOs in application code when the SDK or API schema already owns the shape.

CalculatorRunResponse

CalculatorRunResponse is the canonical full run response.

Field	Type	Notes
`calculator`	`CalculatorCatalogItem`	Metadata for the selected calculator and context.
`diagnostics`	`CalculationDiagnostics`	Graph and calculation diagnostics returned by the engine.
`report`	`CalculatorRunReport`	The calculator-specific report union. SDK helpers narrow this through the descriptor output schema.

CalculatorServiceError

CalculatorServiceError is the expected calculator service failure union.

Error	When you see it
`CalculatorInputDecodeError`	Request facts do not match the selected calculator input schema.
`UnsupportedCalculatorError`	The requested calculator id is not in the public catalogue.
`UnsupportedCalculatorContextError`	The calculator exists, but not for the requested jurisdiction or tax year.
`CalculationError`	The calculation engine returned a source-backed domain failure.
`CalculatorCapacityExceeded`	The server has no free calculation place. Retry manually after the current work finishes.
`CalculatorOperationTimedOut`	The operation reached its time limit. Retry manually.
`CalculatorRateLimited`	The native per-client calculation limit was reached. Wait for `Retry-After` and retry manually.
`CalculatorAdmissionUnavailable`	The native request identity or rate limiter is unavailable. Retry manually.

Runtime graph

Production: schema ownership

SDK or HTTP caller
  -> CalculatorRunRequest
    -> CalculatorRunFacts
      -> rule-owned scenario input schema
    -> PublicCalculatorService.calculate
      -> CalculatorRunResponse
      -> CalculatorServiceError for expected failures

Owning sources

Calculator schemas: packages/calculators/src/schemas.ts
Calculator error projection: packages/calculators/src/errors.ts
SDK schema re-exports: packages/sdk/typescript/src/schemas/index.ts

Used by

Read this page as Markdown