# Schema reference [#schema-reference]

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

## CalculatorRunRequest [#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]

`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]

`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 [#runtime-graph]

```ts
Production: schema ownership

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

## Owning sources [#owning-sources]

* Calculator schemas: [`packages/calculators/src/schemas.ts`](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/packages/calculators/src/schemas.ts)
* Calculator error projection: [`packages/calculators/src/errors.ts`](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/packages/calculators/src/errors.ts)
* SDK schema re-exports: [`packages/sdk/typescript/src/schemas/index.ts`](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/packages/sdk/typescript/src/schemas/index.ts)

## Used by [#used-by]

* [Type safety](/sdk/type-safety)
* [API errors](/api/errors)
* [Error reference](/reference/errors)
* [Examples](/reference/examples)