---
title: "Ontology"
description: "Define device types, the metrics they emit, and their property schemas."
icon: "sitemap"
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

The **Ontology** consists of platform primitives which are configured to fit the exact shape and schema of your data: 
from the types of devices you have and the data they produce to transactions and integrations your workflows are composed of. 

The typical starting primitives to onboard are the ones which represent the hardware types and data signals associated to those types:

- **Thing types** define a kind of device: which metrics it reports and which properties it
  carries. They're versioned.
- **Metric definitions** define a single measurement: its data type, unit, and default
  aggregation. Metrics are reused across many thing types.

The Ontology page has three tabs: a **relationship graph** (thing types linked to the metrics
they include), **metric definitions**, and **thing type definitions**.

<Frame>
  <img src="/images/console/ontology-graph.png" alt="The Ontology relationship graph" />
</Frame>

<Note>
This page describes managing the ontology in the console. For the concepts behind it (how
thing types reference metrics, how properties and versioning work, and metric reuse), see
[Data model](/platform/data-model).
</Note>

## Thing types

A thing type has a stable identity (the **index**, `tdefi_`) that points at its latest
**version** (`tdef_`) and keeps the full version history. A device binds to a specific version,
which fixes the metric set and property schema that apply to it.

### Fields

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| Display name | string (1–100) | Yes | |
| Description | string (0–500) | No | |
| Metric ids | list | Yes | The metrics this version reports |
| Property definitions | list | No | Typed property schema (see below) |
| Model metadata | object | No | Manufacturer, model, hardware revision, certifications, and more |
| Tags | list | No | |
| Default image / icon URL | URL | No | Index-level visual assets |

<Frame>
  <img src="/images/console/ontology-thing-type-form.png" alt="The thing type version form" />
</Frame>

### Versioning

Each version is a full snapshot. You change the metric set by creating a **new version**, not
by editing an existing one. The "create version" form pre-fills every field from the latest
version. A response also reports `deletedMetricIds`: metrics that earlier versions had but this
one dropped.

When updating an existing version, you can change its display name, description, tags, model
metadata, and property definitions, but **not its metric ids**.

## Metric definitions

A metric definition (surfaced as `metricId`) describes one measurement.

| Field | Type | Required | Mutable | Notes |
|-------|------|----------|---------|-------|
| Name | string | Yes | No | Programmatic name; fixed after creation |
| Data type | enum | Yes | No | See below |
| Default aggregation | enum | Yes | No | See below |
| Display name | string | No | Yes | |
| Description | string | No | Yes | |
| Unit label | string | No | Yes | |
| Tags | list | No | Yes | |
| Enum values | list | No | Yes | Only valid when the data type is `Int` |

### Data types

| Data type | Notes |
|-----------|-------|
| `Int` | Integer |
| `Double` | Floating point |
| `String` | Text |
| `Bool` | Boolean |
| `Json` | JSON document |

There's no separate "enum" data type. An enum metric is an `Int` with a non-empty list of
**enum values**, each mapping an integer `code` to a `name` (plus optional display name and
description). Codes are append-only and unique; names are required and unique.

### Aggregations

`defaultAggregation` is how the metric is combined when binned.

| Data type | Allowed aggregations |
|-----------|----------------------|
| `Int`, `Double` | `First`, `Last`, `Sum`, `Min`, `Max`, `Avg`, `Count` |
| `String`, `Bool`, `Json` | `First`, `Last`, `Count` |
| Enum (`Int` + enum values) | `First`, `Last`, `Count` |

Arithmetic aggregations are disallowed for enums, since the codes have no numeric meaning.

## Property definitions

Properties are typed, predefined attributes a device of this type carries (for example a
battery's capacity). Each property has:

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| Name | string | Yes | |
| Value type | enum | Yes | `string`, `int`, `double`, `bool` |
| Description | string | No | |
| Unit | string | No | |
| Constraints | list | No | Validation rules (see below) |

A constraint is an **operator** plus a **value**. Operators: `>`, `>=`, `<`, `<=`, `==`, `!=`.

When updating a version, omitting `propertyDefinitions` leaves them unchanged; passing a list
replaces them entirely; passing an empty list removes them all.

## States

- **Lifecycle status:** list endpoints take `status` = `active` (default), `deleted`, or `all`.
  Deletes are soft, so entities carry an `isDeleted` flag.
- **Graph layouts:** the relationship graph renders as `bipartite` (default), `galaxy`, or
  `force`.

## API

Send your API key in the `X-Api-Key` header. Reads need a `read` scope; create, update, and
delete need `write`. Ids: thing-type index `tdefi_`, thing-type version `tdef_`, metric
`mdef_`. These are version 2 endpoints. The thing-type endpoints are also in the
**API Reference** tab.

### Thing types

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/v2/definitions/thing-types` | List thing types (paginated) |
| `POST` | `/v2/definitions/thing-types` | Create a thing type (its first version) |
| `GET` | `/v2/definitions/thing-types/{thingTypeId}` | Get one thing type |
| `PUT` | `/v2/definitions/thing-types/{thingTypeId}` | Update index metadata |
| `DELETE` | `/v2/definitions/thing-types/{thingTypeId}` | Soft-delete a thing type |
| `GET` | `/v2/definitions/thing-types/{thingTypeId}/versions` | List version history |
| `POST` | `/v2/definitions/thing-types/{thingTypeId}/versions` | Create a new version |
| `GET` | `/v2/definitions/thing-types/versions/{thingTypeDefId}` | Get one version (`?includeMetricDefinitions=true` resolves metrics) |

### Metric definitions

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/v2/definitions/metrics` | List metrics (paginated) |
| `GET` | `/v2/definitions/metrics/{metricId}` | Get one metric |
| `POST` | `/v2/definitions/metrics` | Create a metric |
| `PUT` | `/v2/definitions/metrics/{metricId}` | Update mutable fields |
| `DELETE` | `/v2/definitions/metrics/{metricId}` | Soft-delete a metric |