# Unified Namespace

> How Proxus builds the Unified Namespace from the place of each device, the MQTT topics it publishes, and what the messages contain.

Source: https://proxus.io/docs/concepts/unified-namespace

A **Unified Namespace** (UNS) is one shared, structured place where every current value of the plant can be
found by its location: this enterprise, this site, this area, this machine, this value. Any system that needs
plant data subscribes to the namespace, instead of connecting to each machine or to each other.

Proxus builds the namespace for you. Every device you add is published in it, under the place you gave it, and
every tag value appears there as it is read.

## The place of a device

The levels of the namespace follow ISA-95, the international standard for the structure of a manufacturing
enterprise. You set them on each device, in the device setup wizard or on the device page:

| Level | Example | What it usually is |
| --- | --- | --- |
| **Enterprise** | `Meridian` | The company. |
| **Site** | `Lyon Foods Plant` | One plant or location. |
| **Area** | `Processing` | A department or hall in the plant. |
| **Process cell** | `Dough` | A line or a group of machines that work together. |
| **Equipment module** | `Kneading` | A part of a machine, when one device stands for part of a larger unit. |

All levels are optional. A level you leave empty is skipped, so a device with only a site is published directly
under that site. The place also groups devices in lists, the Trend Workspace and the Operations Center, so it is
worth agreeing on names before you add many devices.

## Topics

Proxus publishes the namespace over MQTT. Each value has its own topic, built from the place, the device name
and the tag name:

```text
v1/<enterprise>/<site>/<area>/<process cell>/<equipment module>/<device>/telemetry/<tag>
```

For the mixer from [Connect your first machine](https://proxus.io/docs/get-started/first-machine):

```text
v1/Meridian/Lyon_Foods_Plant/Processing/Dough/DOCS_TUTORIAL_MIXER_01/telemetry/Temperature
```

- `v1` is the version of the topic structure.
- Empty levels are left out; there is no empty segment.
- In each level, any character other than a letter, a digit, `_` or `-` becomes `_`. A space in
  `Lyon Foods Plant` becomes `Lyon_Foods_Plant`. Upper and lower case are kept.

Besides one topic per tag, each device has three more:

| Topic | Content | Sent |
| --- | --- | --- |
| `.../<device>/telemetry/<tag>` | One value of one tag. | Every time the tag is read. |
| `.../<device>/telemetry/_summary` | The latest value of every tag of the device in one message, with the device's place. | At most every 5 seconds by default. |
| `.../<device>/state/_lastSeen` | When the device last sent a value. | At most every 5 seconds by default; kept by the broker for new subscribers. |
| `.../<device>/state/_status` | Whether the device is online. | When the status changes; kept by the broker for new subscribers. |

A new subscriber therefore sees the status and the last-seen time of every device at once, and the values as
they come in.

## Messages

Messages are JSON by default. A value message looks like this:

```json
{
  "ts": "2026-10-15T19:12:35.120Z",
  "value": 62.5,
  "dataType": "Float",
  "unit": "°C",
  "quality": "Good",
  "source": "Proxus"
}
```

| Field | Meaning |
| --- | --- |
| `ts` | When the value was read, in UTC. |
| `value` | The value, as a JSON number, true or false, or text. |
| `dataType` | The type of the value (`Bool`, `Int`, `Float`, `Double`, `String`...). It is worked out from the value itself, so it can differ from the tag's type: a `Float` tag that reads `62` is published as `Int`. |
| `unit` | The tag's unit. Left out when the tag has none. |
| `quality` | In this version always `Good`. The real quality of each value is on the device page and in the historian. |
| `source` | Always `Proxus`. |

Proxus can publish the namespace as **Sparkplug B** instead of JSON, for systems built on that standard. The
format, the summary interval and the other publishing settings are in the `[UNS]` section of the configuration
file; see [Configuration keys](https://proxus.io/docs/reference/configuration).

## Where the namespace is published

Each edge gateway publishes the values it reads on its own built-in MQTT broker. For the **SYSTEM** gateway in
the Docker Compose stack, that broker listens on port `1883` of the hub host. A remote gateway has its own
broker, on the port chosen when it was installed.

Subscribers need credentials; the broker does not accept anonymous clients by default.
[MQTT and the UNS topics](https://proxus.io/docs/develop/mqtt) shows how to connect and subscribe.

In the hub, **Organize > UNS Explorer** shows the whole namespace as a live tree, with the values of every
gateway together.

## What's next

- [UNS Explorer](https://proxus.io/docs/organize/uns-explorer) to browse the namespace in the hub.
- [UNS permissions](https://proxus.io/docs/administer/uns-permissions) to decide who may see which part of it.
- [Devices, profiles and tags](https://proxus.io/docs/concepts/devices-profiles-tags) for the objects behind each topic.