From c9527480de7ac52c5afde2a27146ad984102d4bd Mon Sep 17 00:00:00 2001 From: Thomas Bouldin Date: Mon, 26 Mar 2018 18:29:35 -0700 Subject: [PATCH 1/3] Propose holistic simplification of source- attributes * Drops source-type; there is no clear use according to the usage scenarios. * Consolidates namespace and the source-authority * Clarifies that source-path should not be redundant with source-authority/namespace * Adds namespacing to event-type * Drops documentation for "source" that was redundant with each of its subfields. Opts for a name prefix instead. Signed-off-by: Thomas Bouldin --- spec.md | 72 +++++++++++++++++++++++++++++++-------------------------- 1 file changed, 39 insertions(+), 33 deletions(-) diff --git a/spec.md b/spec.md index 9e9981d86..5c86429b7 100644 --- a/spec.md +++ b/spec.md @@ -107,27 +107,19 @@ the event data. The context might also need to be serialized with the event data for some use cases (e.g. a JSON implementation might use one JSON object that contains both context and data). -### namespace -* Type: String -* Description: Identifier that uniquely identifies the organization publishing - the event. -* Constraints: - * REQUIRED - * MUST be a non-empty string -* Examples: - * kafka.apache.org - * com.microsoft.azure - ### event-type * Type: String -* Description: Type of the event `data`. Producers can specify the format of - this, depending on their service. This enables the interpretation of `data`, - and can be used for routing, policy and more. +* Description: Type of occurrence which has happened. The event type MUST be + namespaced with a package based on the reverse-DNS of a domain associated + with the software that produced the event. This MAY be used for routing, + observability, policy enforcement, etc. * Constraints: * REQUIRED * MUST be a non-empty string + * MUST be prefixed with a reverse-DNS name associated with the software that + produces the event * Examples: - * customer.created + * com.github.pull.create ### event-type-version * Type: String @@ -146,32 +138,46 @@ that contains both context and data). * REQUIRED * MUST be a non-empty string -### source -* Type: Object -* Description: This describes the software instance that emits the event at - runtime (i.e. the producer). It contains sub-properties (listed below) -* Constraints: - * REQUIRED - * MUST contain at least one non-empty sub-property. - -### source-type +### source-authority * Type: String -* Description: Type of the event source. Providers define list of event - sources. +* Description: The URI authority component of the source software. * Constraints: * REQUIRED * MUST be a non-empty string + * MUST conform to the + ["authority" component](https://tools.ietf.org/html/rfc3986#section-3.2) + of the URI spec * Examples: - * s3 + * github.com + * myenterpriseGitHubInstall.company.com -### source-id -* Type: String -* Description: ID of the event source. +### source-path +* Type: string +* Description: The URI path component of the resource that emitted an event. * Constraints: - * REQUIRED - * MUST be a non-empty string + * OPTIONAL + * If present, MUST conform to the "path-rootless" grammar of the + [URI spec](https://tools.ietf.org/html/rfc3986#section-3.3) * Examples: - * my.s3.bucket + * myorg/myrepo + * my/long/ftp/path.jpg + +### source-attributes +* Type: Map +* Description: Attributes associated with the resource that emitted the event. + This allows filtering or routing based on non-hierarchical source metadata. + This is intended to include (but is not limited to) "labels" in cloud + platforms like AWS or Kubernetes. +* Constraints: + * OPTIONAL + * Keys MUST match the regular expression `[_.a-z0-9]+` + * Keys SHOULD use the character "." is as namespace separator + * Values MUST use URI-safe characters +* Examples: + * { + "sensor.configuration": "WINDOW" + "sensor.location": "deployments/house1/window3" + } ### event-id * Type: String From 87e270b44c00f01b318593b41133a4c08dc898c3 Mon Sep 17 00:00:00 2001 From: Thomas Bouldin Date: Wed, 28 Mar 2018 15:39:23 -0700 Subject: [PATCH 2/3] Rename 'attributes' to 'labels' Signed-off-by: Thomas Bouldin --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 5c86429b7..0ff723e02 100644 --- a/spec.md +++ b/spec.md @@ -162,9 +162,9 @@ that contains both context and data). * myorg/myrepo * my/long/ftp/path.jpg -### source-attributes +### source-labels * Type: Map -* Description: Attributes associated with the resource that emitted the event. +* Description: Labels associated with the resource that emitted the event. This allows filtering or routing based on non-hierarchical source metadata. This is intended to include (but is not limited to) "labels" in cloud platforms like AWS or Kubernetes. From 35b46fa5bc68353242a17c5cbeba970453c461ef Mon Sep 17 00:00:00 2001 From: Thomas Bouldin Date: Thu, 29 Mar 2018 08:57:02 -0700 Subject: [PATCH 3/3] Fix poor grammar Signed-off-by: Thomas Bouldin --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 0ff723e02..04e537d64 100644 --- a/spec.md +++ b/spec.md @@ -171,7 +171,7 @@ that contains both context and data). * Constraints: * OPTIONAL * Keys MUST match the regular expression `[_.a-z0-9]+` - * Keys SHOULD use the character "." is as namespace separator + * Keys SHOULD use the character "." as a namespace separator * Values MUST use URI-safe characters * Examples: * {