Data model

Why this exists

Before the platform can accept telemetry from a device, it needs to know what kind of device it is and what data to expect. We call this the ontology, the platform's vocabulary to describe your devices.

You define the ontology yourself, through the API. It's data, not hard-coded: each organization owns its own definitions, and they're versioned so they can evolve over time.

There's no single "ontology" object. Instead, the ontology is three cooperating pieces:

• A Thing Type Definition is the type of a device, e.g. "Battery".
• It references Metric Definitions: what the device measures (soc, soh, latitude, etc.).
• It includes Property Definitions: static attributes (capacity, reporting interval, etc.).

A simple way to think about this: Things are instances of Thing Type Definitions.

Metric Definition

A Metric Definition describes a single measurable quantity. You create these first, then reference them from your Thing Types.

Two things to know:

• defaultAggregation is how the data reads back. A state-of-charge metric uses Last (you want the most recent value in a window); an energy total might use Sum. Choose it to match the physical meaning of the metric.
• Enum-shaped metrics: when dataType is Int and you supply enumValues, the metric represents discrete states (e.g. 0 = Idle, 1 = Charging). Codes are append-only and immutable. Labels can change. Aggregation is limited to First/Last/Count.

Each metric is identified by a stable id (mdef_…) and a name. The name is what you put in telemetry payloads and query strings, so treat it as part of your contract. Renaming a metric is not a casual change.

Thing Type Definition

A Thing Type Definition ties metrics and properties together into a named device type.

Key ideas:

• Types reference metrics, they don't own them. Because metricIds is a list of references, the same metric can be shared across multiple types (see Metric reuse below).
• Types are scoped to your organization. Your "Battery" type is yours; another org's "Battery" can have entirely different metrics.

Property Definition

Where a metric is a time-series measurement, a Property Definition is a static attribute of a device, configured once, like a battery's capacity or its reporting interval. Property definitions live inline on the Thing Type.

When you set a property on a Thing, the platform validates it against that Thing's type: an unknown property name is rejected, and constraints define the allowed range. This is how you keep device configuration consistent.

Versioning

Thing Types are immutably versioned, which gives each type a two-part identity:

• A stable id (tdefi_…) identifies the type itself, "the Battery type". It never changes.
• A version id (tdef_…) identifies one immutable snapshot of that type's metrics and properties. Creating a "new version" adds a new snapshot; earlier versions are untouched.

A Thing records both: the stable type it is, and the exact version it was created against. That version fixes which metric set applies to it. Devices created under v1 and v2 of a type coexist cleanly. Old data stays readable as your schema evolves.

Metric reuse

Because a Thing Type references metrics by id, the same Metric Definition can be shared across types. Define soc (state of charge) once and reference it from both Battery and SwapStation; define latitude/longitude once and share them across Battery and a Scooter type.

Defining a metric once and reusing it makes data comparable across device kinds: a query for soc means the same thing whether the reading came from a Battery or a SwapStation.

Managing the ontology

These live under the v2 definitions endpoints of the Aerovy Platform API.

Metric Definitions

Thing Type Definitions

Exact request/response fields are documented in the API Reference. The Ingesting data guide shows these in a worked example.

Recap

Devices aren't hard-coded; they're defined: per organization, versioned, with units, aggregation rules, validation, and reuse.