> This is the Markdown version of the page. For the complete Lattice Developers documentation index, fetch https://developer.anduril.com/llms.txt. Append .md to any page URL for its clean Markdown.

# 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`** `String` — required

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

---

**`is_live`** `Boolean` — required

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`** `Datetime` — required

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`** `string` — required

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](/reference/rest/entities/publish-entity#request)
in the *Lattice API Reference*.

## Entity templates

Although there is no strict type hierarchy, a user interface could group
entities according to its [ontology](/reference/rest/entities/publish-entity#ontology.template) component.
Lattice supports the following three top-level entity shapes:

#### [Asset](/guides/entities/overview#asset)

#### [Track](/guides/entities/overview#track)

#### [Geo-entity](/guides/entities/overview#geo-entity)

### 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`** `Ontology` — required

Add the ontology component and set [`template`](/reference/rest/entities/publish-entity#request.body.ontolog.template)
to `TEMPLATE_ASSET` to render an asset in Lattice.

---

**`location`** `Location` — required

Add the [location](/reference/rest/entities/publish-entity#request.body.location) component
and set the asset's position using its latitude and longitude details.

---

**`milView`** `MilView` — required

Add the [milView](/reference/rest/entities/publish-entity#request.body.milView) component
and set the disposition, environment, and nationality of the asset.

---

**Example entity models**:

#### Submarine

**`asset.json`**

```json title="asset.json" maxLines=25
{
    "entityId": "UNIQUE_ENTITY_ID",
    "description": "Asset",
    "ontology": {
        "template": "TEMPLATE_ASSET",
        "platform_type": "Submarine"
    },
    "location": {
        "position": {
            "latitudeDegrees": 50.91402185768586,
            "longitudeDegrees": 0.79203612077257,
            "altitudeHaeMeters": 2994,
            "altitudeAglMeters": 2972.8
        }
    },
    "milView": {
        "disposition": "DISPOSITION_FRIENDLY",
        "environment": "ENVIRONMENT_SUB_SURFACE"
    },
    "aliases": {
        "name": "Dive"
    },
    "provenance": {
        "integrationName": "your_integration_name",
        "dataType": "your_data_type",
        "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
    },
    "isLive": true,
    "createdTime": "2024-12-07T00:09:42.816877Z",
    "expiryTime": "2024-12-17T00:09:42.816878Z",
}
```

#### Radar

**`asset.json`**

```json title="asset.json" maxLines=25
{
    "entityId": "UNIQUE_ENTITY_ID",
    "description": "Asset",
    "ontology": {
        "template": "TEMPLATE_ASSET",
        "platform_type": "Radar"
    },
    "location": {
        "position": {
            "latitudeDegrees": 50.91402185768586,
            "longitudeDegrees": 0.79203612077257
        }
    },
    "milView": {
        "disposition": "DISPOSITION_FRIENDLY",
        "environment": "ENVIRONMENT_SURFACE"
    },
    "aliases": {
        "name": "Tower"
    },
    "provenance": {
        "integrationName": "your_integration_name",
        "dataType": "your_data_type",
        "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
    },
    "isLive": true,
    "createdTime": "2024-12-07T00:09:42.816877Z",
    "expiryTime": "2024-12-17T00:09:42.816878Z",
}
```

#### UAV

**`asset.json`**

```json title="asset.json" maxLines=25
{
    "entityId": "UNIQUE_ENTITY_ID",
    "description": "Asset",
    "ontology": {
        "template": "TEMPLATE_ASSET",
        "platform_type": "UAV"
    },
    "location": {
        "position": {
            "latitudeDegrees": 50.91402185768586,
            "longitudeDegrees": 0.79203612077257,
            "altitudeHaeMeters": 2994,
            "altitudeAglMeters": 2972.8
        }
    },
    "milView": {
        "disposition": "DISPOSITION_FRIENDLY",
        "environment": "ENVIRONMENT_AIR"
    },
    "aliases": {
        "name": "UAV"
    },
    "provenance": {
        "integrationName": "your_integration_name",
        "dataType": "your_data_type",
        "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
    },
    "isLive": true,
    "createdTime": "2024-12-07T00:09:42.816877Z",
    "expiryTime": "2024-12-17T00:09:42.816878Z"
}
```

### 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:

#### Track

**`ontology`** — required

Add the ontology component and set [`template`](/reference/rest/entities/publish-entity#request.body.ontolog.template)
to `TEMPLATE_TRACK`  to render a generic track.

---

**`location`** — required

Add the [`location`](/reference/rest/entities/publish-entity#request.body.position) component
to set the latitude and longitude of the track.

---

**`milView`** — required

Add the [`milView`](/reference/rest/entities/publish-entity#request.body.milView) component
to set the disposition, environment, and nationality of the track.

---

**Example entity models**:

#### Airplane

**`track.json`**

```json title="track.json" maxLines=25 
{
    "entityId": "UNIQUE_ENTITY_ID",
    "description": "Airplane",
    "ontology": {
        "template": "TEMPLATE_TRACK",
        "platform_type": "Airplane"
    },
    "location": {
        "position": {
            "latitudeDegrees": 50.91402185768586,
            "longitudeDegrees": 0.79203612077257,
            "altitudeHaeMeters": 46.214997987295234
        }
    },
    "milView": {
        "disposition": "DISPOSITION_FRIENDLY",
        "environment": "ENVIRONMENT_AIR"
    },
    "aliases": {
        "name": "Friendly Airplane"
    },
    "provenance": {
        "integrationName": "your_integration_name",
        "dataType": "your_data_type",
        "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
    },
    "isLive": true,
    "createdTime": "2024-12-07T00:19:46.706195Z",
    "expiryTime": "2024-12-07T00:24:46.706196Z"
}
```

#### Bird

**`track.json`**

```json title="track.json" maxLines=25
{
    "entityId": "UNIQUE_ENTITY_ID",
    "description": "Animal",
    "ontology": {
        "template": "TEMPLATE_TRACK",
        "platform_type": "Animal"
    },
    "location": {
        "position": {
            "latitudeDegrees": 50.91402185768586,
            "longitudeDegrees": 0.79203612077257,
            "altitudeHaeMeters": 46.214997987295234
        }
    },
    "milView": {
        "disposition": "DISPOSITION_NEUTRAL",
        "environment": "ENVIRONMENT_AIR"
    },
    "provenance": {
        "integrationName": "your_integration_name",
        "dataType": "your_data_type",
        "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
    },
    "aliases": {
        "name": "Bird"
    },
    "isLive": true,
    "createdTime": "2024-12-07T00:19:46.706195Z",
    "expiryTime": "2024-12-07T00:24:46.706196Z"
}
```

#### Sensor point-of-interest (SPI)

**`ontology`** — required

Add the ontology component and set [`template`](/reference/rest/entities/publish-entity#request.body.ontolog.template)
to `TEMPLATE_SENSOR_POINT_OF_INTEREST` to render a sensor detected at a specific location.

---

**`location`** — required

Add the [`location`](/reference/rest/entities/publish-entity#request.body.position) component
to set the latitude and longitude of the track.

---

**`milView`** — required

Add the [`milView`](/reference/rest/entities/publish-entity#request.body.mil_view) component
to set the disposition, environment, and nationality of the track.

---

**`sensors`**

Optionally, add the [`sensors`](/reference/rest/entities/publish-entity#request.body.sensors) component to
identify details about the sensor type.

---

**Example entity models**:

#### Radar

**`track.json`**

```json title="track.json" maxLines=25
{
    "entityId": "UNIQUE_ENTITY_ID",
    "description": "Sensor",
    "ontology": {
        "template": "TEMPLATE_SENSOR_POINT_OF_INTEREST",
        "platform_type": "Radar"
    },
    "location": {
        "position": {
            "latitudeDegrees": 50.91402185768586,
            "longitudeDegrees": 0.79203612077257,
            "altitudeHaeMeters": 46.214997987295234
        }
    },
    "milView": {
        "disposition": "DISPOSITION_ASSUMED_FRIENDLY",
        "environment": "ENVIRONMENT_SURFACE"
    },
    "sensors": {
        [
            {
                "operationalState": "OPERATIONAL_STATE_OPERATIONAL",
                "sensorType": "SENSOR_TYPE_RADAR"
            }
        ]
    },
    "provenance": {
        "integrationName": "Your Integration",
        "dataType": "Your Data Type",
        "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
    },
    "aliases": {
        "name": "SPI"
    },
    "isLive": true,
    "createdTime": "2024-12-07T00:19:46.706195Z"
    "expiryTime": "2024-12-07T00:24:46.706196Z"
}
```

#### Signal of interest (SOI)

**`ontology.template`** — required

Add the ontology component and set [`template`](/reference/rest/entities/publish-entity#request.body.ontolog.template)
to `TEMPLATE_SIGNAL_OF_INTEREST` to render a signal detection with characteristics
such as emitter notation, frequency, or lines of bearing.

---

**`milView`** — required

Add the [`milView`](/reference/rest/entities/publish-entity#request.body.milView) component
to set the disposition, environment, and nationality of the signal track.

---

**`signal`** — required

Add the [`signal`](/reference/rest/entities/publish-entity#request.body.signal) component
to set the emitter notation, frequency, lines of bearing, and other details about the signal.

---

**`location`**

Optionally, if `signal.fixed` is set, add [location](/reference/rest/entities/publish-entity#request.body.position)
and define the position of the signal track.

---

**Example entity models**:

#### Satellite

**`track.json`**

```json title="track.json" maxLines=25
{
    "entityId": "UNIQUE_ENTITY_ID",
    "description": "Signal",
    "isLive": true,
    "createdTime": "2024-12-07T00:19:46.706195Z",
    "expiryTime": "2024-12-07T00:24:46.706196Z",
    "location": {
        "position": {
            "latitudeDegrees": 50.91402185768586,
            "longitudeDegrees": 0.79203612077257,
            "altitudeHaeMeters": 46.214997987295234
        }
    },
    "aliases": {
        "name": "Satellite 1"
    },
    "milView": {
        "disposition": "DISPOSITION_SUSPICIOUS",
        "environment": "ENVIRONMENT_SPACE"
    },
    "ontology": {
        "template": "TEMPLATE_SIGNAL_OF_INTEREST",
        "platform_type": "Satellite"
    },
    "provenance": {
        "integrationName": "your_integration",
        "dataType": "your_data_type",
        "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
    }
}
```

### 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`](/reference/rest/entities/publish-entity#request.body.ontolog.template)
to `TEMPLATE_GEO` to render a geo-entity shape.

---

**`geo_details`** — required

Add the [`geo_details`](/reference/rest/entities/publish-entity#request.body.geoDetails) component.

---

**`geo_shape`** — required

Add the [`geo_shape`](/reference/rest/entities/publish-entity#request.body.geoShape) component.

---

**`location`**

Add the [`location`](/reference/rest/entities/publish-entity#request.body.location) component, if `geo_shape` is set to
[ellipse](/reference/rest/entities/publish-entity#request.body.geoShape.ellipse).

---

**Example entity models**

#### Point

**`geo.json`**

```json title="geo.json" maxLines=25
{
    "entityId": "UNIQUE_ENTITY_ID",
    "description": "Geo point",
    "isLive": true,
    "createdTime": "2024-12-07T00:45:15.581592Z",
    "noExpiry": true,
    "provenance": {
        "integrationName": "your_integration_name",
        "dataType": "your_data_type",
        "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
    },
    "geoShape": {
    "point": {
        "position": {
            "latitudeDegrees": 50.91402185768586,
            "longitudeDegrees": 0.79203612077257,
            "altitudeHaeMeters": 46.214997987295234,
            "altitudeAglMeters": 0.5000067609670396
        }
    }
    },
    "geoDetails": {
        "type": "GEO_TYPE_GENERAL"
    },
    "aliases": {
        "name": "Point"
    },
    "ontology": {
        "template": "TEMPLATE_GEO"
    }
}
```

#### Polygon

**`geo.json`**

```json title="geo.json" maxLines=25
{
    "entityId": "UNIQUE_ENTITY_ID",
    "description": "Polygon 1",
    "isLive": true,
    "createdTime": "2024-12-07T00:55:43.183738Z",
    "expiryTime": "2024-12-07T01:00:43.183743Z",
    "aliases": {
        "name": "Polygon"
    },
    "ontology": {
        "template": "TEMPLATE_GEO"
    },
    "provenance": {
        "integrationName": "your_integration_name",
        "dataType": "your_data_type",
        "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
    },
    "geoDetails": {
        "type": "GEO_TYPE_GENERAL"
    },
    "geoShape": {
        "polygon": {
            "rings": [
                {
                    "positions": [
                        {
                            "position": {
                            "latitudeDegrees": 49.01611140463143,
                            "longitudeDegrees": 1.5746513124955297
                            }
                        },
                        {
                            "position": {
                            "latitudeDegrees": 49.01924140463143,
                            "longitudeDegrees": 2.882469645828863
                            }
                        },
                        {
                            "position": {
                            "latitudeDegrees": 48.4172380712981,
                            "longitudeDegrees": 2.9189863124955298
                            }
                        },
                        {
                            "position": {
                            "latitudeDegrees": 49.01611140463143,
                            "longitudeDegrees": 1.5746513124955297
                            }
                        }
                    ]
                }
            ]
        }
    }
}
```

#### Ellipse

**`geo.json`**

```json title="geo.json" maxLines=25
{
    "entityId": "UNIQUE_ENTITY_ID",
    "description": "Geo ellipse",
    "isLive": true,
    "createdTime": "2024-12-07T01:06:32.834952Z",
    "expiryTime": "2024-12-07T01:11:32.834954Z",
    "aliases": {
        "name": "Ellipse"
    },
    "ontology": {
        "template": "TEMPLATE_GEO"
    },
    "provenance": {
        "integrationName": "your_integration_name",
        "dataType": "your_data_type",
        "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
    },
    "geoDetails": {
        "type": "GEO_TYPE_CONTROL_AREA"
    },
    "geoShape": {
        "ellipse": {
            "semiMajorAxisM": 20,
            "semiMinorAxisM": 20,
            "orientationD": 40
        }
    },
    "location": {
        "position": {
            "latitudeDegrees": 51.46,
            "longitudeDegrees": -0.16
        }
    }
}
```

#### Line

**`geo.json`**

```json title="geo.json" maxLines=25
{
    "entityId": "UNIQUE_ENTITY_ID",
    "description": "Geo line",
    "isLive": true,
    "createdTime": "2024-12-07T01:08:39.079826Z",
    "expiryTime": "2024-12-07T01:13:39.079828Z",
    "provenance": {
        "integrationName": "your_integration_name",
        "dataType": "your_data_type",
        "sourceUpdateTime": "2025-04-07T00:19:47.706196Z"
    },
    "geoShape": {
        "line": {
            "positions": [
            {
                "latitudeDegrees": 47.605,
                "longitudeDegrees": -122.329
            },
            {
                "latitudeDegrees": 47.61,
                "longitudeDegrees": -122.33
            }
            ]
        }
    },
    "geoDetails": {
        "type": "GEO_TYPE_GENERAL"
    },
    "aliases": {
        "name": "Line"
    },
    "ontology": {
        "template": "TEMPLATE_GEO"
    }
}
```

## 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:

#### Create

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

#### 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.

#### Delete

An entity is deleted when its `expiry_time` has lapsed, or an
update is sent with the `is_live` component set to `false`.
Alternatively, you can use the `noExpiry` flag to create entities that
persist indefinitely. Use `noExpiry` only when the entity contains
information that should be available to other tasks or integrations beyond
its immediate operational context, such as long-living geographical entities.

> **Persistence**
>
> \
>
>
> * If both `noExpiry` and `expiryTime` are set, Lattice ignores
>   `expiryTime`.
>
> * If a service restart occurs and an entity hasn't been
>   republished within the previous 5 minutes, the entity will not be restored, regardless of the
>   `noExpiry` setting.

You should handle a delete event by removing all references to it in
memory or discarding it from your user interface.

## What's next?

* Learn more about the Entities API in [REST](/reference/rest/entities/publish-entity) and [gRPC](/reference/grpc/anduril-entitymanager-v-1/entity-manager-api/anduril-entitymanager-v-1-publish-entity).
* Learn how to [publish entities to Lattice](/guides/entities/publish).
* Check out the Lattice [sample apps](/samples/overview).

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