# Project catalog API

Inspect and manage dictionary definitions for an explicit project. The
project ID must match the project bound to your API key.

CLI equivalent: `simhealth dictionary get` reads the catalog;
`simhealth dictionary validate FILE` and `simhealth dictionary publish FILE`
write it.

## Catalog structure

A dictionary pack contains four kinds:

- **records:** root entities sampleable through `GET /v1/random/{record}`.
- **sets:** discrete categorical values, one member per line. A trailing positive number is weight metadata and is not part of the sampled label (`Pepperoni 10` samples as `Pepperoni`). Set draws are uniform; that number is not a probability. Weighted categoricals are `P(name)`.
- **sequences:** sequential ID generators. Template placeholders are only `{n}` and zero-padded `{n:WIDTH}` (for example `{n:06}`). Other `{...}` text is copied literally.
- **distributions:** continuous and discrete probability definitions, including `P(name) ~ Count` for list lengths.

`Fragment(name)` is source-level syntax for a nested record. Publish it as kind `records`. There is no `fragments` kind. `POST /v1/projects/{project_id}/catalog/batch` with kind `fragments` returns HTTP 400 `Unknown catalog kind (use sets, records, distributions, sequences)`. A fragment is not a sampleable root and is not a relational foreign-key table.

Sets, distributions, sequences, and records are separate entries. A record source that contains `P(...)` or `Set(...)` is rejected.

## DSL example

Publish these as four catalog entries. Field cardinalities are `1`, `0..1`, `0..N`, and an inclusive range such as `1..3`.

```text
# kind: sets  id: itemCount
Set(itemCount)
0
1
2

# kind: distributions  id: itemCount
P(itemCount) ~ Count over Set(itemCount)
0	20
1	50
2	30

# kind: records  id: lineItem
Fragment(lineItem)
sku	1	Set(sku)
quantity	1	uniformInt(1, 10)

# kind: records  id: order
Record(order)
id	1	Seq(orderId)
itemCount	1	P(itemCount)
items	0..N	Fragment(lineItem) ~ P(itemCount)
```

Numeric rows in `P(itemCount)` are list lengths even without `~ Count`. A count distribution that cannot be zero does not sample an empty list. The nested value is an object under `items`, for example `items[0].sku`, not flattened columns. `orders 1..3 Fragment(lineItem)` samples one to three objects. `patient.id` copies that nested value exactly; a missing or case-mismatched path fails with `Unresolved reference`. `Record(lineItem)` is accepted in the same position as `Fragment(lineItem)`.

## Catalog endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/projects/{project_id}/catalog` | Return the manifest and all entries. |
| GET | `/v1/projects/{project_id}/catalog/{kind}` | List entries for `sets`, `records`, `distributions`, or `sequences`. |
| GET | `/v1/projects/{project_id}/catalog/{kind}/{id}` | Retrieve source and compiled metadata. |
| PUT | `/v1/projects/{project_id}/catalog/{kind}/{id}` | Replace an entry and validate it. |
| POST | `/v1/projects/{project_id}/catalog/batch` | Atomically compile and publish multiple entries. |
| DELETE | `/v1/projects/{project_id}/catalog/{kind}/{id}` | Delete an entry when the remaining pack still compiles. |

The catalog and random-generation endpoints use the project encoded in the
Bearer API key. They never use the browser's currently selected project, so
keys for separate applications can safely be used at the same time.

The legacy `/v1/catalog`, `/v1/catalog/{kind}`, and related unscoped catalog
routes remain available for compatibility with existing clients. New
integrations should use the project-scoped paths above. A `{project_id}` that
does not match the project permanently bound to the Bearer API key returns
`403`.
