Atlas API - Ontology (Entity Types, Properties, Data Types, Enumeration Types, Relationship Types, Functions)

Overview#

The Ontology API reads and writes the type definitions that make up an Atlas model. There are six ontology resources, and each one is mounted twice: once under a domain and once under a library.

This article is written for developers building an integration against Atlas. It documents the request bodies, response bodies, verbs and status codes of all 64 ontology endpoints.

Read Atlas API Overview first. That article is the single source of truth for the base address, authentication, the RFC-9457 error envelope, pagination and the /api/v2 surface. This article does not restate any of it and links back wherever it matters. For the meaning of the words used here (domain, library, branch, ontology, compile, draft session, binding path), see Timebase Atlas Key Concepts.

The three corrections most likely to break an existing client#

1. nodes is now entity-types and relationships is now relationship-types. Both renames were part of the /api/v1 cutover. A request to the old segment does not return 404: the single-page-application fallback answers it with 200 text/html. See the Overview article's Troubleshooting table.
2. Update is PATCH for entity types, properties and relationship types. PUT survives only for data types and functions. Sending the wrong verb also gives you the HTML shell, not a 405.
3. Data types are a full ontology resource. If your integration models anything historian-bound, you need them.

Scopes: every route is mounted twice#

Each of the five resources has an identical domain group and library group. The request bodies, response bodies and status codes are the same; only the scope segment differs.

/api/v1/branches/{branch}/domains/{domain}/{resource}
/api/v1/branches/{branch}/libraries/{library}/{resource}

{branch} is always required and is a Git branch name, typically main. {domain} and {library} are the lowercased, hyphenated internal names, not display labels.

Every example in this article uses the domain scope. To use the library scope, swap domains/{domain} for libraries/{library} and change nothing else.

Authentication#

/api/v1 requires a Pulse-issued bearer token whose aud claim includes Atlas (Authentication is required on all ten ontology route groups). A browser session cookie is not accepted on this plane. Every example below sends the header; do not omit it.

Authorization: Bearer <your-pulse-token>

Serialization#

Responses use camelCase property names, omit null members entirely rather than emitting null, and serialize enums as camelCase strings, so NodeKind.Entity arrives as "entity". A strongly typed client that expects every declared member to be present will see gaps. The response samples in this article show the fields as they appear when populated.

201 Created responses carry the created resource in the body. Ontology creates do not set a Location header (only domain, library and branch creation do), so do not build a client that follows it.

Naming: one URN namespace for all six kinds#

Every entity type, property, data type, enumeration type, relationship type and function is identified by a URN with exactly one shape:

urn:atlas:ontology:{scope}:{LocalName}

{scope} is the domain or library name. {LocalName} is the name you supplied on create. A Plant entity type in the lonestar-plant scope is:

urn:atlas:ontology:lonestar-plant:Plant

There are no per-kind prefixes. urn:atlas:class:, urn:atlas:prop:, urn:atlas:rel: and urn:atlas:fn: do not exist and never did on this surface. A Cypher query or binding path built on one matches nothing. In the shipped libraries every @id resolves to urn:atlas:ontology:..., for example urn:atlas:ontology:atlas-common:TVQ.

Two adjacent namespaces you will also encounter in responses:

• urn:atlas:vocab:... for the Atlas framework vocabulary, such as urn:atlas:vocab:NodeBase, urn:atlas:vocab:ContainsBase and urn:atlas:vocab:RelationshipBase.
• urn:atlas:instance:... for individual instances in the compiled World.

{name} in a route is the local name#

Every single-item route addresses the resource by its local name, not its URI. GET .../entity-types/Pump, never GET .../entity-types/urn:atlas:ontology:brewery:Pump. The server mints the URI from the scope and the name.

A name collision across kinds is rejected#

Because all six kinds mint from the same namespace, a name is unique across the whole scope, not just within its own kind. Creating a property called Tank in a scope that already has an entity type called Tank fails with 409 Conflict:

{
  "type": "https://atlas.timebase.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Cannot create Property 'Tank': the key 'urn:atlas:ontology:brewery:Tank' is already used by a Type. All element kinds (Types, Properties, Relationships, Data Types, Functions) share one URN namespace per domain."
}

This is a different failure from a same-kind duplicate, which reports Property 'Tank' already exists. The cross-kind case cannot be fixed by switching to an update: pick a different local name. The occupying kind is named in the detail string as one of Type, Property, Relationship, Data Type, Enumeration Type or Function. The list of kinds at the end of the message does not mention enumeration types, but they share the namespace too.

What a successful write actually means#

This is the single most consequential behaviour on the ontology surface, and it changed. Read it before you write anything.

