Skip to content

The event model

An Event is CloudEvents' attribute set: eight attributes, any number of extensions, and a payload the module never looks inside. It is a plain struct.

const SpecVersion = "1.0"

type Event struct {
    ID              string
    Source          string
    SpecVersion     string
    Type            string
    DataContentType string
    DataSchema      string
    Subject         string
    Time            time.Time
    Extensions      map[string]string
    Data            []byte
}

Fields

Field Required Meaning
ID yes With Source, uniquely identifies the event. A producer must not reuse a pair for two different events.
Source yes The context the event happened in. A URI-reference, so it may be relative.
SpecVersion yes The CloudEvents version. A format fills it in when it is empty; Validate refuses any value but SpecVersion ("1.0").
Type yes The kind of occurrence, and what consumers usually filter on.
DataContentType no The media type of Data.
DataSchema no The schema Data conforms to. Must be an absolute URI.
Subject no The thing the event is about, within Source.
Time no When the occurrence happened. The zero value means absent.
Extensions no Attributes outside the specification's set, keyed by name.
Data no The payload, carried as the message body and never interpreted.

Every extension must be safe to log: opaque identifiers only, never a display name or anything a person chose. Attributes ride in headers, headers are logged by default, and nothing routes them through a redaction pass the way a payload field is routed.

What Validate checks

Validate(e Event) error is the one description of a well-formed event. Every format runs it on Encode and on Decode, so every format refuses the same events. It does not fill in an empty SpecVersion. It checks, in this order:

Rule Refusal
id, source, specversion and type are non-empty, checked in that order ErrMissingAttribute
specversion is 1.0 ErrUnsupportedSpecVersion
id, source, type, subject, dataschema, datacontenttype and every extension value hold no control character (U+0000 to U+001F, U+007F to U+009F) ErrControlCharacter
the same values are valid UTF-8 ErrInvalidEncoding
dataschema, when present, is an absolute URI ErrDataSchemaNotAbsolute
each extension name is one or more lower-case ASCII letters or digits, and not data ErrInvalidExtensionName
no extension is named after one of the eight attributes ErrReservedExtensionName
no extension has an empty value ErrMissingAttribute

Validate does not check Time: a time.Time is already a time. ErrInvalidTime is returned by a format that reads a timestamp it cannot parse.

ValidExtensionName

func ValidExtensionName(name string) bool

Reports whether a name may be an extension: one or more lower-case ASCII letters or digits, not data, and not one of the eight attribute names (id, source, specversion, type, datacontenttype, dataschema, subject, time). It enforces the specification's MUSTs and not its SHOULDs, so starting with a letter and staying under twenty characters are not required.

The character set is this narrow because some protocols treat metadata as case-sensitive and others do not, and one event may cross several of them.