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 10samples asPepperoni). Set draws are uniform; that number is not a probability. Weighted categoricals areP(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) ~ Countfor 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.
# 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.