A save that fails validation still returns 2xx. When an ontology write leaves the scope with outstanding error-severity violations, the content is committed to the caller's private draft session and the target branch does not advance. You still receive 201 Created or 200 OK with the resource in the body. Nobody else sees the change.

A valid save commits straight through. It runs in a throwaway worktree, fast-forwards the target branch and leaves nothing behind. There is no session to publish and nothing else to do.

So a draft session is not a mode you opt into. Having one means "I have unpublished work that does not validate".

The only signal is a response header#

Atlas-Validation-Violations: 3

The header carries the count of outstanding error-severity violations in the state the write just persisted. It is absent on a clean save, not 0. Check for its presence on every write.

The header carries only a count. To get the actionable list, read the violations resource:

GET /api/v1/branches/{branch}/domains/{domain}/validation
GET /api/v1/branches/{branch}/libraries/{library}/validation

To promote your draft onto the branch:

POST /api/v1/branches/{branch}/draft/publish

Rule IDs in the violations you get back are O-A* and O-B* for ontology problems and I-A* and I-B* for instance-map problems. See the Validation Rules Reference for what each one means and how to clear it.

rdfs:domain on a property is now a validation error#

If you migrate hand-written JSON-LD into Atlas, note that property-to-type attachment moved onto the entity class as an owl:Restriction. An rdfs:domain on a property definition is reported as O-A12. Atlas framework vocabulary under urn:atlas:vocab: and the atlas: CURIE are exempt; your own subjects never are.

Compile is a separate action with a different failure shape#

PUT /api/v1/branches/{branch}/domains/{domain}/world returns 422 with a violations[] array and builds no World when validation fails. Do not conflate the two: saves return 2xx and route to a draft; compile returns 422 and aborts. Full detail is in the Overview article.

Entity types#

An entity type is a kind of thing. It may inherit from a parent entity type and it carries a set of attached properties.

Routes#

Declared (domain) and (library).

List all entity types#

GET /api/v1/branches/main/domains/brewery/entity-types
Authorization: Bearer <your-pulse-token>

Response - 200 OK

[
  {
    "uri": "urn:atlas:ontology:brewery:Pump",
    "label": "Pump",
    "comment": "Centrifugal pump",
    "parentType": "urn:atlas:ontology:isa95-common:Equipment",
    "kind": "entity",
    "properties": [
      {
        "uri": "urn:atlas:ontology:brewery:Speed",
        "label": "Speed",
        "attachedTypes": ["urn:atlas:ontology:brewery:Pump"],
        "range": "http://www.w3.org/2001/XMLSchema#double",
        "isObjectProperty": false
      }
    ]
  }
]

Get a single entity type#

GET /api/v1/branches/main/domains/brewery/entity-types/Pump
Authorization: Bearer <your-pulse-token>

{name} is the local name. Returns 200 with a single object in the shape above, or 404 when no entity type of that name exists in the scope.

Create an entity type#

POST /api/v1/branches/main/domains/brewery/entity-types
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "Compressor",
  "label": "Gas Compressor",
  "comment": "Reciprocating gas compressor",
  "parentType": "Equipment",
  "properties": ["Speed", "Description"]
}

Response - 201 Created, body is the created entity type read model.

properties is the atomic create-plus-attach path (AddEntityTypeRequest). Every entry is resolved before anything is written, so one unresolvable reference fails the whole create and the type is never half-created. That failure is 400 Bad Request with the detail Cannot attach property '<ref>' - no such property in scope..

parentType resolution searches the current scope first, then the Atlas framework vocabulary roots, then every loaded entity by local-name suffix. If nothing matches, it falls back to a scope-local URI, and whole-scope validation reports it.

Update an entity type#

PATCH /api/v1/branches/main/domains/brewery/entity-types/Compressor
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "label": "Reciprocating Compressor",
  "properties": ["Speed", "Description", "UOM"]
}

PATCH is a partial merge. Fields you do not send are preserved.

Response - 200 OK, body is the updated read model. 404 when the name does not exist.

The properties replacement is all-or-nothing and lands as one commit with the metadata edit, so a metadata change never persists alone when an attachment reference is bad. Inherited attachments, declared on an ancestor type, are never affected by this list.

Defer properties and rule O-B23#

A property is Defer when its type is not yet fixed: its own range is a union of scalars, or its data type has a union-typed field, such as TVQ.Value (xsd:double, xsd:string or xsd:boolean), that fieldTypeOverrides has not pinned. Each such place is an unresolved leaf, and the read model reports them in openLeaves.

