Entities overview

The data model, and how it powers your common operating picture

An entity is an interoperable data structure that powers the Lattice common operational picture (COP).

An entity consists of components. The presence or absence of components, rather than a strict type hierarchy, determines what an entity is and how it should be interacted with. Think of an entity as a bag of components that you can mix and match as needed. Entities might be incomplete at various points in time, reflecting the real-time state of the COP. Partial states are valuable for situational awareness, so your code must handle missing components robustly.

Composition principles

  • Components must not be duplicative — Avoid modeling the same underlying data on two different components.
  • Components are non-hierarchical — The data model is composable and not an inheritance tree.

Entity model

An entity requires the following components:

entity_id
StringRequired

Unique string identifier. Can be a Globally Unique Identifier (GUID).

is_live
BooleanRequired

A boolean that when set to true, creates, or updates the entity. If set to false, while the entity is still live, it triggers a DELETE event.

expiry_time
DatetimeRequired

The future time, less than 30 days, at which the entity expires. When the expiry_time has passed, Lattice deletes the entity.

provenance.integration_name
stringRequired

The name of the integration that created this entity.

aliases.name
string

Human-readable string that represents the name of an entity.

For more information, see Entities in the Lattice API Reference.

Entity templates

Although there is no strict type hierarchy, a user interface could group entities according to its ontology component. Lattice supports the following three top-level entity shapes:

Asset

An asset is an entity under your control, or under the control of another operator or system. Assets may accept tasks such as search or tracking. To create an asset, add the following components in addition to the required components:

ontology
OntologyRequired

Add the ontology component and set template to TEMPLATE_ASSET to render an asset in Lattice.

location
LocationRequired

Add the location component and set the asset’s position using its latitude and longitude details.

milView
MilViewRequired

Add the milView component and set the disposition, environment, and nationality of the asset.

Example entity models:

asset.json
1{
2 "entityId": "UNIQUE_ENTITY_ID",
3 "description": "Asset",
4 "ontology": {
5 "template": "TEMPLATE_ASSET",
6 "platform_type": "Submarine"
7 },
8 "location": {
9 "position": {
10 "latitudeDegrees": 50.91402185768586,
11 "longitudeDegrees": 0.79203612077257,
12 "altitudeHaeMeters": 2994,
13 "altitudeAglMeters": 2972.8
14 }
15 },
16 "milView": {
17 "disposition": "DISPOSITION_FRIENDLY",
18 "environment": "ENVIRONMENT_SUB_SURFACE"
19 },
20 "aliases": {
21 "name": "Dive"
22 },
23 "provenance": {
24 "integrationName": "your_integration_name",
25 "dataType": "your_data_type",
26 "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
27 },
28 "isLive": true,
29 "createdTime": "2024-12-07T00:09:42.816877Z",
30 "expiryTime": "2024-12-17T00:09:42.816878Z",
31}
asset.json
1{
2 "entityId": "UNIQUE_ENTITY_ID",
3 "description": "Asset",
4 "ontology": {
5 "template": "TEMPLATE_ASSET",
6 "platform_type": "Radar"
7 },
8 "location": {
9 "position": {
10 "latitudeDegrees": 50.91402185768586,
11 "longitudeDegrees": 0.79203612077257
12 }
13 },
14 "milView": {
15 "disposition": "DISPOSITION_FRIENDLY",
16 "environment": "ENVIRONMENT_SURFACE"
17 },
18 "aliases": {
19 "name": "Tower"
20 },
21 "provenance": {
22 "integrationName": "your_integration_name",
23 "dataType": "your_data_type",
24 "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
25 },
26 "isLive": true,
27 "createdTime": "2024-12-07T00:09:42.816877Z",
28 "expiryTime": "2024-12-17T00:09:42.816878Z",
29}
asset.json
1{
2 "entityId": "UNIQUE_ENTITY_ID",
3 "description": "Asset",
4 "ontology": {
5 "template": "TEMPLATE_ASSET",
6 "platform_type": "UAV"
7 },
8 "location": {
9 "position": {
10 "latitudeDegrees": 50.91402185768586,
11 "longitudeDegrees": 0.79203612077257,
12 "altitudeHaeMeters": 2994,
13 "altitudeAglMeters": 2972.8
14 }
15 },
16 "milView": {
17 "disposition": "DISPOSITION_FRIENDLY",
18 "environment": "ENVIRONMENT_AIR"
19 },
20 "aliases": {
21 "name": "UAV"
22 },
23 "provenance": {
24 "integrationName": "your_integration_name",
25 "dataType": "your_data_type",
26 "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
27 },
28 "isLive": true,
29 "createdTime": "2024-12-07T00:09:42.816877Z",
30 "expiryTime": "2024-12-17T00:09:42.816878Z"
31}

