RaBe Events Spec

Specfication for RaBe CloudEvents. Defines URI, URI-reference types and the required type attribute of the CloudEvents spec. It uses pseudo-DNS namespacing with the events.api.rabe.ch domain to achieve most of it's goals.

Table of Contents

• Overview
• Notations and Terminology
• Versioning
• Type System
• REQUIRED Attributes
• Example

Overview

Events occur all over the place and all the time, having a common understanding of how to communicate events allows us to capture them in a meaningful way ensuring they can be leveraged in protocol and implementation agnostic scenarios by a range of consumers and producers across the diverse landscape of the RaBe IT stack.

This specification is heavily inspired by the work done by the maintainers of the CloudEvents v1.0.1 Spec.

Notations and Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

This document SHALL adhere to the Notational Conventions and Terminology described in the the CloudEvents v1.0.1 Spec.

Versioning

This specification is versioned using git tag. It uses go-semantic-release for tagging new versions following the Conventional Commits v1.0.0 specification.

Type System

This specification defines types from the CloudEvents Type System.

• URI - Absolute uniform resource identifier.
  • String encoding: Absolute URI as defined in RFC 3986 Section 4.3.
• URI-reference - Uniform resource identifier reference.
  • String encoding: URI-reference as defined in RFC 3986 Section 4.1.

REQUIRED Attributes

The following attributes MUST follow these constaints in addition to the CloudEvents REQUIRED Attributes.

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.

  An application SHOULD use the RECOMMENDED unique, internet-wide, absolute URI format.

  It is RECOMMENDED to use the GitHub page of the project as source.

  A source MAY assign a unique source to each distinct by appending a fragment to the URI. It is RECOMMENDED that the unique part is based on a UUID to aid with tracing efforts or similar requirements.

  An application MAY use UUID, URN or application-specific schemes to create unique source identifiers but this is NOT RECOMMENDED.

• Constraints:

  • SHOULD be a based on the event producers project page.

• Examples

  • https://github.com/radiorabe/rabemimimi
  • https://github.com/LibreTime/libretime#<event-id-for-tracing>
  • https://github.com/radiorabe/raar_show_descriptor

type

• Type: String

• Description: This attribute contains a value describing the type of event related to the originating occurrence. Often this attribute is used for routing, observability, policy enforcement, etc. The format of this is producer defined and might include information such as the version of the type - see Versioning of CloudEvents in the Primer for more information.

  The RaBe DNS authority events.api.rabe.ch SHALL be used for reverse-DNS naming purposes.

  The event producer MUST include a unique identifier. It is RECOMMENDED that the GitHub repo name of the producer is used in the source attribute. Systems MAY also use their internal project name for this purpose.

  An event producer MAY use a subdomain indicate which component an event originated from. Types SHOULD contain versioning information.

• Constraints:

  • SHOULD be prefixed with a reverse-DNS name.
  • if used, the reverse-DNS name SHALL be ch.rabe.api.events

• Examples

  • Such event, much type, very version:
    • ch.rabe.api.events.rabemimimi.v1alpha.mimimi.created
    • ch.rabe.api.events.rabemimimi.v1alpha.mimimi.updated
  • Simple unversioned events:
    • ch.rabe.api.libretime.onair

Example

The following example shows a paired down RaBe CloudEvent serialized as JSON:

{
    "type" : "ch.rabe.api.events.events-spec.v1.such.event",
    "source" : "https://github.com/radiorabe/events-spec",
}

License

This specification is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Copyright

Copyright (c) 2021 Radio Bern RaBe