Ontologies

An ontology is your team's live schema — a completed template instantiated for real product data. Creating one deep-copies the template's structure (regenerating every property id) and automatically creates the root passport at the top level, so you can start adding data immediately. There's no separate "activate" step: an ontology is live the moment it's created.

Both ontologies:read and ontologies:write can be restricted to specific ontologies, and ontologies:read is the root every passport, composition and import ability sits inside: a key cannot hold one of those without it, nor reach an ontology its ontologies:read does not. A scoped ontologies:read lists only its ontologies and reads any other as 403 ability_not_scoped_to_resource. A scoped ontologies:write edits the drafts and metadata of its ontologies but cannot create one, because a new ontology is in no scope yet.

The ontology model

An ontology's passport values are authored in its default language — the team's language when the ontology was created, or English if the team has none — and a passport read falls back to it when the language asked for has no translation. It is not a field of this object; the ontology's composition reports it as default_language.

The level object

Each entry in levels describes one level of the schema. See the Data model for how the type values behave.

Reporting granularity

A level may declare which of the three tiers it reports as to the EU registry: model, batch or item. null — the default — means the level is internal: it still holds properties and still renders on the passport page, it is simply reported to nobody.

The tiers run coarse to fine, and three rules govern them:

• Containment is strict. An item sits inside a batch, a batch inside a model. A level advances one tier at a time, and only from the tier directly above it.
• Only a multiplier opens a finer tier. A singular level is one-to-one with its parent, so it may repeat the tier it inherits but never open a finer one. model is exempt: it establishes the top of the hierarchy rather than subdividing it, so any level type — a singular root included — may open it.
• Each tier is opened once per ontology. Opening means carrying a tier without inheriting it. Two batches on separate branches would leave an item with no answer to which batch it belongs to. Continuing an inherited run is always fine, however deep — and a level may open a tier that a level below it currently opens, which simply extends that run upwards.

A level with no granularity is transparent: it does not interrupt the run around it. A violation is 400 structure_invalid, with the offending level named in error.errors.structure.

Which level carries the ID

Several levels can share a tier, so one of them has to be the one the registry is given as that tier's ID: the level marked is_core. You choose it — which level of your hierarchy is "the item" is a judgement about your business, not something the shape of the tree settles.

• A core must carry a granularity.
• One core per tier. Two would make "the item id" ambiguous.
• It must sit where every path through the run passes through it — at or above any fork. A core chosen down one branch leaves the others reporting nothing. This is checked when you publish a draft, not on every save, so a part-marked draft still saves. Publishing never picks a core for you; template completion does, for a tier only one level carries.

A passport at a level that carries a tier without being its core reports that tier with a null id. And a series below the core holds many instances per core, so its values cannot be reported as part of the entity the core names.

Reported properties

A level's granularity says which tier it reports as; a property's data_element_id says whether that property is reported at all, and under what name the registry knows it.

{ "id": "property_9f2k7d", "name": "Capacity", "type": "measurement", "data_element_id": "BATT-BATCH-CAP" }

Absent is the ordinary state, not an omission: most properties on a reported level are your own business rather than the registry's, so only the ones you map are reported. Nothing requires a mapping, and an ontology with none still publishes.

• Only a reported level may carry mappings. A data_element_id on a level with no granularity names a field in a submission that never happens, so it is refused rather than silently dropped.
• One property per element, per tier. The registry receives one submission per tier, so two properties offering values for the same element are ambiguous. Across tiers the same element may be reused: a model's weight and an item's weight are separate submissions.
• The value has to survive XML and JSON. Valid UTF-8, at most 128 characters, and no control characters — tabs and newlines included, because XML rewrites those inside an attribute value. Markup characters (<, &, quotes) are fine; they escape losslessly. Surrounding whitespace is trimmed on write, and a blank value is stored as no mapping.

A violation is 400 structure_invalid, with the offending property named in error.errors.structure.

List ontologies

curl -G https://api.synexcloud.com/v1/ontologies \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -d limit=10

