# Naming and schema standards [#naming-and-schema-standards]

Use this page when you add public or package-facing names for facts, rules,
calculators, HTTP requests or SDK helpers.

## Use canonical owners [#use-canonical-owners]

| Contract                                                                     | Owner                               |
| ---------------------------------------------------------------------------- | ----------------------------------- |
| `FactId`, fact descriptors and shared fact contracts                         | `@taxkit/core`                      |
| `RuleId`, rule descriptors, traces and source refs                           | `@taxkit/core`                      |
| Rule-specific facts, parameter services, rule IDs and calculator literals    | Owning `@taxkit/rules-au-*` package |
| `CalculatorRunRequest`, `CalculatorRunResponse` and `CalculatorServiceError` | `@taxkit/calculators`               |
| HTTP route status envelopes and OpenAPI annotations                          | `@taxkit/api-http`                  |
| `TaxKit.calculate`, `TaxKit.safe.calculate` and SDK helper descriptors       | `@taxkit/sdk`                       |

Import the owning schema, type, branded constructor, descriptor or service tag.
Do not redeclare canonical fields such as `id: string`, `ruleId: string`,
`taxYear: string` or transport-only mirrors when an owner already exists.

## Use current public names [#use-current-public-names]

Use these names in public docs and package-facing code:

* `TaxKit.calculate`
* `TaxKit.safe.calculate`
* `au.incomeTax.annual`
* `calculateRunRequest`
* `calculateReportRequest`
* `calculateReport`
* `CalculatorRunRequest`
* `CalculatorRunResponse`
* `CalculatorServiceError`

Do not introduce stale names in new docs or code. Migration docs may mention
old names only when they are explicitly documenting a migration.

## Optional policy [#optional-policy]

Use schema-owned optional fields, `Option` and `Match` for optional request
and response policy. Do not use conditional object spread to hide fields or
raw `undefined` branching to invent defaults.

For deeper rules, read
[Effect services](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/docs/architecture/effect-services.md) and
[Package ownership](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/docs/architecture/package-ownership.md).