A Defer property can be attached to an entity type or a relationship type, and nothing refuses the write. Validation rule O-B23, an Error that is not fatal, reports every concrete type that uses a property with a leaf that is still open after the type's own pins and its ancestors' pins, for example Type 'Pump' uses property 'FlowRate' with an unresolved type (Value is one of double, string, boolean), so 'Pump' cannot compile. Pin it on 'Pump' or on 'FlowRate'. Abstract types are skipped. The domain still loads and every save still lands, but compile refuses until every leaf used by a type is pinned. A property that comes from a library adds a clause to the message, for example 'FlowRate' comes from library 'isa95-common'; pin it on 'Pump' here, or in 'isa95-common'. See the Validation Rules Reference.

There are two places to pin a leaf:

• On the property, with fieldTypeOverrides, for example {"Value": "xsd:double"}. Every type that uses the property gets that type. Use it when the shape is the same everywhere.
• On the type, with propertyPins, described next. Only that type and its subtypes get the type. Use it when the shape depends on the type.

Pin a property's leaf on a type#

propertyPins pins an open leaf of a Defer property that a type uses. The type can attach the property itself or inherit it from an ancestor. The same two fields exist on the four requests that write a type: create and update of an entity type, and create and update of a relationship type.

PATCH /api/v1/branches/main/domains/plant/entity-types/Pump
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "propertyPins": {
    "Running": { "Value": "xsd:boolean" },
    "Mode": { "": "xsd:string" }
  }
}

Where the fields exist:

On update, an omitted or null propertyPins keeps the type's declared pins. An object, even {}, is a full replacement of the type's declared pins, so send every pin you want to keep. Inherited pins are never affected. The pins land in the same commit as the rest of the write.

A pin follows three rules, and a write that breaks one is refused before anything is saved:

• A property pin is final. A type cannot pin a leaf that the property already fixed in fieldTypeOverrides.
• A subtype only pins a leaf its ancestors left open. A leaf that an ancestor type pinned cannot be pinned again further down.
• The pinned type must be a member of the leaf's union. Value on a TVQ accepts xsd:double, xsd:string or xsd:boolean.

The refusals are 400 invalid-request, and each carries an error key. For a relationship type the key starts with Relationship. instead of EntityType., and the message opens with Relationship instead of Type.

The same cases, when found in an existing file, are reported by validation rule O-B24.

Reading pins. The entity type and relationship type read models carry propertyPins, the effective pins: the type's own plus the ones it inherits.

"propertyPins": [
  {
    "propertyUri": "urn:atlas:ontology:plant:Running",
    "declaredOnUri": "urn:atlas:ontology:plant:Pump",
    "fieldTypeOverrides": { "Value": "http://www.w3.org/2001/XMLSchema#boolean" }
  }
]

declaredOnUri names the type that wrote the pin, so a pin inherited from Equipment reads declaredOnUri of Equipment. fieldEnumOverrides, a path to enumeration URI map, is present only when an enumeration is bound.

A property can resolve to a different leaf type on different types, even in one compiled World. The compiled columns are typed for each type. A Cypher query that reads such a property across types is held to a rule: see the openCypher Query Reference.

Delete an entity type#

DELETE /api/v1/branches/main/domains/brewery/entity-types/Compressor
Authorization: Bearer <your-pulse-token>

Response - 204 No Content. 404 when the name does not exist.

Entity types carry no per-item dependents guard, so check for references before you delete one. Unlike properties, data types and functions, a delete that leaves a dangling reference is not blocked with a 409. It is caught by whole-scope re-validation instead, which aborts the write. Practically that means the delete either succeeds cleanly or routes to your draft session with an Atlas-Validation-Violations header.

Attach and detach a property#

This is the primary day-to-day ontology edit and it is a sub-resource of the entity type, not of the property.

PUT    /api/v1/branches/main/domains/brewery/entity-types/Pump/properties/Speed
DELETE /api/v1/branches/main/domains/brewery/entity-types/Pump/properties/Speed
Authorization: Bearer <your-pulse-token>

Both return 204 No Content with no body. Neither takes a request body.

The write subject is the entity class, which is what makes cross-scope attachment work: a property imported from a library attaches to a local type by construction, and the change persists only in the local type's file. The reverse is not allowed. Attaching onto a type that an import declared would be a phantom write, validated and read back but dropped by the scope-filtered save, so it is rejected with 400 and the detail Entity type '<name>' is declared by an import ('<uri>') and cannot be modified from this scope. Attach properties to it from its declaring library instead.

The attach route accepts a Defer property. See Defer properties and rule O-B23.

Detach is surgical: it retracts exactly one restriction and only from the type's declared attachments. An attachment inherited from an ancestor cannot be detached from a subtype.

Properties#

A property is a standalone value definition. It is not owned by a type. The attachment link lives on the type, and the same property can be attached to any number of types.

Routes#

Declared (domain) and (library).

List all properties#

GET /api/v1/branches/main/domains/brewery/properties
Authorization: Bearer <your-pulse-token>