{
  "object": "list",
  "data": [
    {
      "object": "ontology",
      "id": "ontology_00a1b2c3d4e5f607",
      "name": "EV Battery Line A",
      "description": "2026 production",
      "template": "template_00a1b2c3d4e5f607",
      "levels": [
        { "key": "A", "name": "SKU", "type": "singular",
          "granularity": "model", "is_core": true, "is_root": true }
      ],
      "latest_version": 2,
      "has_draft": false,
      "metadata": {},
      "created_at": "2026-07-10T12:00:00Z",
      "updated_at": "2026-07-24T08:31:47Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/ontologies"
}

Create an ontology

curl https://api.synexcloud.com/v1/ontologies \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template": "template_00a1b2c3d4e5f607", "name": "EV Battery Line A", "description": "2026 production" }'

{
  "object": "ontology",
  "id": "ontology_00a1b2c3d4e5f607",
  "name": "EV Battery Line A",
  "description": "2026 production",
  "template": "template_00a1b2c3d4e5f607",
  "levels": [
    { "key": "A", "name": "SKU", "type": "singular", "granularity": null,
      "is_core": false, "is_root": true, "children": ["B"], "properties": [] },
    { "key": "B", "name": "Pack", "type": "series", "granularity": null,
      "is_core": false, "parent": "A",
      "properties": [
        { "id": "property_9f2k7d", "name": "Capacity", "type": "measurement" }
      ] }
  ],
  "latest_version": 1,
  "has_draft": false,
  "metadata": {},
  "root_passport": {
    "object": "passport",
    "id": "pass_00a1b2c3d4e5f607",
    "ontology": "ontology_00a1b2c3d4e5f607",
    "parent": null,
    "level": "A",
    "path": "A",
    "friendly_id": null,
    "ontology_version": 1,
    "publish_status": null,
    "publish_status_resolved": "draft",
    "release_number": 0,
    "values": {},
    "metadata": {},
    "created_at": "2026-07-10T12:00:00Z",
    "updated_at": "2026-07-10T12:00:00Z"
  },
  "created_at": "2026-07-10T12:00:00Z",
  "updated_at": "2026-07-10T12:00:00Z"
}

Retrieve an ontology

curl https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "ontology",
  "id": "ontology_00a1b2c3d4e5f607",
  "name": "EV Battery Line A",
  "description": "2026 production",
  "template": "template_00a1b2c3d4e5f607",
  "levels": [
    {
      "key": "A", "name": "SKU", "type": "singular",
      "granularity": "model", "is_core": true, "is_root": true,
      "static_lineage": true, "parent": null, "children": ["B"],
      "discoverable": [], "properties": []
    },
    {
      "key": "B", "name": "Pack", "type": "series",
      "granularity": "batch", "is_core": true, "is_root": false,
      "static_lineage": true, "parent": "A", "children": [],
      "discoverable": ["A"],
      "properties": [
        { "id": "property_9f2k7d", "name": "Capacity", "type": "measurement",
          "data_element_id": "BATT-BATCH-CAP" }
      ]
    }
  ],
  "latest_version": 2,
  "has_draft": false,
  "metadata": {},
  "created_at": "2026-07-10T12:00:00Z",
  "updated_at": "2026-07-24T08:31:47Z"
}

Update an ontology

curl -X PATCH https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607 \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"erp_line": "L-14"}}'

{
  "object": "ontology",
  "id": "ontology_00a1b2c3d4e5f607",
  "name": "EV Battery Line A",
  "description": "2026 production",
  "template": "template_00a1b2c3d4e5f607",
  "levels": [
    { "key": "A", "name": "SKU", "type": "singular",
      "granularity": "model", "is_core": true, "is_root": true }
  ],
  "latest_version": 2,
  "has_draft": false,
  "metadata": { "erp_line": "L-14" },
  "created_at": "2026-07-10T12:00:00Z",
  "updated_at": "2026-07-28T14:02:19Z"
}

Versioning

A schema evolves without breaking the passports already issued under it. Versions are append-only: publishing adds version N+1 and never alters or removes an existing one.

