> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiparlance.org/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI emitter

> @aiparlance/openapi — role contract, score 16/33, pass/partial/fail objectives

# OpenAPI emitter

|           |                                                                                                                                           |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Package   | `@aiparlance/openapi`                                                                                                                     |
| CLI       | `aip emit openapi`                                                                                                                        |
| Role      | `contract`                                                                                                                                |
| **Score** | **16/33** (48%)                                                                                                                           |
| Band      | Useful Preview                                                                                                                            |
| Scorecard | [transpilers/openapi/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/openapi/EMITTER_OBJECTIVES.md) |

Scored against the master checklist ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), v2 · 2026-08-06).

## Summary

| ✅ Pass | ⚠️ Partial | ❌ Fail | ➖ N/A |
| ------ | ---------- | ------ | ----- |
| 16     | 3          | 14     | 22    |

N/A items are outside the `contract` role and do not affect the score denominator.

## What it produces

OpenAPI 3.0.3 JSON: schemas, CRUD paths, `api.prefix`, auth schemes.

## ✅ Passed

| ID   | Objective                                                             |
| ---- | --------------------------------------------------------------------- |
| `A1` | Emit entity shapes (types / structs / schemas / tables) from `entity` |
| `A2` | Emit create-input shapes (`EntityCreate` or equivalent)               |
| `A3` | Emit update-input shapes (`EntityUpdate` or equivalent)               |
| `A4` | Emit enums / constrained variants from `enum(…)`                      |
| `A5` | Emit `belongs_to` as FKs or refs                                      |
| `A6` | Emit implicit `id` primary key                                        |
| `A7` | Emit `timestamps` (`created_at` / `updated_at`)                       |
| `A8` | Emit `soft_delete` field/column (`deleted_at`)                        |
| `B1` | Honor `required` / `optional`                                         |
| `D1` | Full CRUD surface for `crud` entities (list/create/get/update/delete) |
| `D2` | Honor `api.prefix`                                                    |
| `D7` | Honor `api.format` (e.g. JSON)                                        |
| `E1` | Auth scheme from `app.auth` (`jwt` / `api_key` / `session` / `oauth`) |
| `H3` | Golden / CI for `minimal.aip` (or matching twin)                      |
| `H4` | Emit succeeds on matching full-tier examples without crash            |
| `H5` | Naming aligned with docs (plural tables, `*_id`, snake\_case)         |

## ⚠️ Partial

| ID   | Objective                                                |
| ---- | -------------------------------------------------------- |
| `B2` | Honor `unique`                                           |
| `B4` | Map semantic types (`email`, `phone`, …) distinctly      |
| `E2` | Wire auth into API (security requirements or middleware) |

## ❌ Still failing (applicable)

| ID   | Objective                                                                    |
| ---- | ---------------------------------------------------------------------------- |
| `A9` | Soft-delete **semantics** (default reads filter deleted rows)                |
| `B3` | Apply `validation { }` beyond required folding                               |
| `D3` | Honor `api.cors` (config or middleware)                                      |
| `D4` | Honor `api.rate_limit` (config or enforcement)                               |
| `D5` | Pagination and/or filter/sort on list                                        |
| `D6` | Typed error responses (4xx/5xx + stable body shape)                          |
| `E3` | Reflect `policy` create/read/update/delete                                   |
| `E4` | Predicates: `public`, `authenticated`, `role(…)`                             |
| `E5` | Predicates: `owner` / `owner_or_manager(…)`                                  |
| `E6` | Consistent **401/403** denial paths (runtime **or** contract documents both) |
| `H1` | Human-readable API / domain documentation                                    |
| `H2` | Automated test fixtures or scaffolds                                         |
| `I1` | Typed API client / SDK (or codegen from the contract)                        |
| `I2` | Contract↔runtime parity story (shared paths/types or CI check)               |

Full ID-by-ID scorecard (including ➖ N/A): [transpilers/openapi/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/openapi/EMITTER_OBJECTIVES.md).

## Tests

Golden `minimal.openapi.json` + CI. OpenAPI prefix asserted for crm/blog examples.

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit openapi examples/blog-crud.aip
```

## Related

* [Emitters overview](/en/emitters)
* [Master EMITTER\_OBJECTIVES](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [First emitters](/en/first-transpiler)
* [Get started here](/en/getting-started)