Compositions

A composition is the presentation layout used when an ontology's passports are rendered publicly — which tabs exist, which properties appear where, and the masthead (name, id, QR code). Each ontology has at most one composition, and it shares the ontology's id. Ontologies without one still render, from a synthesized default layout, so a composition is only needed when you want control over how a passport is presented — not its schema.

The composition model

Name
object
Type
string
Description
Always composition.
Name
id
Type
string
Description
Unique identifier. A composition is 1:1 with its ontology and shares its id, e.g. ontology_00a1b2c3d4e5f607.
Name
ontology
Type
string
Description
The id of the ontology this composition belongs to.
Name
name
Type
string
Description
Display name for the layout. Nullable.
Name
description
Type
string
Description
Short description of the layout. Nullable.
Name
composition
Type
object
Description
The layout document — a JSON object or array describing how the public passport page is presented (see below). Nullable until you set it.
Name
created_at
Type
string
Description
ISO 8601 timestamp of creation.
Name
updated_at
Type
string
Description
ISO 8601 timestamp of the last update.

The layout document

composition is a free-form layout document — a JSON object (or array) that describes the public presentation: the masthead toggles, the tabs, and which properties appear in each. It controls presentation only; the underlying schema lives on the ontology and its passports. PATCH replaces the whole document, so send the complete layout you want each time.

composition

{
  "masthead": { "show_name": true, "show_id": true, "show_qr": true },
  "tabs": [
    { "key": "overview", "label": "Overview", "properties": ["property_9f2k7d"] },
    { "key": "documents", "label": "Documents", "properties": ["property_3a8b1c"] }
  ]
}

Ontologies without a stored composition still render — the viewer synthesizes a default layout from the passport data. See the Data model for how passports are assembled.

GET/v1/ontologies/:ontology/composition

Retrieve a composition

Retrieves the composition for an ontology. Returns 404 composition_missing until a composition has been created — ontologies without one still render from a synthesized default layout. Requires compositions:read.

Request

GET

/v1/ontologies/ontology_00a1b2c3d4e5f607/composition

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

Response

{
  "object": "composition",
  "id": "ontology_00a1b2c3d4e5f607",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "name": "EV Battery Pack",
  "description": "Public passport layout",
  "composition": {
    "masthead": { "show_name": true, "show_id": true, "show_qr": true },
    "tabs": [
      { "key": "overview", "label": "Overview", "properties": ["property_9f2k7d"] }
    ]
  },
  "created_at": "2026-07-12T09:31:00Z",
  "updated_at": "2026-07-12T09:31:00Z"
}

POST/v1/ontologies/:ontology/composition

Create a composition

Creates the single composition for an ontology. There's no required body — the composition starts empty, then you shape its layout with update. Fails with 409 composition_exists if the ontology already has one. Requires compositions:write. Accepts an optional Idempotency-Key header.

Request

POST

/v1/ontologies/ontology_00a1b2c3d4e5f607/composition

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

Response

{
  "object": "composition",
  "id": "ontology_00a1b2c3d4e5f607",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "name": null,
  "description": null,
  "composition": null,
  "created_at": "2026-07-12T09:31:00Z",
  "updated_at": "2026-07-12T09:31:00Z"
}

PATCH/v1/ontologies/:ontology/composition

Update a composition

Replaces the composition's layout document. PATCH overwrites the whole composition document — send the complete layout you want, not a partial patch. Requires compositions:write.

Required attributes

Name
composition
Type
object
Description
The full replacement layout document — a JSON object or array describing how the public passport page is presented. Replaces the existing document entirely.

Request

PATCH

/v1/ontologies/ontology_00a1b2c3d4e5f607/composition

curl -X PATCH https://api.synexcloud.com/v1/ontologies/ontology_00a1b2c3d4e5f607/composition \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "composition": {
      "masthead": { "show_name": true, "show_id": true, "show_qr": true },
      "tabs": [
        { "key": "overview", "label": "Overview", "properties": ["property_9f2k7d"] },
        { "key": "documents", "label": "Documents", "properties": ["property_3a8b1c"] }
      ]
    }
  }'

Response

{
  "object": "composition",
  "id": "ontology_00a1b2c3d4e5f607",
  "ontology": "ontology_00a1b2c3d4e5f607",
  "name": null,
  "description": null,
  "composition": {
    "masthead": { "show_name": true, "show_id": true, "show_qr": true },
    "tabs": [
      { "key": "overview", "label": "Overview", "properties": ["property_9f2k7d"] },
      { "key": "documents", "label": "Documents", "properties": ["property_3a8b1c"] }
    ]
  },
  "created_at": "2026-07-12T09:31:00Z",
  "updated_at": "2026-07-12T09:40:00Z"
}