Response - 200 OK

[
  {
    "uri": "urn:atlas:ontology:brewery:Speed",
    "label": "Speed",
    "comment": "Shaft speed in RPM",
    "attachedTypes": [
      "urn:atlas:ontology:brewery:Pump",
      "urn:atlas:ontology:brewery:Compressor"
    ],
    "range": "http://www.w3.org/2001/XMLSchema#double",
    "isObjectProperty": false
  }
]

An empty attachedTypes is legal. A property attached to nothing stays available until you attach it, and is not reached by any type read.

Get a single property#

GET /api/v1/branches/main/domains/brewery/properties/Speed
Authorization: Bearer <your-pulse-token>

200 with a single object, or 404.

Create a property#

POST /api/v1/branches/main/domains/brewery/properties
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "TargetSpeed",
  "label": "Target Speed",
  "comment": "Setpoint speed in RPM",
  "attachToTypes": ["Pump"],
  "range": "xsd:double",
  "isObjectProperty": false
}

Response - 201 Created, body is the created property read model.

Note the asymmetry that catches people out: you send attachToTypes and you read back attachedTypes.

range values carrying a reserved CURIE prefix (xsd:, rdf:, rdfs:, owl:) pass through unscoped and are expanded to a full URI downstream. Anything else is resolved against the loaded ontology.

Bind a property to an enumeration type#

Use enumType when a property holds one of a fixed set of codes, such as a status or a criticality. Create the enumeration type first, then give the property a plain scalar range equal to the enumeration's key type and name the enumeration in enumType:

POST /api/v1/branches/main/libraries/plant-assets/properties
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "Criticality",
  "label": "Criticality",
  "attachToTypes": ["Asset"],
  "range": "xsd:string",
  "enumType": "CriticalityLevel"
}

What the binding does, and what it does not:

• The stored value is the member's key, unchanged. Instance maps, the value hub, instance reads and queries all carry the key ("A", "3", "true"). Nothing on the value path translates it.
• The Atlas UI shows the member's label in place of the key, falling back to the member's name when no label was written. A key that is not in the list is shown as the raw key, never as an error.
• Atlas does not reject a value outside the list. An instance map value is checked against the property's range (rule I-B4), not against the enumeration's members. A code nobody has modelled yet is treated as real data. If your integration needs a closed list, check membership before you write.
• Bridge type descriptions carry the binding, so a downstream system receives the enumeration with the column it types. See Exporting Data with Bridge.

The checks, and how each one fails:

For a property whose value type is still open (a Defer property), the entity type that uses it can bind an enumeration to the leaf it pins, with propertyEnumPins. See Pin a property's leaf on a type.

Update a property#

PATCH /api/v1/branches/main/domains/brewery/properties/TargetSpeed
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "label": "Speed Setpoint",
  "attachToTypes": ["Pump", "Compressor"]
}

PATCH is a partial merge; unsent fields are preserved. Every field is independently nullable.

Response - 200 OK, or 404 when the name does not exist. Updating a library's property by name from a domain is refused with 400 and Property.NotWritableInScope; it was a plain 404 before.

Delete a property#

DELETE /api/v1/branches/main/domains/brewery/properties/TargetSpeed
Authorization: Bearer <your-pulse-token>

Response - 204 No Content when nothing references it.

409 Conflict when a type still declares it, or a data type links it as a field. The body is an RFC-9457 problem with target and dependents extensions:

{
  "type": "https://atlas.timebase.io/errors/delete-blocked",
  "title": "Delete Blocked",
  "status": 409,
  "detail": "Cannot delete 'TargetSpeed' — it is declared on 2 types. Detach from those types first.",
  "target": { "name": "TargetSpeed", "kind": "property" },
  "dependents": [
    { "id": "Pump", "name": "Pump", "kind": "entity", "referenceType": "type-declares-property" },
    { "id": "Compressor", "name": "Compressor", "kind": "entity", "referenceType": "type-declares-property" }
  ]
}

The dependents list is never truncated. Note that the dependent kind is renamed from type to entity on this surface, to match the entity-types naming. Clear the block by detaching from each listed type first, using DELETE .../entity-types/{type}/properties/{name}.

Data types#

A data type is a compound: one property value made of several named fields that always travel together. This is the fifth ontology resource, a peer of the other four, and it shares their URN namespace.

The canonical example ships in the atlas-common library as TVQ, for Timestamp-Value-Quality, and it is how nearly every measurement in Atlas is shaped.

Routes#

Declared (domain) and (library).

The library scope gained PUT and DELETE in this cutover. ### List all data types

GET /api/v1/branches/main/domains/brewery/data-types
Authorization: Bearer <your-pulse-token>