Track

A track represents any entity tracked by an asset or integration connected to Lattice. Tracks are not directly under the control of friendly forces. This includes aircraft tracks from radar or sensors, signal detections, vehicles, people, or animals detected through cameras.

Lattice supports the following track types:

ontology
Required

Add the ontology component and set template to TEMPLATE_TRACK to render a generic track.

location
Required

Add the location component to set the latitude and longitude of the track.

milView
Required

Add the milView component to set the disposition, environment, and nationality of the track.

Example entity models:

track.json
1{
2 "entityId": "UNIQUE_ENTITY_ID",
3 "description": "Airplane",
4 "ontology": {
5 "template": "TEMPLATE_TRACK",
6 "platform_type": "Airplane"
7 },
8 "location": {
9 "position": {
10 "latitudeDegrees": 50.91402185768586,
11 "longitudeDegrees": 0.79203612077257,
12 "altitudeHaeMeters": 46.214997987295234
13 }
14 },
15 "milView": {
16 "disposition": "DISPOSITION_FRIENDLY",
17 "environment": "ENVIRONMENT_AIR"
18 },
19 "aliases": {
20 "name": "Friendly Airplane"
21 },
22 "provenance": {
23 "integrationName": "your_integration_name",
24 "dataType": "your_data_type",
25 "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
26 },
27 "isLive": true,
28 "createdTime": "2024-12-07T00:19:46.706195Z",
29 "expiryTime": "2024-12-07T00:24:46.706196Z"
30}
track.json
1{
2 "entityId": "UNIQUE_ENTITY_ID",
3 "description": "Animal",
4 "ontology": {
5 "template": "TEMPLATE_TRACK",
6 "platform_type": "Animal"
7 },
8 "location": {
9 "position": {
10 "latitudeDegrees": 50.91402185768586,
11 "longitudeDegrees": 0.79203612077257,
12 "altitudeHaeMeters": 46.214997987295234
13 }
14 },
15 "milView": {
16 "disposition": "DISPOSITION_NEUTRAL",
17 "environment": "ENVIRONMENT_AIR"
18 },
19 "provenance": {
20 "integrationName": "your_integration_name",
21 "dataType": "your_data_type",
22 "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
23 },
24 "aliases": {
25 "name": "Bird"
26 },
27 "isLive": true,
28 "createdTime": "2024-12-07T00:19:46.706195Z",
29 "expiryTime": "2024-12-07T00:24:46.706196Z"
30}

Geo-entity

A geo-entity is a shape, region, or point of interest drawn on the map. Use geo-entities to represent any geographical areas of interest, such as airfields or a control zones, for autonomous vehicles to operate in.

ontology.template
Required

Add the ontology component and set template to TEMPLATE_GEO to render a geo-entity shape.

geo_details
Required

Add the geo_details component.

geo_shape
Required

Add the geo_shape component.

location

Add the location component, if geo_shape is set to ellipse.

Example entity models

