[ADP-604] CloudEvents source

Summary

This document provides guidance on how to properly use the source field in CloudEvents.

Context

The source field in CloudEvents identifies the context in which an event occurred. It's crucial for uniquely identifying events and their origins.

Decision

We will adopt the following guidelines for the source field:

1. MUST follow the CloudEvents spec convention: source + id must be unique.
2. SHOULD use UUID, URI, URL, or URN for the source field and maintain consistency within the same application/product.
3. SHOULD follow this preference order: absolute URI > URI reference > URN > UUID.

Details

Format Preferences

1. Absolute URI (Most Preferred) Use when the event source has a regular API endpoint.

   {
     "specversion": "1.0",
     "source": "https://api.the-app.com/users/{uuid}"
   }

2. Relative URI Use when the event source is not exposed at a specific API endpoint.

   {
     "specversion": "1.0",
     "source": "//vortexcloud.com/applications/{application-id}"
   }

   or

   {
     "specversion": "1.0",
     "source": "/users/{uuid}"
   }

3. URN Provides a programmatic way to identify resources by category. See URN naming convention principle.

4. UUID (Least Preferred)

Special Cases

• For events about collections (resources), the source MAY be the collection itself. Example (for created / deleted events):

  {
    "specversion": "1.0",
    "type": "com.example.event",
    "source": "/users",
    "id": "A234-1234-1234",
    "time": "2024-07-10T08:42:00Z",
    "datacontenttype": "application/json",
    "data": {
      "message": "New user collection created"
    }
  }

• For events about single resources, the source MAY be the unique resource. Example (for updated events):

  {
    "specversion": "1.0",
    "type": "com.example.event",
    "source": "/users/123",
    "id": "A234-1234-1234",
    "time": "2024-07-10T08:42:00Z",
    "datacontenttype": "application/json",
    "data": {
      "message": "User profile updated"
    }
  }

Consequences

• Improved consistency in source field usage across the system.
• Better event traceability and origin identification.
• Potential need to update existing event producers to comply with these guidelines.

References

• CloudEvents Specification

  from https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#source-1

  source

  • Type: URI-reference

  • Description: Identifies the context in which an event happened. Often this will include information such as the type of the event source, the organization publishing the event or the process that produced the event. The exact syntax and semantics behind the data encoded in the URI is defined by the event producer.

    Producers MUST ensure that source + id is unique for each distinct event.

    An application MAY assign a unique source to each distinct producer, which makes it easy to produce unique IDs since no other producer will have the same source. The application MAY use UUIDs, URNs, DNS authorities or an application-specific scheme to create unique source identifiers.

    A source MAY include more than one producer. In that case the producers MUST collaborate to ensure that source + id is unique for each distinct event.

  • Constraints:

    • REQUIRED
    • MUST be a non-empty URI-reference
    • An absolute URI is RECOMMENDED

  • Examples

    • Internet-wide unique URI with a DNS authority.
      • https://github.com/cloudevents
      • mailto:cncf-wg-serverless@lists.cncf.io
    • Universally-unique URN with a UUID:
      • urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66
    • Application-specific identifiers
      • /cloudevents/spec/pull/123
      • /sensors/tn-1234567/alerts
      • 1-555-123-4567