Response - 200 OK

[
  {
    "uri": "urn:atlas:ontology:atlas-common:TVQ",
    "sourceLibrary": "atlas-common",
    "fields": [
      { "name": "Timestamp", "typeUri": "urn:atlas:ontology:atlas-common:Timestamp", "isTimeAxis": true },
      { "name": "Value",     "typeUri": "urn:atlas:ontology:atlas-common:Value",     "isTimeAxis": false },
      { "name": "Quality",   "typeUri": "urn:atlas:ontology:atlas-common:Quality",   "isTimeAxis": false }
    ]
  }
]

Get a single data type#

GET /api/v1/branches/main/domains/brewery/data-types/TVQ
Authorization: Bearer <your-pulse-token>

200 with a single object, or 404.

Create a data type#

POST /api/v1/branches/main/domains/brewery/data-types
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "TVQR",
  "label": "TVQ with Rate",
  "comment": "Measurement tuple carrying a derived rate",
  "fields": ["Timestamp", "Value", "Quality", "Rate"],
  "timeAxisField": "Timestamp"
}

Response - 201 Created, body is the created data-type read model.

Three rules bite here:

• Fields are selected, not defined. Each entry must already exist as a property in the scope or in an imported library. The write mints only the field-membership edge; the linked property already carries its own range.
• No field may resolve to a property declared by an import when the compound itself is local, because the scope-filtered save would drop that back-pointer. This is rejected rather than allowed to become a phantom write.
• The array is a complete roster. There is no per-field add or remove operation.

An unresolvable timeAxisField fails the write with DataType.UnknownTimeAxisField.

Update a data type#

Update is PUT, not PATCH. The backend retracts the prior compound and re-emits the class plus every field edge in one commit, so relabelling, adding, removing and reordering fields all land together.

PUT /api/v1/branches/main/domains/brewery/data-types/TVQR
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "label": "TVQ with Rate",
  "comment": "Measurement tuple carrying a derived rate",
  "fields": ["Timestamp", "Value", "Quality", "Rate", "Confidence"],
  "timeAxisField": "Timestamp"
}

Response - 200 OK, body is the updated read model. 404 when the name does not exist.

Delete a data type#

DELETE /api/v1/branches/main/domains/brewery/data-types/TVQR
Authorization: Bearer <your-pulse-token>

Response - 204 No Content, or 409 Conflict with target and dependents when something still references it.

Two reference shapes block the delete:

{
  "type": "https://atlas.timebase.io/errors/delete-blocked",
  "title": "Delete Blocked",
  "status": 409,
  "detail": "Cannot delete 'TVQR' — it is referenced by 1 dependent.",
  "target": { "name": "TVQR", "kind": "dataType" },
  "dependents": [
    { "id": "Flow", "name": "Flow", "kind": "property", "referenceType": "property-ranges-over-data-type" }
  ]
}

Enumeration types#

An enumeration type is a closed list of codes, each with an identifier and a display label: an asset status, a criticality level, a machine state. It holds no values itself. A property points at it with enumType, as described in Bind a property to an enumeration type.

Routes#

Declared (domain) and (library).

Create an enumeration type#

POST /api/v1/branches/main/libraries/plant-assets/enum-types
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "CriticalityLevel",
  "label": "Criticality Level",
  "comment": "How much an asset failure affects production",
  "keyType": "string",
  "members": [
    { "key": "A", "name": "High",   "label": "A - production stops" },
    { "key": "B", "name": "Medium", "label": "B - production slows" },
    { "key": "C", "name": "Low",    "label": "C - no production impact" }
  ]
}

Response - 201 Created, body is the read model:

{
  "uri": "urn:atlas:ontology:plant-assets:CriticalityLevel",
  "label": "Criticality Level",
  "comment": "How much an asset failure affects production",
  "keyType": "http://www.w3.org/2001/XMLSchema#string",
  "members": [
    { "key": "A", "name": "High",   "label": "A - production stops" },
    { "key": "B", "name": "Medium", "label": "B - production slows" },
    { "key": "C", "name": "Low",    "label": "C - no production impact" }
  ]
}

An unsupported key type, a key that is not a valid value of the key type, an invalid member name, or a duplicate key or name fails with 400 and the error key EnumType.Invalid. The detail names the offending member. A same-kind duplicate fails with 409 and EnumType.AlreadyExists.

Update an enumeration type#

Update is PUT, and members is a full replacement, so adding, removing and reordering members land together:

PUT /api/v1/branches/main/libraries/plant-assets/enum-types/CriticalityLevel
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "label": "Criticality Level",
  "comment": "How much an asset failure affects production",
  "keyType": "string",
  "members": [
    { "key": "A", "name": "High",   "label": "A - production stops" },
    { "key": "B", "name": "Medium", "label": "B - production slows" },
    { "key": "C", "name": "Low",    "label": "C - no production impact" },
    { "key": "X", "name": "Retired", "label": "Retired asset" }
  ]
}

