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¶
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.