Field Guide

Entity URNs specify a unique entity in a data system.

Entity URNs are composed of a urn: prefix followed by at least three colon-separated parts, following the format: urn:namespace:type:ID

• namespace is the namespace of the event for the entity. It’s also referred to as system ID.
• type is the type of the entity. It is always the next-to-last colon-separated part of the URN.
• ID is the unique identifier of the entity. It is always the last colon-separated part of the URN.

The namespace is also referred to as the Namespace Identifier (or NID). The namespace must start and end with an alphanumeric character. namespace length must be between 2 and 32 characters. namespace may contain alphanumeric, “-”, and “.” characters. All other characters are disallowed.

The remainder of the URN after the namespace is considered the Namespace Specific String (NSS) and contains the type and ID fields. The NSS complies with URN RFC 8141, except that it must contain at least two colon-separated fields, “?” characters are allowed, and R, Q, and F-components are stripped and ignored.

Example Entity URN for Asset Graph: urn:autodesk.data.assetgraph:asset:8LpSOiCoSlqMwcY07ggQRQ_aga

Event Type IDs specify a unique event type in a given namespace, or system.

Event type ID for subscription. Event type IDs follow a type ID format which is composed of three sections following the format: namespace:eventType-semverVersion

• namespace is the namespace of the event. It’s also referred to as system ID in the event definitions API.
• eventType is the type of the event.
• semverVersion is the version of the event, in semver format. See https://semver.org/ for more details.

The namespace field must start and end with an alphanumeric character. namespace length must be between 2 and 32 characters. namespace may contain alphanumeric, “-”, and “.” characters. All other characters are disallowed. The eventType field must be composed of alphanumeric characters with the “.” character also allowed, except at the end. eventType can also contain the wildcard character “*”. The semver field must follow semver format. See https://semver.org/ for more details.

Example Event Type ID for Asset Graph: autodesk.data.assetgraph:events.asset.updated-1.0.0

When creating a subscription, it is possible to specify a event type ID containing a wildcard pattern using the asterisk character in the eventType field only. When using wildcards, the system will attempt to match other event types and use the asterisk as a placeholder for zero or more characters to other events in the namespace. For example, a eventType of asset.* would match the asset.created, asset.updated, asset.deleted, etc. event types.

It might be tempting to specify all the events in a namespace using a eventType field value containing only the asterisk character. However, note that this can result in a very large number of incoming events, depending on the entityUrn field you specified. Also note that wildcards are not supported in the entityUrn parameters.

Data events are targeted to provide updates on specific range of data within a particular event namespace, like Asset Graph. For example, you could subscribe to the “space created” event for a collection. In Data Events Service terminology, the collection is referred as the scope of the subscription. The scope is specified as the entityUrn when the subscription is created.

The event type defines the type of event that will be received for a subscription, and is specified as the eventType when the subscription is created. Only events of that type will be received for that subscription.

Scopes are recursive in nature and define the hierarchy of entities within the system. In Asset Graph, collections contain spaces, and spaces contain assets. Therefore, if you choose your scope to be a collection, then you could receive a particular event type for all spaces and assets within the collection.

For example, if you subscribe to a collection as the entityUrn, and choose autodesk.data.assetgraph:events.asset.created-1.0.0 as the eventType, then your subscription will receive the “asset created” event whenever any new asset is created under that collection. However, this subscription would not receive any other kind of event (see below).

In other systems, like a file system, similar hierarchies can exist, for example a root folder could contain sub-folders. Those folders can contain files.

Important Notes:

• A subscription can only receive one type of event, specified by the eventType and will not receive any other event types. For example, if you subscribe to “space created”, then other events such as “space updated” or “space deleted” would not be received. One subscription would need to be created for each desired event type, or a wildcard event type would need to be used (see section above).
• “Updated” events, like the “collection updated” event, are only fired when the collection itself is updated, and does not fire for other event types that occur on other entities within the collection. For example, when spaces or assets are added, removed, or deleted, the “collection updated” event will not be sent.