Ontologies

An ontology describes a domain as object types, link types and action types, and may bind each object type to the dataset that holds its instances. It is the semantic layer over your data: what an agent queries first when it is bound to one, and what the platform serves as JSON-LD. An ontology is declarative: it has no lineage edges and no builds. An ontology is identified by res.ontology.… and lives in a project.

The specification

{
  "name": "Sales",
  "project_id": "res.project.…",
  "api_name": "sales",
  "version": "1",
  "object_types": {
    "customer": {
      "display_name": "Customer",
      "primary_key": "customer_id",
      "properties": {
        "customer_id": {"data_type": "string", "required": true},
        "name": {"data_type": "string"},
        "segment": {"data_type": "string"}
      },
      "dataset_id": "res.dataset.…"
    },
    "order": {
      "primary_key": "order_id",
      "properties": {
        "order_id": {"data_type": "long", "required": true},
        "customer_id": {"data_type": "string"},
        "amount": {"data_type": "double"},
        "placed_at": {"data_type": "timestamp"}
      },
      "dataset_id": "res.dataset.…"
    }
  },
  "link_types": {
    "places": {
      "source_object_type": "customer",
      "target_object_type": "order",
      "cardinality": "ONE_TO_MANY",
      "foreign_key_property": "customer_id"
    }
  },
  "action_types": {
    "flag_customer": {
      "parameters": {"customer": {"data_type": {"type": "ontology_object", "object_type_api_name": "customer"}}},
      "rules": [{"parameter": "customer", "property": "segment", "operator": "neq", "value": "vip", "message": "VIP customers are not flagged"}],
      "scope": "datasets:write",
      "operations": [{"type": "modify_object", "parameter": "customer", "properties": {"segment": "flagged"}}]
    }
  }
}

Part	Meaning
`api_name`, `version`, `base_uri`	the ontology’s stable identifier (the name and slug derive from it), its version, and the base of every `@id` (`urn:ontology:<api_name>` by default)
`object_types`	each with a `properties` map (`data_type` among `string`, `integer`, `long`, `short`, `byte`, `double`, `float`, `decimal`, `boolean`, `date`, `timestamp`; `required`), a `primary_key` naming one of them, optional `subtypes` (an is-a list of names)
`link_types`	`source_object_type` → `target_object_type` with a `cardinality` (`ONE_TO_ONE`, `ONE_TO_MANY`, `MANY_TO_MANY`); either end may be a list of alternatives or untyped; `inverse_of` names the reciprocal link
`action_types`	declarative contracts: `parameters` (a primitive, or an object of the ontology), `rules` (preconditions over a parameter’s property, with a message), the `scope` a caller needs, and `operations` (`create_object`, `modify_object`, `delete_object`, `add_link`, `remove_link`), checked in order against the rest of the spec

Identifiers (api_names, property names, subtypes) are [A-Za-z_][A-Za-z0-9_]*, safe as JSON-LD terms and as SQL identifiers. Everything is cross-validated at save time: an action naming a property or an object type that does not exist is a 400, and so is removing an object type a stored link still references. GET /ontologies lists summaries (identity, api_name, version, is_standard); GET /ontologies/{id} returns the whole specification. PATCH replaces each of the three collections wholesale.

Standard ontologies

The platform ships twenty extraction ontologies, object types, subtypes and typed links without properties or bindings, to describe a domain before modelling a schema: general, business, finance, financial_analysis, accounting, insurance, legal, healthcare, human_resources, marketing, real_estate, supply_chain, maritime, energy, environment, esg, research, cyber, security, geopolitics. They are global, readable by everyone, listed with is_standard: true, and the first thing Klara reads before inventing a model.

Binding data

An object type bound to a dataset (dataset_id) has its instances in that dataset: the dataset’s columns must carry the declared property names, and only the declared properties are ever read, so extra columns never leak. A link type is backed either by a foreign key on the target object type (foreign_key_property, for ONE_TO_ONE and ONE_TO_MANY: the column holds the source’s primary key) or by an edge dataset (dataset_id with source_key/target_key columns, source_id/target_id by default).

Objects as JSON-LD

Bound instances are served as application/ld+json, read from the datasets with the same engine as SQL; the caller must be able to read both the ontology and the dataset.

Call	Returns
`GET /ontologies/{id}/objects/{object_type}?limit=&offset=`	the instances, as a JSON-LD `@graph`
`GET /ontologies/{id}/objects/{object_type}/{pk}`	one node
`GET /ontologies/{id}/objects/{object_type}/{pk}/links/{link_type}`	the objects linked to that node
`GET /ontologies/{id}/links/{link_type}`	the edges, as `source`/`target` node references

@ids are {base_uri}/{object_type}/{pk}. Only single-typed links are traversable.

In an agent

An ontology bound to an agent gives it model, list_objects, get_object, list_links and list_linked_objects, and the agent’s instructions ask it to query the ontology first, before the datasets behind it: it is the structured view over the same data. Klara can create and update ontologies when asked to model a domain.

These endpoints are served by the platform and used by the Atlas interface; they are being opened on the public gateway progressively, and the Python library does not wrap them yet. The API reference lists what the gateway exposes today.

Get started

Concepts

Workspace

Data

Code

Build

Models

Inference

Agents

Client

Changelog

The specification

Standard ontologies

Binding data

Objects as JSON-LD

In an agent

​The specification

​Standard ontologies

​Binding data

​Objects as JSON-LD

​In an agent

The specification

Standard ontologies

Binding data

Objects as JSON-LD

In an agent