---
sidebar:
  hidden: true
title: roboto.domain.platform_events.catalog
---
## Module Contents

### DATASET_ROOT

```python
roboto.domain.platform_events.catalog.DATASET_ROOT = 'dataset'
```

`from roboto.domain.platform_events import DATASET_ROOT`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L62-L62)

Namespace root naming a dataset. An event exposing it is about a dataset or about something within one, so a consumer may reach that dataset's files from the event.

### DEFAULT_PLATFORM_EVENT_CATALOG

```python
roboto.domain.platform_events.catalog.DEFAULT_PLATFORM_EVENT_CATALOG
```

`from roboto.domain.platform_events import DEFAULT_PLATFORM_EVENT_CATALOG`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L288-L430)

The catalog of every [`PlatformEventType`](/reference/python-sdk/roboto/domain/platform_events/events#roboto.domain.platform_events.events.PlatformEventType), used wherever a caller does not supply its own (envelope payload binding, trigger validation, evaluation).

### ENVELOPE_ROOT

```python
roboto.domain.platform_events.catalog.ENVELOPE_ROOT = 'envelope'
```

`from roboto.domain.platform_events import ENVELOPE_ROOT`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L49-L49)

Namespace root served from the platform event's own envelope: its id, source, subject, type, time, and org, plus the payload as published under `data`. Reserved: no event type may expose it as an entity root.

### OncePerProjection

```python
roboto.domain.platform_events.catalog.OncePerProjection
```

`from roboto.domain.platform_events import OncePerProjection`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L36-L36)

Projects a [`PlatformEvent`](/reference/python-sdk/roboto/domain/platform_events/events#roboto.domain.platform_events.events.PlatformEvent) onto the token string that identifies what the trigger fires once per (e.g. the dataset id for `once_per=dataset`).

A projection reads the event payload and nothing else: one event in, one string out, with no lookup against platform state. A `once_per` value can only name what the event itself already identifies, so there is no "once per file in the dataset this event is about". `once_per` only collapses repeats; it never fans one event out into several runs, and a trigger dispatches each of its targets at most once per event.

### PlatformEventCatalog

```python
class roboto.domain.platform_events.catalog.PlatformEventCatalog(
    descriptors: collections.abc.Iterable[PlatformEventDescriptor],
)
```

`from roboto.domain.platform_events import PlatformEventCatalog`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L227-L285)

Descriptors for platform event types, looked up by type.

Everything that varies by event type — payload model, exposed roots, default root, dedup projections — hangs off the [`PlatformEventDescriptor`](/reference/python-sdk/roboto/domain/platform_events/catalog#roboto.domain.platform_events.catalog.PlatformEventDescriptor) objects registered here. [`DEFAULT_PLATFORM_EVENT_CATALOG`](/reference/python-sdk/roboto/domain/platform_events/catalog#roboto.domain.platform_events.catalog.DEFAULT_PLATFORM_EVENT_CATALOG) registers every member of [`PlatformEventType`](/reference/python-sdk/roboto/domain/platform_events/events#roboto.domain.platform_events.events.PlatformEventType); a caller may build a catalog over a subset.

**Parameters**

- **descriptors** (`collections.abc.Iterable[PlatformEventDescriptor]`)

#### PlatformEventCatalog.descriptor()

```python
def descriptor(
    event_type: roboto.domain.platform_events.events.PlatformEventType,
) -> PlatformEventDescriptor
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L257-L266)

Return the descriptor for `event_type`.

**Parameters**

- **event_type** (`roboto.domain.platform_events.events.PlatformEventType`)

**Raises**

- `ValueError`: No descriptor is registered for `event_type`.

**Returns**

- `PlatformEventDescriptor`

#### PlatformEventCatalog.exposed_roots()

```python
def exposed_roots(
    event_type: roboto.domain.platform_events.events.PlatformEventType,
) -> frozenset[str]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L268-L274)

Return the namespace roots `event_type` exposes.

**Parameters**

- **event_type** (`roboto.domain.platform_events.events.PlatformEventType`)

**Raises**

- `ValueError`: No descriptor is registered for `event_type`.

**Returns**

- `frozenset[str]`

#### PlatformEventCatalog.namespace_roots()

```python
def namespace_roots() -> frozenset[str]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L280-L285)

Return the union of every registered event type's exposed roots.

**Returns**

- `frozenset[str]`

#### PlatformEventCatalog.subscribable_types()

```python
def subscribable_types() -> frozenset[roboto.domain.platform_events.events.PlatformEventType]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L276-L278)

Return the event types a trigger may subscribe to.

**Returns**

- `frozenset[roboto.domain.platform_events.events.PlatformEventType]`

### PlatformEventDescriptor

```python
class roboto.domain.platform_events.catalog.PlatformEventDescriptor
```

`from roboto.domain.platform_events import PlatformEventDescriptor`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L113-L224)

Everything the trigger system knows about one platform event type.