geo.json
1{
2 "entityId": "UNIQUE_ENTITY_ID",
3 "description": "Geo point",
4 "isLive": true,
5 "createdTime": "2024-12-07T00:45:15.581592Z",
6 "expiryTime": "2024-12-07T00:50:15.581598Z",
7 "provenance": {
8 "integrationName": "your_integration_name",
9 "dataType": "your_data_type",
10 "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
11 },
12 "geoShape": {
13 "point": {
14 "position": {
15 "latitudeDegrees": 50.91402185768586,
16 "longitudeDegrees": 0.79203612077257,
17 "altitudeHaeMeters": 46.214997987295234,
18 "altitudeAglMeters": 0.5000067609670396
19 }
20 }
21 },
22 "geoDetails": {
23 "type": "GEO_TYPE_GENERAL"
24 },
25 "aliases": {
26 "name": "Point"
27 },
28 "ontology": {
29 "template": "TEMPLATE_GEO"
30 }
31}
geo.json
1{
2 "entityId": "UNIQUE_ENTITY_ID",
3 "description": "Polygon 1",
4 "isLive": true,
5 "createdTime": "2024-12-07T00:55:43.183738Z",
6 "expiryTime": "2024-12-07T01:00:43.183743Z",
7 "aliases": {
8 "name": "Polygon"
9 },
10 "ontology": {
11 "template": "TEMPLATE_GEO"
12 },
13 "provenance": {
14 "integrationName": "your_integration_name",
15 "dataType": "your_data_type",
16 "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
17 },
18 "geoDetails": {
19 "type": "GEO_TYPE_GENERAL"
20 },
21 "geoShape": {
22 "polygon": {
23 "rings": [
24 {
25 "positions": [
26 {
27 "position": {
28 "latitudeDegrees": 49.01611140463143,
29 "longitudeDegrees": 1.5746513124955297
30 }
31 },
32 {
33 "position": {
34 "latitudeDegrees": 49.01924140463143,
35 "longitudeDegrees": 2.882469645828863
36 }
37 },
38 {
39 "position": {
40 "latitudeDegrees": 48.4172380712981,
41 "longitudeDegrees": 2.9189863124955298
42 }
43 },
44 {
45 "position": {
46 "latitudeDegrees": 49.01611140463143,
47 "longitudeDegrees": 1.5746513124955297
48 }
49 }
50 ]
51 }
52 ]
53 }
54 }
55}
geo.json
1{
2 "entityId": "UNIQUE_ENTITY_ID",
3 "description": "Geo ellipse",
4 "isLive": true,
5 "createdTime": "2024-12-07T01:06:32.834952Z",
6 "expiryTime": "2024-12-07T01:11:32.834954Z",
7 "aliases": {
8 "name": "Ellipse"
9 },
10 "ontology": {
11 "template": "TEMPLATE_GEO"
12 },
13 "provenance": {
14 "integrationName": "your_integration_name",
15 "dataType": "your_data_type",
16 "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
17 },
18 "geoDetails": {
19 "type": "GEO_TYPE_CONTROL_AREA"
20 },
21 "geoShape": {
22 "ellipse": {
23 "semiMajorAxisM": 20,
24 "semiMinorAxisM": 20,
25 "orientationD": 40
26 }
27 },
28 "location": {
29 "position": {
30 "latitudeDegrees": 51.46,
31 "longitudeDegrees": -0.16
32 }
33 }
34}
geo.json
1{
2 "entityId": "UNIQUE_ENTITY_ID",
3 "description": "Geo line",
4 "isLive": true,
5 "createdTime": "2024-12-07T01:08:39.079826Z",
6 "expiryTime": "2024-12-07T01:13:39.079828Z",
7 "provenance": {
8 "integrationName": "your_integration_name",
9 "dataType": "your_data_type",
10 "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
11 },
12 "geoShape": {
13 "line": {
14 "positions": [
15 {
16 "latitudeDegrees": 47.605,
17 "longitudeDegrees": -122.329
18 },
19 {
20 "latitudeDegrees": 47.61,
21 "longitudeDegrees": -122.33
22 }
23 ]
24 }
25 },
26 "geoDetails": {
27 "type": "GEO_TYPE_GENERAL"
28 },
29 "aliases": {
30 "name": "Line"
31 },
32 "ontology": {
33 "template": "TEMPLATE_GEO"
34 }
35}

Entity lifecycle

Entities have a well-defined lifecycle of create, update, and delete. On each lifecycle update, Entity Manager emits the state change event back to Lattice:

1

Create

When an app or integration publishes an entity, Lattice emits a state change event, setting the entity state to CREATE.

2

Update

When data in the entity changes, Lattice emits the state change as an update event. To optimize performance, Lattice relies on changes to provenance.source_update_time to trigger an update. It does not compare the full proto definitions to set the state change.

3

Delete

An entity is deleted when its expiry_time has lapsed, or an update is sent with the is_live component set to false. You should handle a delete event by removing all references to it in memory or discarding it from your user interface.

What’s next?