From 4661a69744e02430f642d167558e588c7b80f3ae Mon Sep 17 00:00:00 2001 From: Lance Ball Date: Thu, 3 Dec 2020 17:41:02 -0500 Subject: [PATCH] docs: typos and wordsmithing for 1.0.1 (#733) * docs: typos and wordsmithing for 1.1 This commit addresses a few typos and does a little wordsmithing on some of the docs and specs meant to land in the 1.1 release. In the proprietary-specs.md document, I used MUST in a couple of places. Not sure if this is appropriate for that doc. Signed-off-by: Lance Ball * fixup: incorporate PR feedback Signed-off-by: Lance Ball * fixup: incorporate PR feedback Signed-off-by: Lance Ball --- extensions/distributed-tracing.md | 11 ++++++----- http-protocol-binding.md | 18 +++++++++--------- kafka-protocol-binding.md | 20 +++++++++----------- mqtt-protocol-binding.md | 18 +++++++++--------- proprietary-specs.md | 4 ++-- protobuf-format.md | 5 +++-- websockets-protocol-binding.md | 10 +++++----- 7 files changed, 43 insertions(+), 43 deletions(-) diff --git a/extensions/distributed-tracing.md b/extensions/distributed-tracing.md index cab7519f3..0292a545b 100644 --- a/extensions/distributed-tracing.md +++ b/extensions/distributed-tracing.md @@ -2,9 +2,10 @@ This extension embeds context from [Distributed Tracing](https://w3c.github.io/trace-context/) so that distributed -systems can include traces that span an event-driven system. This extensions is meant -to contain historical data of the parent trace, in order to diagnose eventual failures of the -systems through tracing platforms like Jaeger, Zipkin, etc. +systems can include traces that span an event-driven system. This extension is +meant to contain historical data of the parent trace, in order to diagnose +eventual failures of the system through tracing platforms like Jaeger, Zipkin, +etc. ## Attributes @@ -35,10 +36,10 @@ if used, MUST carry the same trace information contained in protocol specific tr Given a multi hop event transmission, the Distributed Tracing Extension, if used, MUST carry the trace information of the starting trace of the transmission. In other words, it MUST NOT carry trace information of each individual hop, since this information is usually -carried using protocol specific defined headers, understood by tools like [OpenTelemetry](https://opentelemetry.io/). +carried using protocol specific headers, understood by tools like [OpenTelemetry](https://opentelemetry.io/). Middleware between the source and the sink of the event could eventually add a Distributed Tracing Extension -if the source didn't included any, in order to provide to the sink the starting trace of the transmission. +if the source didn't include any, in order to provide to the sink the starting trace of the transmission. An example with HTTP: diff --git a/http-protocol-binding.md b/http-protocol-binding.md index 4df911914..feda27327 100644 --- a/http-protocol-binding.md +++ b/http-protocol-binding.md @@ -150,15 +150,15 @@ If a receiver detects the CloudEvents media type, but with an event format that it cannot handle, for instance `application/cloudevents+avro`, it MAY still treat the event as binary and forward it to another party as-is. -When the `Content-Type` header is not prefixed with the CloudEvents media type, -being able to know when the message ought to be attempted to be parsed as a -CloudEvent can be a challenge. While this specification can not mandate that -senders do not include any of the CloudEvents HTTP headers when the message -is not a CloudEvent, it would be reasonable for a receiver to assume that if -the message has all of the mandatory CloudEvents attributes as HTTP headers -then it's probably a CloudEvent. However, as with all CloudEvent messages, if -it does not adhere to all of the normative language of this specification -then it is not a valid CloudEvent. +When the `Content-Type` header value is not prefixed with the CloudEvents media +type, knowing when the message ought to be parsed as a CloudEvent can be a +challenge. While this specification can not mandate that senders do not include +any of the CloudEvents HTTP headers when the message is not a CloudEvent, it +would be reasonable for a receiver to assume that if the message has all of the +mandatory CloudEvents attributes as HTTP headers then it's probably a +CloudEvent. However, as with all CloudEvent messages, if it does not adhere to +all of the normative language of this specification then it is not a valid +CloudEvent. ### 3.1. Binary Content Mode diff --git a/kafka-protocol-binding.md b/kafka-protocol-binding.md index d155a06cc..63929f0a4 100644 --- a/kafka-protocol-binding.md +++ b/kafka-protocol-binding.md @@ -51,8 +51,7 @@ of event messages with Kafka; it solely defines how CloudEvents are expressed in the Kafka protocol as [Kafka messages][kafka-message-format]. The Kafka documentation uses "message" and "record" somewhat interchangeably and -therefore the terms are to be considered being synonyms for this specification -as well. +therefore the terms are to be considered synonyms in this specification as well. Conceptually, Kafka is a log-oriented store for records, each holding a singular key/value pair. The store is commonly partitioned, and the partition for a @@ -130,15 +129,14 @@ event format that it cannot handle, for instance `application/cloudevents+avro`, it MAY still treat the event as binary and forward it to another party as-is. -When the `content-type` header is not prefixed with the CloudEvents -media type, being able to know when the message ought to be attempted to be -parsed as a CloudEvent can be a challenge. While this specification can not -mandate that senders do not include any of the CloudEvents headers -when the message is not a CloudEvent, it would be reasonable for a receiver -to assume that if the message has all of the mandatory CloudEvents attributes -as headers then it's probably a CloudEvent. However, as with all -CloudEvent messages, if it does not adhere to all of the normative language of -this specification then it is not a valid CloudEvent. +When the `content-type` header value is not prefixed with the CloudEvents media +type, knowing when the message ought to be parsed as a CloudEvent can be a +challenge. While this specification can not mandate that senders do not include +any of the CloudEvents headers when the message is not a CloudEvent, it would be +reasonable for a receiver to assume that if the message has all of the mandatory +CloudEvents attributes as headers then it's probably a CloudEvent. However, as +with all CloudEvent messages, if it does not adhere to all of the normative +language of this specification then it is not a valid CloudEvent. If the `content-type` header is not present then the receiver uses _structured_ mode with the JSON event format. diff --git a/mqtt-protocol-binding.md b/mqtt-protocol-binding.md index c850d050a..fe7aa6399 100644 --- a/mqtt-protocol-binding.md +++ b/mqtt-protocol-binding.md @@ -126,15 +126,15 @@ If a receiver finds a CloudEvents media type as per the above rule, but with an event format that it cannot handle, for instance `application/cloudevents+avro`, it MAY still treat the event as binary and forward it to another party as-is. -When the `Content Type` property is not prefixed with the CloudEvents -media type, being able to know when the message ought to be attempted to be -parsed as a CloudEvent can be a challenge. While this specification can not -mandate that senders do not include any of the CloudEvents properties -when the message is not a CloudEvent, it would be reasonable for a receiver -to assume that if the message has all of the mandatory CloudEvents attributes -as message properties then it's probably a CloudEvent. However, as with all -CloudEvent messages, if it does not adhere to all of the normative language of -this specification then it is not a valid CloudEvent. +When the `Content Type` header value is not prefixed with the CloudEvents media +type, knowing when the message ought to be parsed as a CloudEvent can be a +challenge. While this specification can not mandate that senders do not include +any of the CloudEvents properties when the message is not a CloudEvent, it would +be reasonable for a receiver to assume that if the message has all of the +mandatory CloudEvents attributes as message properties then it's probably a +CloudEvent. However, as with all CloudEvent messages, if it does not adhere to +all of the normative language of this specification then it is not a valid +CloudEvent. With MQTT 3.1.1, the content mode is always _structured_ and the message payload MUST use the [JSON event format][json-format]. diff --git a/proprietary-specs.md b/proprietary-specs.md index 43fabb12b..45f9cf12e 100644 --- a/proprietary-specs.md +++ b/proprietary-specs.md @@ -11,7 +11,7 @@ the responsibility of the respective project maintainers. - Create a spec that follows the structure of an existing binding specification (e.g. [http](http-protocol-binding.md) or [amqp](amqp-protocol-binding.md)) - this will help SDK development. - **NOTES:** - - The spec needs to be publically accessible and managed by the proposing organization. - - The spec should clearly state the version(s) of CloudEvents supported. + - The spec must be publically accessible and managed by the proposing organization. + - The spec must clearly state the version(s) of CloudEvents supported. - Open a pull request against this file. - Respond to any comments on the pull request and potentially join one of the regularly scheduled working group sessions. diff --git a/protobuf-format.md b/protobuf-format.md index 018d57fd7..c6423391b 100644 --- a/protobuf-format.md +++ b/protobuf-format.md @@ -93,7 +93,7 @@ message CloudEventAttributeValue { In this model an attribute's name is used as the map *key* and is associated with its *value* stored in the appropriately typed property. -This approach allows for attributes to be represented and transported +This approach allows attributes to be represented and transported with no loss of *type* information. ## 3. Data @@ -140,7 +140,8 @@ Transports that support content identification MUST use the following designatio ## 5. Examples -The following code-snippets shows how proto representations might be constucted asuming the availability of some convenience methods ... +The following code-snippets show how proto representations might be constucted +assuming the availability of some convenience methods. ### 5.1 Plain Text event data diff --git a/websockets-protocol-binding.md b/websockets-protocol-binding.md index 3617c4b54..98537a8a2 100644 --- a/websockets-protocol-binding.md +++ b/websockets-protocol-binding.md @@ -48,9 +48,9 @@ This specification does not prescribe rules constraining the use or handling of specific [HTTP target resource][rfc7230-section-5-1] to establish the WebSocket upgrade. -This specification prescribe rules constraining the [WebSockets +This specification prescribes rules constraining the [WebSockets Subprotocols][rfc6455-section-5-1] in order to reach agreement on the event -format to use, in order to exchange serialized CloudEvents. +format to use when sending and receiving serialized CloudEvents. Events are sent as WebSocket messages, serialized using an [event format][ce-event-format]. @@ -62,7 +62,7 @@ transferring events: _structured_ and _binary_. Because of the nature of WebSockets messages, this specification supports only _structured_ data mode, hence event metadata attributes and event data are -placed into the WebSockets messages using an [event format][ce-event-format]. +sent in WebSocket messages using an [event format][ce-event-format]. The [event format][ce-event-format] to be used in a full-duplex WebSocket stream is agreed during the [handshake](#14-handshake) and cannot change during the @@ -123,7 +123,7 @@ specified WebSocket frame type: | `cloudevents.proto` | [Protobuf event format][proto-format] | Binary | All implementations of this specification MUST support the [JSON event -format][json-format]. This specification doesn't support the [JSON batch +format][json-format]. This specification does not support the [JSON batch format][json-batch-format]. ### 1.6. Security @@ -146,7 +146,7 @@ contains a CloudEvent serialized using the agreed event format. The chosen [event format][ce-event-format] defines how all attributes, including the payload, are represented. -The event metadata and data MUST then be rendered in accordance with the event +The event metadata and data MUST be rendered in accordance with the event format specification and the resulting data becomes the payload. ## 4. References