The name in the route cannot change. Response - 200 OK, or 404 when the name does not exist.

Delete an enumeration type#

DELETE /api/v1/branches/main/libraries/plant-assets/enum-types/CriticalityLevel
Authorization: Bearer <your-pulse-token>

Response - 204 No Content, or 409 Conflict when something still uses it. The body has the same shape as the data-type delete conflict, with a target of kind enumType and the full dependents list:

Remove each binding, then delete.

Relationship types#

A relationship type is a named, directed connection with a Source end and a Target end. In Atlas a relationship is a thing, not a line: it is reified as an instance in its own right, it carries its own property values, and it is created by its own instance map with top-level source and target templates.

Routes#

Declared (domain) and (library).

List all relationship types#

GET /api/v1/branches/main/domains/brewery/relationship-types
Authorization: Bearer <your-pulse-token>

Response - 200 OK

[
  {
    "uri": "urn:atlas:ontology:brewery:LineContainsPump",
    "label": "Line Contains Pump",
    "comment": "Physical containment of a pump within a brewing line",
    "baseType": "urn:atlas:vocab:ContainsBase",
    "sourceNodeType": "urn:atlas:ontology:brewery:BrewingLine",
    "targetNodeType": "urn:atlas:ontology:brewery:Pump",
    "properties": ["urn:atlas:ontology:brewery:CommissionedOn"],
    "isContainment": true
  }
]

Create a relationship type#

POST /api/v1/branches/main/domains/brewery/relationship-types
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "LineContainsPump",
  "baseType": "ContainsBase",
  "label": "Line Contains Pump",
  "comment": "Physical containment of a pump within a brewing line",
  "sourceNodeType": "BrewingLine",
  "targetNodeType": "Pump",
  "properties": ["CommissionedOn"]
}

Response - 201 Created, body is the created read model with parent and merged inherited constraints populated.

Edge properties

properties is how a relationship carries data of its own: a flow rate on a feeds, a commissioning date on a contains. Each entry becomes an owl:Restriction on the relationship class, the same shape the Source and Target ends use, so no new vocabulary is involved.

A Defer property can be an edge property. The relationship type then reports O-B23 and cannot compile until the property is pinned, on the property or on the relationship type with propertyPins. See Defer properties and rule O-B23.

Primitive-ranged edge properties compile end to end. Give a relationship property a scalar value type such as xsd:double, or carry a compound on one of the connected entity types.

Allow several entity types at one end#

A single sourceNodeType allows one entity type and its subtypes. When a connection can start or end at unrelated types, list them in sourceUnion or targetUnion instead of leaving the end unconstrained:

POST /api/v1/branches/main/libraries/plant-assets/relationship-types
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "Feeds",
  "baseType": "RelationshipBase",
  "label": "Feeds",
  "sourceUnion": ["Equipment", "Stockpile"],
  "targetUnion": ["Equipment", "Stockpile"],
  "inverseName": "FedBy",
  "properties": ["SplitPercent"]
}

• Each entry must be an existing entity type. An unknown name reports O-B1, and something that is not an entity type reports O-B4.
• Subtypes count. An instance of any listed type, or of a subtype of one, satisfies the end. A connection whose end is of another type reports I-B7 when the instance map is validated.
• The read model reports what is stored. Two or more types read back as sourceUnion, with sourceNodeType omitted. A one-entry list is stored as a plain single-type end and reads back as sourceNodeType.

Name the reverse direction#

inverseName names the same connection as seen from the Target end. It adds no second connection and stores nothing per instance: it is another way to read the one you already have.

Where it is used:

• In Cypher. The inverse name is accepted as a relationship type and matches the connection backwards. With "inverseName": "FedBy" on Feeds, these two queries return the same rows:

  textCopy

  MATCH (a)-[:FedBy]->(b) RETURN a, b
  MATCH (b)-[:Feeds]->(a) RETURN a, b
  

  If a relationship type's own name is the same as another type's inverse name, the forward type wins.

• In the i3X API, as the reverse direction of the relationship type.

The rules, all checked when the scope is validated:

• It shares the URN namespace. The inverse direction is identified as urn:atlas:ontology:{scope}:{inverseName}, so it must not equal the relationship type's own name, another relationship type's inverse name in the same scope, or the name of any other element in the scope. Each case reports O-B12.
• Reusing an ancestor's inverse name is a warning, O-B13. It is allowed, but the same inverse name then means two different things in one hierarchy.

Update a relationship type#

