v1.0.2

Signed-off-by: Doug Davis <dug@us.ibm.com>

README.md

@@ -1,5 +1,7 @@
 # CloudEvents
 
+<!-- no verify-specs -->
+
 ![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png)
 
 Events are everywhere. However, event producers tend to describe events
@@ -22,35 +24,39 @@ a Cloud Native sandbox level project on
 
 ## CloudEvents Documents
 
-The following documents are available:
+The following documents are available ([Release Notes](misc/RELEASE_NOTES.md)):
 
 |                               |                                 Latest Release                                  |                                      Working Draft                                       |
 | :---------------------------- | :-----------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------: |
 | **Core Specification:**       |
-| CloudEvents                   |          [v1.0.1](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md)          |            [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md)             |
+| CloudEvents                   |          [v1.0.2](cloudevents/spec.md)          |            [WIP](https://github.com/cloudevents/spec/tree/main/cloudevents/spec.md)             |
 |                               |
 | **Optional Specifications:**  |
-| AMQP Protocol Binding         | [v1.0.1](https://github.com/cloudevents/spec/blob/v1.0.1/amqp-protocol-binding.md)  |    [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/amqp-protocol-binding.md)    |
-| AVRO Event Format             |      [v1.0.1](https://github.com/cloudevents/spec/blob/v1.0.1/avro-format.md)       |         [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/avro-format.md)         |
-| HTTP Protocol Binding         | [v1.0.1](https://github.com/cloudevents/spec/blob/v1.0.1/http-protocol-binding.md)  |    [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/http-protocol-binding.md)    |
-| JSON Event Format             |      [v1.0.1](https://github.com/cloudevents/spec/blob/v1.0.1/json-format.md)       |         [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/json-format.md)         |
-| Kafka Protocol Binding        | [v1.0.1](https://github.com/cloudevents/spec/blob/v1.0.1/kafka-protocol-binding.md) |   [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/kafka-protocol-binding.md)    |
-| MQTT Protocol Binding         | [v1.0.1](https://github.com/cloudevents/spec/blob/v1.0.1/mqtt-protocol-binding.md)  |    [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/mqtt-protocol-binding.md)    |
-| NATS Protocol Binding         | [v1.0.1](https://github.com/cloudevents/spec/blob/v1.0.1/nats-protocol-binding.md)  |    [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/nats-protocol-binding.md)    |
+| AMQP Protocol Binding         | [v1.0.2](cloudevents/bindings/amqp-protocol-binding.md)  |    [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/amqp-protocol-binding.md)    |
+| AVRO Event Format             |      [v1.0.2](cloudevents/formats/avro-format.md)       |         [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/avro-format.md)         |
+| HTTP Protocol Binding         | [v1.0.2](cloudevents/bindings/http-protocol-binding.md)  |    [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/http-protocol-binding.md)    |
+| JSON Event Format             |      [v1.0.2](cloudevents/formats/json-format.md)       |         [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/json-format.md)         |
+| Kafka Protocol Binding        | [v1.0.2](cloudevents/bindings/kafka-protocol-binding.md) |   [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/kafka-protocol-binding.md)    |
+| MQTT Protocol Binding         | [v1.0.2](cloudevents/bindings/mqtt-protocol-binding.md)  |    [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/mqtt-protocol-binding.md)    |
+| NATS Protocol Binding         | [v1.0.2](cloudevents/bindings/nats-protocol-binding.md)  |    [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/nats-protocol-binding.md)    |
 | WebSockets Protocol Binding   |                                        -                                        | [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/websockets-protocol-binding.md) |
-| Protobuf Event Format         |                                                                                 | [v1.0-rc1](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/protobuf-format.md)                                  |
-| Web hook                      |      [v1.0.1](https://github.com/cloudevents/spec/blob/v1.0.1/http-webhook.md)      |        [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/http-webhook.md)         |
+| Protobuf Event Format         | [v1.0.2](cloudevents/formats/protobuf-format.md) | [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/protobuf-format.md)                                  |
+| Web hook                      |      [v1.0.2](cloudevents/http-webhook.md)      |        [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/http-webhook.md)         |
 |                               |
 | **Additional Documentation:** |
 | CloudEvents Adapters          |                                        -                                        |          [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/adapters.md)           |
 | CloudEvents SDK Requirements  |                                        -                                        |             [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/SDK.md)             |
 | Documented Extensions         |                                        -                                        |    [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/documented-extensions.md)    |
-| Primer                        |         [v1.0.1](https://github.com/cloudevents/spec/blob/v1.0.1/primer.md)         |           [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/primer.md)            |
+| Primer                        |         [v1.0.2](cloudevents/primer.md)         |           [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/primer.md)            |
 | Proprietary Specifications    |                                        -                                        |      [WIP](https://github.com/cloudevents/spec/blob/main/cloudevents/proprietary-specs.md)      |
 
+There might be additional work-in-progress specifications being developed
+in the [`main`](https://github.com/cloudevents/spec/tree/main) branch.
+
 If you are new to CloudEvents, it is recommended that you start by reading the
-[Primer](primer.md) for an overview of the specification's goals and design
-decisions, and then move on to the [core specification](spec.md).
+[Primer](cloudevents/primer.md) for an overview of the specification's goals
+and design decisions, and then move on to the
+[core specification](cloudevents/spec.md).
 
 Since not all event producers generate CloudEvents by default, there is
 documentation describing the recommended process for adapting some popular
@@ -60,13 +66,14 @@ events into CloudEvents, see
 ## SDKs
 
 In addition to the documentation mentioned above, there is also an
-[SDK proposal](SDK.md). A set of SDKs is also being developed:
+[SDK proposal](cloudevents/SDK.md). A set of SDKs is also being developed:
 
 - [CSharp](https://github.com/cloudevents/sdk-csharp)
 - [Go](https://github.com/cloudevents/sdk-go)
 - [Java](https://github.com/cloudevents/sdk-java)
-- [Javascript/TypeScript](https://github.com/cloudevents/sdk-javascript)
+- [Javascript](https://github.com/cloudevents/sdk-javascript)
 - [PHP](https://github.com/cloudevents/sdk-php)
+- [PowerShell](https://github.com/cloudevents/sdk-powershell)
 - [Python](https://github.com/cloudevents/sdk-python)
 - [Ruby](https://github.com/cloudevents/sdk-ruby)
 - [Rust](https://github.com/cloudevents/sdk-rust)
@@ -85,9 +92,10 @@ native ecosystem by making our systems interoperable with CloudEvents.
 
 ## Process
 
-The CloudEvents project is working to formalize the [specification](spec.md)
-based on [design goals](primer.md#design-goals) which focus on interoperability
-between systems which generate and respond to events.
+The CloudEvents project is working to formalize the
+[specification](cloudevents/spec.md) based on
+[design goals](cloudevents/primer.md#design-goals) which focus on
+interoperability between systems which generate and respond to events.
 
 In order to achieve these goals, the project must describe:
 

SDK.md → cloudevents/SDK.md

@@ -1,5 +1,7 @@
 # CloudEvents SDK Requirements
 
+<!-- no verify-specs -->
+
 The intent of this document to describe a minimum set of requirements for new
 Software Development Kits (SDKs) for CloudEvents. These SDKs are designed and
 implemented to enhance and speed up CloudEvents integration. As part of
@@ -11,6 +13,7 @@ following SDKs:
 - [Java SDK](https://github.com/cloudevents/sdk-java)
 - [JavaScript SDK](https://github.com/cloudevents/sdk-javascript)
 - [PHP SDK](https://github.com/cloudevents/sdk-php)
+- [PowerShell](https://github.com/cloudevents/sdk-powershell)
 - [Python SDK](https://github.com/cloudevents/sdk-python)
 - [Ruby SDK](https://github.com/cloudevents/sdk-ruby)
 - [Rust SDK](https://github.com/cloudevents/sdk-rust)
@@ -45,7 +48,7 @@ Each SDK MUST meet these requirements:
 - Idiomatic usage of the programming language.
   - Using current language version(s).
 - Supports HTTP transport renderings in both `structured` and `binary`
-  encodings.
+  content mode.
 
 ### Object Model Structure Guidelines
 

adapters.md → cloudevents/adapters.md

@@ -1,10 +1,12 @@
 # CloudEvents Adapters
 
+<!-- no verify-specs -->
+
 Not all event producers will produce CloudEvents natively. As a result,
 some "adapter" might be needed to convert these events into CloudEvents.
 This will typically mean extracting metadata from the events to be used as
 CloudEvents attributes. In order to promote interoperability across multiple
-implementations of these adpaters, the following documents show the proposed
+implementations of these adapters, the following documents show the proposed
 algorithms that should be used:
 
 - [AWS S3](adapters/aws-s3.md)

adapters/aws-s3.md → cloudevents/adapters/aws-s3.md

@@ -26,7 +26,8 @@ Comments:
 - While the "eventSource" value will always be static (`aws:s3`) when
   the event is coming from S3, if some other cloud provider is supporting
   the S3 event format it is expected that this value will not be
-  `aws:s3` for them - it should be something specific to their environment.
+  `aws:s3` for them - it is expected to be something specific to their
+  environment.
 - Consumers of these events will therefore be able to know if the event
   is an S3 type of event (regardless of whether it is coming from S3 or
   an S3-compatible provider) by detecting the `com.amazonaws.s3` prefix

amqp-protocol-binding.md → cloudevents/bindings/amqp-protocol-binding.md

@@ -1,4 +1,4 @@
-# AMQP Protocol Binding for CloudEvents - Version 1.0.1
+# AMQP Protocol Binding for CloudEvents - Version 1.0.2
 
 ## Abstract
 
@@ -309,8 +309,8 @@ content-type: application/cloudevents+json; charset=utf-8
 - [OASIS-AMQP-1.0][oasis-amqp-1.0] OASIS Advanced Message Queuing Protocol
   (AMQP) Version 1.0
 
-[ce]: ./spec.md
-[json-format]: ./json-format.md
+[ce]: ../spec.md
+[json-format]: ../formats/json-format.md
 [content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5
 [json-value]: https://tools.ietf.org/html/rfc7159#section-3
 [rfc2046]: https://tools.ietf.org/html/rfc2046
@@ -323,3 +323,8 @@ content-type: application/cloudevents+json; charset=utf-8
 [message-format]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-message-format
 [data]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-data
 [app-properties]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-application-properties
+[amqp-boolean]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-boolean
+[amqp-long]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-long
+[amqp-binary]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-binary
+[amqp-string]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-string
+[amqp-timestamp]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-timestamp

http-protocol-binding.md → cloudevents/bindings/http-protocol-binding.md

@@ -1,4 +1,4 @@
-# HTTP Protocol Binding for CloudEvents - Version 1.0.1
+# HTTP Protocol Binding for CloudEvents - Version 1.0.2
 
 ## Abstract
 
@@ -95,7 +95,7 @@ can be used with the _batched_ content mode.
 
 This specification does not introduce any new security features for HTTP, or
 mandate specific existing features to be used. This specification applies
-identically to [HTTP over TLS]([RFC2818][RFC2818]).
+identically to [HTTP over TLS][rfc2818].
 
 ## 2. Use of CloudEvents Attributes
 
@@ -209,16 +209,75 @@ and per [RFC7230, section 3][rfc7230-section-3], HTTP headers MUST only use
 printable characters from the US-ASCII character set, and are terminated by a
 CRLF sequence with OPTIONAL whitespace around the header value.
 
-String values MUST be percent-encoded as described in [RFC3986, section
-2.4][rfc3986-section-2-4] before applying the header encoding rules described in
-[RFC7230, section 3.2.6][rfc7230-section-3-2-6].
-
-When decoding an HTTP message into a CloudEvent, these rules MUST be applied in
-reverse -- [RFC7230, section 3.2.6][rfc7230-section-3-2-6] decoding to an ASCII
-string, and then a **single round** of percent-decoding as described in
-[RFC3986, section 2.4][rfc3986-section-2-4] to produce a valid UTF-8 String.
-(Note that applying percent-decoding an incorrect number of times can result in
-message corruption or security issues.)
+When encoding a CloudEvent as an HTTP message, string values
+represented as HTTP header values MUST be percent-encoded as
+described below. This is compatible with [RFC3986, section
+2.1][rfc3986-section-2-1] but is more specific about what needs
+encoding. The resulting string SHOULD NOT be further encoded.
+(Rationale: quoted string escaping is unnecessary when every space
+and double-quote character is already percent-encoded.)
+
+When decoding an HTTP message into a CloudEvent, any HTTP header
+value MUST first be unescaped with respect to double-quoted strings,
+as described in [RFC7230, section 3.2.6][rfc7230-section-3-2-6]. A single
+round of percent-decoding MUST then be performed as described
+below. HTTP headers for CloudEvent attribute values do not support
+parenthetical comments, so the initial unescaping only needs to handle
+double-quoted values, including processing backslash escapes within
+double-quoted values. Header values produced via the
+percent-encoding described here will never include double-quoted
+values, but they MUST be supported when receiving events, for
+compatibility with older versions of this specification which did
+not require double-quote and space characters to be percent-encoded.
+
+Percent encoding is performed by considering each Unicode character
+within the attribute's canonical string representation. Any
+character represented in memory as a [Unicode surrogate
+pair][surrogate-pair] MUST be treated as a single Unicode character.
+The following characters MUST be percent-encoded:
+
+- Space (U+0020)
+- Double-quote (U+0022)
+- Percent (U+0025)
+- Any characters outside the printable ASCII range of U+0021-U+007E
+  inclusive
+
+Attribute values are already constrained to prohibit characters in
+the range U+0000-U+001F inclusive and U+007F-U+009F inclusive;
+however for simplicity and to account for potential future changes,
+it is RECOMMENDED that any HTTP header encoding implementation treats
+such characters as requiring percent-encoding.
+
+Space and double-quote are encoded to avoid requiring any further
+quoting. Percent is encoded to avoid ambiguity with percent-encoding
+itself.
+
+Steps to encode a Unicode character:
+
+- Encode the character using UTF-8, to obtain a byte sequence.
+- Encode each byte within the sequence as `%xy` where `x` is a
+  hexadecimal representation of the most significant 4 bits of the byte,
+  and `y` is a hexadecimal representation of the least significant 4
+  bits of the byte.
+
+Percent-encoding SHOULD be performed using upper-case for values A-F,
+but decoding MUST accept lower-case values.
+
+When performing percent-decoding (when decoding an HTTP message to a
+CloudEvent), values that have been unncessarily percent-encoded MUST be
+accepted, but encoded byte sequences which are invalid in UTF-8 MUST be
+rejected. (For example, "%C0%A0" is an overlong encoding of U+0020, and
+MUST be rejected.)
+
+Example: a header value of "Euro € 😀" SHOULD be encoded as follows:
+
+- The characters, 'E', 'u', 'r', 'o' do not require encoding
+- Space, the Euro symbol, and the grinning face emoji require encoding.
+  They are characters U+0020, U+20AC and U+1F600 respectively.
+- The encoded HTTP header value is therefore "Euro%20%E2%82%AC%20%F0%9F%98%80"
+  where "%20" is the encoded form of space, "%E2%82%AC" is the encoded form
+  of the Euro symbol, and "%F0%9F%98%80" is the encoded form of the
+  grinning face emoji.
 
 #### 3.1.4. Examples
 
@@ -458,11 +517,11 @@ Content-Length: nnnn
   Content
 - [RFC7540][rfc7540] Hypertext Transfer Protocol Version 2 (HTTP/2)
 
-[ce]: ./spec.md
-[ce-message]: ./spec.md#message
-[ce-types]: ./spec.md#type-system
-[json-format]: ./json-format.md
-[json-batch-format]: ./json-format.md#4-json-batch-format
+[ce]: ../spec.md
+[ce-message]: ../spec.md#message
+[ce-types]: ../spec.md#type-system
+[json-format]: ../formats/json-format.md
+[json-batch-format]: ../formats/json-format.md#4-json-batch-format
 [content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5
 [json-value]: https://tools.ietf.org/html/rfc7159#section-3
 [json-array]: https://tools.ietf.org/html/rfc7159#section-5
@@ -471,7 +530,7 @@ Content-Length: nnnn
 [rfc2818]: https://tools.ietf.org/html/rfc2818
 [rfc3629]: https://tools.ietf.org/html/rfc3629
 [rfc3986]: https://tools.ietf.org/html/rfc3986
-[rfc3986-section-2-4]: https://tools.ietf.org/html/rfc3986#section-2.4
+[rfc3986-section-2-1]: https://tools.ietf.org/html/rfc3986#section-2.1
 [rfc4627]: https://tools.ietf.org/html/rfc4627
 [rfc4648]: https://tools.ietf.org/html/rfc4648
 [rfc6839]: https://tools.ietf.org/html/rfc6839#section-3.1
@@ -483,3 +542,4 @@ Content-Length: nnnn
 [rfc7231]: https://tools.ietf.org/html/rfc7231
 [rfc7231-section-4]: https://tools.ietf.org/html/rfc7231#section-4
 [rfc7540]: https://tools.ietf.org/html/rfc7540
+[surrogate-pair]: http://unicode.org/glossary/#surrogate_pair