Immutable. Carries the payload model the envelope validates against, the namespace roots the event exposes to conditions and target templates, the default root unqualified condition fields bind to, the entity the event is about, and the [`OncePer`](/reference/python-sdk/roboto/domain/platform_events/once_per#roboto.domain.platform_events.once_per.OncePer) values the event supports (as projections from an event to its dedup token value).

Every `once_per` value is declared as an [`OncePerProjection`](/reference/python-sdk/roboto/domain/platform_events/catalog#roboto.domain.platform_events.catalog.OncePerProjection), a pure function of the event payload, so a descriptor can only offer what the payload itself names. No descriptor can resolve one event into several subjects, which is what holds dispatch at one per target per event.

**Attributes**

- **PlatformEventDescriptor.default_root** (`str`): Root that unqualified condition fields bind to. Always one of [`exposed_roots`](/reference/python-sdk/roboto/domain/platform_events/catalog#roboto.domain.platform_events.catalog.PlatformEventDescriptor.exposed_roots).
- **PlatformEventDescriptor.event_type** (`roboto.domain.platform_events.events.PlatformEventType`): The event type this descriptor describes.
- **PlatformEventDescriptor.exposed_roots** (`frozenset[str]`): Namespace roots (`dataset`, `file`, `changed`, ...) this event exposes.
- **PlatformEventDescriptor.once_per_projections** (`collections.abc.Mapping[roboto.domain.platform_events.once_per.OncePer, OncePerProjection]`): Supported `once_per` values, each mapped to the projection that yields its token. Key presence defines legality; every event supports [`OncePer.Occurrence`](/reference/python-sdk/roboto/domain/platform_events/once_per#roboto.domain.platform_events.once_per.OncePer.Occurrence).
- **PlatformEventDescriptor.payload_model** (`type[pydantic.BaseModel]`): Model of [`PlatformEvent.data`](/reference/python-sdk/roboto/domain/platform_events/events#roboto.domain.platform_events.events.PlatformEvent.data) for this event type.
- **PlatformEventDescriptor.subject_type** (`roboto.uri.RobotoUriType`): The kind of entity this event is about — its CloudEvents `subject`. The payload carries that entity's id under `{subject_type}_id`, and may say more about it, such as the version a file was at. The rest is context around the entity: the upload transaction a file arrived in, or the applied changeset.
- **PlatformEventDescriptor.subscribable** (`bool`) = `True`: Whether a trigger may name this type in an [`EventSubscription`](/reference/python-sdk/roboto/domain/triggers/sources#roboto.domain.triggers.sources.EventSubscription). `False` for occurrences delivered to a single trigger rather than broadcast to subscribers — the schedule tick — which still carry a descriptor so their tokens and namespaces are built the same way.

**Properties**

- **PlatformEventDescriptor.supported_once_per** (`frozenset[roboto.domain.platform_events.once_per.OncePer]`): The [`OncePer`](/reference/python-sdk/roboto/domain/platform_events/once_per#roboto.domain.platform_events.once_per.OncePer) values this event type supports.

#### PlatformEventDescriptor.idempotency_token()

```python
def idempotency_token(
    event: roboto.domain.platform_events.events.PlatformEvent,
    once_per: roboto.domain.platform_events.once_per.OncePer,
) -> str
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L198-L224)

Return the dedup token for `event` at `once_per`.

Two events that project onto the same token dispatch the same target of the same trigger at most once.

**Parameters**

- **event** (`roboto.domain.platform_events.events.PlatformEvent`): The event to project. Must be of this descriptor's type.
- **once_per** (`roboto.domain.platform_events.once_per.OncePer`): What the trigger fires once per.

**Raises**

- `ValueError`: `event` is of a different type, or `once_per` is not supported by this event type.

**Returns**

- `str`

#### PlatformEventDescriptor.subject()

```python
def subject(
    event: roboto.domain.platform_events.events.PlatformEvent,
) -> roboto.uri.RobotoUri
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L185-L196)

Return the `roboto://` URI of the entity `event` is about.

**Parameters**

- **event** (`roboto.domain.platform_events.events.PlatformEvent`)

**Raises**

- `ValueError`: `event` is not of this descriptor's event type.

**Returns**

- `roboto.uri.RobotoUri`

#### PlatformEventDescriptor.supports_once_per()

```python
def supports_once_per(once_per: roboto.domain.platform_events.once_per.OncePer) -> bool
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L181-L183)

Return whether `once_per` is legal for this event type.

**Parameters**

- **once_per** (`roboto.domain.platform_events.once_per.OncePer`)

**Returns**

- `bool`

### RESERVED_ROOTS

```python
roboto.domain.platform_events.catalog.RESERVED_ROOTS
```

`from roboto.domain.platform_events import RESERVED_ROOTS`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L58-L58)

Roots the evaluation namespace serves itself. A descriptor claiming one would be silently shadowed by the envelope or the trigger, so construction rejects it.

### TRIGGER_ROOT

```python
roboto.domain.platform_events.catalog.TRIGGER_ROOT = 'trigger'
```

`from roboto.domain.platform_events import TRIGGER_ROOT`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L54-L54)

Namespace root describing the trigger being evaluated. Reserved for the consumer; no event type may expose it as an entity root.

### event_catalog_manifest()

```python
def roboto.domain.platform_events.catalog.event_catalog_manifest(
    catalog: PlatformEventCatalog = DEFAULT_PLATFORM_EVENT_CATALOG,
) -> dict[str, Any]
```

`from roboto.domain.platform_events import event_catalog_manifest`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/platform_events/catalog.py#L435-L451)

The catalog as the web UI's TypeScript mirror reads it: per event type, its roots, default root, supported grains, subject type, and whether a trigger may subscribe.

`event_catalog.json` in this package is this function's output, written by `scripts/gen_trigger_manifests.py` and drift-checked by a test on each side.

**Parameters**

- **catalog** (`PlatformEventCatalog`)

**Returns**

- `dict[str, Any]`