PATCH /api/v1/branches/main/domains/brewery/relationship-types/LineContainsPump
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "label": "Brewing Line Contains Pump",
  "targetNodeType": "CentrifugalPump",
  "properties": []
}

PATCH is a partial merge. Note that name and baseType are not updatable.

Response - 200 OK, or 404 when the name does not exist.

The ""-to-clear sentinel on the endpoints is undiscoverable from the wire and there is no other way to relax a constrained end back to "any node". Note the asymmetry: on comment, "" sets an empty comment; on the two endpoints, "" is a clear sentinel.

Delete a relationship type#

DELETE /api/v1/branches/main/domains/brewery/relationship-types/LineContainsPump
Authorization: Bearer <your-pulse-token>

Response - 204 No Content. 404 when the name does not exist.

Like entity types, relationship types have no per-item dependents guard. A dangling reference is caught by whole-scope re-validation, which aborts the write.

Functions#

A function is reusable calculation logic with named parameters, one structured output, an inline C# body, and optionally a normalization anchor. Functions have full CRUD on both scopes. They are not read-only and they are not written for you by the instance-map layer.

A function has no schedule and no trigger settings. A calculated value is worked out when something reads it.

Routes#

Declared (domain) and (library).

List all functions#

GET /api/v1/branches/main/domains/brewery/functions
Authorization: Bearer <your-pulse-token>

Response - 200 OK

[
  {
    "uri": "urn:atlas:ontology:brewery:ConvertFlowRate",
    "label": "Convert Flow Rate",
    "comment": "Scales a raw flow reading by a calibration coefficient",
    "parameters": [
      {
        "name": "rawFlow",
        "type": "http://www.w3.org/2001/XMLSchema#double",
        "predicateUri": "urn:atlas:ontology:brewery:param/rawFlow",
        "required": true
      },
      {
        "name": "coefficient",
        "type": "http://www.w3.org/2001/XMLSchema#double",
        "predicateUri": "urn:atlas:ontology:brewery:param/coefficient",
        "required": true
      }
    ],
    "output": {
      "name": "flow",
      "type": "http://www.w3.org/2001/XMLSchema#double",
      "predicateUri": "urn:atlas:ontology:brewery:output/flow"
    },
    "returnType": "http://www.w3.org/2001/XMLSchema#double",
    "implementation": {
      "body": "return rawFlow * coefficient;"
    }
  }
]

Create a function#

POST /api/v1/branches/main/domains/brewery/functions
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "ConvertFlowRate",
  "label": "Convert Flow Rate",
  "comment": "Scales a raw flow reading by a calibration coefficient",
  "parameters": [
    {
      "name": "rawFlow",
      "type": "xsd:double",
      "predicateUri": "urn:atlas:ontology:brewery:param/rawFlow",
      "required": true
    },
    {
      "name": "coefficient",
      "type": "xsd:double",
      "predicateUri": "urn:atlas:ontology:brewery:param/coefficient",
      "required": true
    }
  ],
  "output": {
    "name": "flow",
    "type": "xsd:double",
    "predicateUri": "urn:atlas:ontology:brewery:output/flow"
  },
  "implementation": {
    "body": "return rawFlow * coefficient;"
  }
}

Response - 201 Created. The body is a save envelope, not the bare read model:

{
  "function": { "uri": "urn:atlas:ontology:brewery:ConvertFlowRate", "...": "..." },
  "compileDiagnostics": [
    {
      "id": "CS0019",
      "severity": "Error",
      "message": "Operator '*' cannot be applied to operands of type 'string' and 'double'",
      "line": 1,
      "column": 8
    }
  ]
}

Atlas compiles the body as part of the save and returns the compiler's diagnostics in compileDiagnostics, empty when the body is clean. line and column are 1-based and relative to the first line of the body you sent, not to a file.

The save itself is not blocked by a diagnostic: a body that does not compile is still stored, and the function is set aside at compile time until it does. Treat a non-empty compileDiagnostics as work to finish rather than as a failed write. A 422 remains the validation path, for the O-F rules.

The predicate URIs are domain-shared and reused across functions. They follow the convention {scope-urn}:param/{name} and {scope-urn}:output/{name}. They are what an instance map's Calculated strategy binds arguments against, so they are part of your model's contract, not an implementation detail.

Anchors and multi-row normalization

An anchor turns a scalar converter into one that aligns two or more time series onto a common instant before calculating.

{
  "anchor": {
    "outputField": "Timestamp",
    "inputs": [
      { "parameterName": "rawFlow",     "inputField": "Timestamp" },
      { "parameterName": "coefficient", "inputField": "Timestamp" }
    ]
  }
}

When anchor is set, the compiler runs the function multi-row and auto-injects a single anchor local fed by the union of the contributing inputs. null or an empty inputs array means single-row, and no provenance nodes are emitted.