Every passport is pinned to the version it was created under, exposed as ontology_version. That pin decides two things:

• Reads render the passport against its own version's levels — its discoverable_levels, discovery chain and property definitions are the ones that existed when it was issued.
• PATCH /v1/passports/{passport} validates values against its own version's property definitions. A property added in a later version is rejected on an older-pinned passport.

Changes must be additive

The draft is validated against the published version before it can be saved or published. A violation is 400 structure_invalid, with one message per violation in error.errors.structure:

• published levels cannot be deleted, re-parented, re-typed, or re-lettered;
• a published granularity cannot change or be removed — but a level that has none may be given one in a later version, which is how an ontology already in production starts reporting without being replaced;
• a published is_core cannot be taken away: it is the level the registry was given as that tier's ID;
• a published data_element_id cannot change or be withdrawn, since the registry may already hold values reported under it — but a property published without one may be mapped in a later version;
• a published parent/child edge cannot be dropped;
• a property carried over from a published version must keep its id;
• the graph stays a single tree rooted at A.

Within those rules, adding levels and adding, editing or removing properties are all fine.

Level keys are assigned by the server

This is the part that most often surprises people. You do not choose level keys, and you do not choose ids for new properties.

• Send any placeholder key you like for a new level. The server assigns the next unused letter — C, D, … AA — and returns it in the response's levels. Read the real key back from there; the placeholder is gone.
• A key that already exists in the published schema or the current draft is kept as-is. Existing levels are never re-lettered — every passport path in the system depends on that.
• One trap: a placeholder that looks like a level key (^[A-Z]+$) but is not one of the known keys is treated as a placeholder and silently re-lettered. Use obviously non-key placeholders ("new-module", "tmp-1") so you never have to think about it.
• Property ids work the same way: omit id for a new property and one is minted; carry an existing id through verbatim to keep the values already stored against it.

Concurrency

Three guards, three different 409s:

base_updated_at is an opaque token, not a timestamp you should read. Echo it back exactly as received; do not parse, reformat, or compare it. Every draft response carries a fresh one.

PATCH /draft is deliberately not covered by idempotency keys — base_updated_at is already its concurrency control. The two POSTs are: note that a replayed POST /draft returns the stored response, whose base_updated_at may since have gone stale, so if a following PATCH returns draft_conflict, re-read the draft with GET.

Ontology and version mutations are recorded on the change feed as ontology.created, ontology.updated and ontology.version.published. Opening, editing and discarding a draft record nothing.

List versions

curl https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607/versions \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "ontology.version",
      "version": 1,
      "published_at": "2026-07-10T12:00:00Z",
      "latest": false
    },
    {
      "object": "ontology.version",
      "version": 2,
      "published_at": "2026-07-24T08:31:47Z",
      "latest": true
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/ontologies/ontology_00a1b2c3d4e5f607/versions"
}

Retrieve a version

curl https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607/versions/1 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "ontology.version",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "version": 1,
  "status": "published",
  "published_at": "2026-07-10T12:00:00Z",
  "levels": [
    {
      "key": "A", "name": "SKU", "type": "singular",
      "granularity": null, "is_core": false, "is_root": true,
      "static_lineage": true, "parent": null, "children": ["B"],
      "discoverable": [], "properties": []
    },
    {
      "key": "B", "name": "Pack", "type": "series",
      "granularity": null, "is_core": false, "is_root": false,
      "static_lineage": true, "parent": "A", "children": [],
      "discoverable": ["A"],
      "properties": [
        { "id": "property_9f2k7d", "name": "Capacity", "type": "measurement" }
      ]
    }
  ]
}

The draft lifecycle

An ontology has at most one open draft at a time, always based on the latest published version.

1. Open a draft — a copy of the latest published version.
2. Edit it, sending the complete level map each time.
3. Publish it as the next version, or delete it to throw the work away.

Deleting a draft never affects published versions.

Retrieve the draft