Point normalization needs both halves: the data type must declare a time axis, and the function must declare contributing anchor inputs. Without both, the calculation returns a number built from each input at its latest known value, which is the ordinary behaviour.

Update a function#

Update is PUT. The backend retracts the prior fno:Function subgraph and re-asserts a complete one, so relabelling and signature, output, implementation and anchor changes all land in one commit.

PUT /api/v1/branches/main/domains/brewery/functions/ConvertFlowRate
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "label": "Convert Flow Rate (calibrated)",
  "implementation": {
    "body": "return rawFlow * coefficient * 1.02;"
  }
}

Despite the PUT verb, each top-level field is independently nullable and null means "leave unchanged" (UpdateFunctionRequest):

Response - 200 OK, or 404 when the name does not exist, or 422 on validation.

Malformed URIs: 400#

Before the validator runs, a create or update is refused with 400 and the error key below when a URI field is malformed. This applies to both /app and /api/v1, on create and update.

Function validation: O-F1 to O-F6#

Functions are the one ontology resource with a synchronous pre-save validator. A rejected create or update returns 422 Unprocessable Content as application/problem+json and nothing is persisted, so the draft-session behaviour described earlier does not apply.

O-F6 checks only names that are new or changed on an update, so a function saved under the older, looser rule stays editable. An input named anchor on an anchored function is refused on every save. The messages are:

• Input 'flow rate' has an invalid name. An input name can only contain letters, digits and underscores (_), and cannot start with a digit.
• Input 'class' has an invalid name: 'class' is a reserved word in C#. Choose another name.
• Input 'anchor' has an invalid name: 'anchor' is reserved for the anchor of an anchored function. Choose another name.
• Output 'flow rate' has an invalid name. An output name can only contain letters, digits, underscores (_) and hyphens (-).

The 422 body:

{
  "type": "https://atlas.timebase.io/errors/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "1 violation(s) found in brewery.",
  "violations": [
    {
      "ruleId": "O-F4",
      "severity": "Error",
      "filePath": "ontology.jsonld",
      "message": "A function must declare exactly one output."
    }
  ]
}

jsonPointer, instanceId and suggestion also appear on each violation when populated, and occurrences says how many violations the entry stands for. It is almost always 1; the count in detail sums it rather than counting array entries.

Delete a function#

DELETE /api/v1/branches/main/domains/brewery/functions/ConvertFlowRate
Authorization: Bearer <your-pulse-token>

Response - 204 No Content, or 409 Conflict when an instance-map Calculated strategy still references it.

{
  "type": "https://atlas.timebase.io/errors/delete-blocked",
  "title": "Delete Blocked",
  "status": 409,
  "detail": "Cannot delete 'ConvertFlowRate' — it is referenced by 1 dependent.",
  "target": { "name": "ConvertFlowRate", "kind": "function" },
  "dependents": [
    { "id": "pumps", "name": "pumps", "kind": "instanceMap", "referenceType": "calculated-strategy" }
  ]
}

Clear the block by changing the strategy on each listed instance map first.

A delete also removes each input's shared property when no other function uses it and nothing else uses it as a property. An input property that is still in use stays. Renaming or removing an input on an update does the same for the property it leaves behind. The in-use check is scoped to the Domain or Library that owns the function: a Domain that imports a Library and has attached one of the Library's input properties to its own types is not consulted, and the property is still removed with the Library function.

Errors on this surface#

All failures are RFC-9457 application/problem+json. The full type-URI table lives in the Atlas API Overview. These are the shapes specific to the ontology resources:

A write from a domain to a property that one of its libraries declares is refused with 400 invalid-request, and the detail carries the message:

The /app plane is not an alternative#

Every route in this article has a twin under /app/branches/{branch}/... that dispatches the same commands and returns the same wire shapes. It is private glue for the Atlas single-page application, excluded from the published API documents, gated by a session cookie for reads and an inline admin check for writes. A bearer token does not clear it.

Browser code inside Atlas uses /app. Machine integrations use /api/v1. Picking the wrong one is a guaranteed 401. Do not build against /app.

Troubleshooting#

Related articles#

• Atlas API Overview - base address, authentication, the full route table, RFC-9457 errors, pagination
• Timebase Atlas Key Concepts - the vocabulary this article assumes
• Validation Rules Reference - every O-A*, O-B*, O-F*, I-A* and I-B* rule
• Atlas API - Instance Maps - authoring the instances these types describe, including relationship instance maps
• Atlas API - Domains and Atlas API - Libraries - creating the scopes these routes address
• Atlas API - Compile and Query - reading the compiled World
• Compiling and Publishing a Domain - the compile lifecycle and draft publishing