curl https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607/draft \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "ontology.draft",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "status": "draft",
  "created_from_version": 2,
  "base_updated_at": "1753699847.482913",
  "latest_version": 2,
  "levels": [
    { "key": "A", "name": "SKU", "type": "singular", "granularity": "model",
      "is_core": true, "is_root": true, "children": ["B"], "properties": [] },
    { "key": "B", "name": "Pack", "type": "series", "granularity": "batch",
      "is_core": true, "parent": "A", "children": [],
      "properties": [
        { "id": "property_9f2k7d", "name": "Capacity", "type": "measurement",
          "data_element_id": "BATT-BATCH-CAP" }
      ] }
  ]
}

Open a draft

curl -X POST https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607/draft \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "ontology.draft",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "status": "draft",
  "created_from_version": 2,
  "base_updated_at": "1753699847.482913",
  "latest_version": 2,
  "levels": [
    { "key": "A", "name": "SKU", "type": "singular", "granularity": "model",
      "is_core": true, "is_root": true, "children": ["B"], "properties": [] },
    { "key": "B", "name": "Pack", "type": "series", "granularity": "batch",
      "is_core": true, "parent": "A", "children": [],
      "properties": [
        { "id": "property_9f2k7d", "name": "Capacity", "type": "measurement",
          "data_element_id": "BATT-BATCH-CAP" }
      ] }
  ]
}

Edit the draft

curl -X PATCH https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607/draft \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base_updated_at": "1753699847.482913",
    "structure": {
      "A": {"name": "SKU", "type": "singular", "is_root": true,
            "granularity": "model", "is_core": true,
            "properties": [], "children": ["B", "new-module"]},
      "B": {"name": "Pack", "type": "series", "children": [],
            "granularity": "batch", "is_core": true,
            "properties": [
              {"id": "property_9f2k7d", "name": "Capacity", "type": "measurement",
               "data_element_id": "BATT-BATCH-CAP"}
            ]},
      "new-module": {"name": "Module", "type": "many", "children": [],
                     "properties": [{"name": "Slot", "type": "short_text"}]}
    }
  }'

{
  "object": "ontology.draft",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "status": "draft",
  "created_from_version": 2,
  "base_updated_at": "1753700114.907255",
  "latest_version": 2,
  "levels": [
    { "key": "A", "name": "SKU", "type": "singular", "granularity": "model",
      "is_core": true, "is_root": true, "children": ["B", "C"], "properties": [] },
    { "key": "B", "name": "Pack", "type": "series", "granularity": "batch",
      "is_core": true, "parent": "A", "children": [],
      "properties": [
        { "id": "property_9f2k7d", "name": "Capacity", "type": "measurement",
          "data_element_id": "BATT-BATCH-CAP" }
      ] },
    { "key": "C", "name": "Module", "type": "many", "granularity": null,
      "is_core": false, "parent": "A", "children": [],
      "properties": [
        { "id": "property_4c8b1e", "name": "Slot", "type": "short_text" }
      ] }
  ]
}

The placeholder new-module came back as level C, with a minted property_4c8b1e. Read both from the response — the values you sent are not authoritative.

Discard the draft

curl -X DELETE https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607/draft \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "ontology.draft",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "deleted": true
}

Publish the draft

curl -X POST https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607/draft/publish \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expected_latest_version": 2}'

{
  "object": "ontology.version",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "version": 3,
  "status": "published",
  "published_at": "2026-07-28T14:20:05Z",
  "levels": [
    { "key": "A", "name": "SKU", "type": "singular", "granularity": "model",
      "is_core": true, "is_root": true, "children": ["B", "C"], "properties": [] },
    { "key": "B", "name": "Pack", "type": "series", "granularity": "batch",
      "is_core": true, "parent": "A",
      "properties": [
        { "id": "property_9f2k7d", "name": "Capacity", "type": "measurement",
          "data_element_id": "BATT-BATCH-CAP" }
      ] },
    { "key": "C", "name": "Module", "type": "many", "granularity": null,
      "is_core": false, "parent": "A",
      "properties": [
        { "id": "property_4c8b1e", "name": "Slot", "type": "short_text" }
      ] }
  ]
}