Skip to content

Resolve quote issue for HTTP Binary Transport Encoding. #413

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
n3wscott wants to merge 6 commits into from
Closed

Resolve quote issue for HTTP Binary Transport Encoding. #413

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
25cecd8
Atempting to resolve quote issue.
Apr 3, 2019
3c34416
Attempting to resolve quote issue.
Apr 3, 2019
305fb16
Merge branch 'quotes' of github.com:n3wscott/spec into quotes
Apr 30, 2019
cc305ab
Merge branch 'master' into quotes
Apr 30, 2019
a0bb8fe
try no quotes.
Apr 30, 2019
0538aa3
Quote json ints.:
Apr 30, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion amqp-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ exceptions noted below.
| CloudEvents | AMQP |
| ------------- | --------------------------- |
| String | [string][amqp-string] |
| Integer | [long][amqp-long] |
| Integer | [string][amqp-string] |
| Binary | [binary][amqp-binary] |
| URI-reference | [string][amqp-string] |
| Timestamp | [timestamp][amqp-timestamp] |
Expand Down
10 changes: 5 additions & 5 deletions amqp-transport-binding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,11 +201,11 @@ content-type: application/json; charset=utf-8

----------- application-properties -----------

cloudEvents:specversion: "0.3-wip"
cloudEvents:type: "com.example.someevent"
cloudEvents:time: "2018-04-05T03:56:24Z"
cloudEvents:id: "1234-1234-1234"
cloudEvents:source: "/mycontext/subcontext"
cloudEvents:specversion: 0.3-wip
cloudEvents:type: com.example.someevent
cloudEvents:time: 2018-04-05T03:56:24Z
cloudEvents:id: 1234-1234-1234
cloudEvents:source: /mycontext/subcontext
.... further attributes ...

------------- application-data ---------------
Expand Down
25 changes: 12 additions & 13 deletions http-transport-binding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,7 @@ specification, header names are case-insensitive.
##### 3.1.3.2 HTTP Header Values

The value for each HTTP header is constructed from the respective attribute's
[JSON value][json-value] representation, compliant with the [JSON event
unquoted [JSON value][json-value] representation, compliant with the [JSON event
Copy link
Copy Markdown
Contributor

@clemensv clemensv May 3, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An encoding that isn't using quotes is no longer using JSON. "Unquoted JSON value" doesn't make sense if the only JSON value type for which quotes are used are strings and the quotes are significant for type inference. The convenient thing about using JSON here was that we get to borrow all of the type system and encoding and character set rules for when we need to distinguish between numbers and strings and complex types and we get automatic type inference so that generic frameworks can surface up the right types in spite of being unaware of specific rules of extensions.

If we choose to revert to "it's all just strings" and we would then still care about being able to represent numbers and complex types, we need to have a common model for how to restrict those strings, or it would be up to any individual extension to define such constraints locally within their scope.

For instance, we might keep "integer" and mandate that attributes of that type MUST be encoded, for instance, per https://tools.ietf.org/html/rfc7159.html#section-6 - or we abandon the type model altogether and have that encoding rule as a constraint next to the attribute(s) that need it.

For URI-reference and Timestamp we already have such constraints in place by referring to RFC3986 and RFC 3339 as a type-level constraint and it seems to make sense to do that just once and do the same for Integer.

What we're definitely losing with dropping the quotes is type inference for values of extensions that a generic CloudEvents framework doesn't know the specs for, because you can't easily tell whether 41751 is a number or a legitimate string (solution: it's my postal code and therefore I wanted it to be a string). I think that's a little sad, because we're sacrificing that capability for optics.

Copy link
Copy Markdown
Member Author

@n3wscott n3wscott May 3, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is apples to oranges in regards to JSON encoding. JSON needs the " because JSON is bytes. HTTP headers are strings. We are currently doing a hack to put bytes as sting to be interpreted as a string because it has quotes.

Copy link
Copy Markdown
Contributor

@clemensv clemensv May 6, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand what the apples and the oranges are. We currently define the header value as to be JSON encoded:

"The value for each HTTP header is constructed from the respective attribute's JSON value representation"

The JSON encoding of a string is a string in quotes, again rendered as a string. The JSON encoding of an integer is a stringified integer, rendered as a string. You're adding "unquoted" into the definition above, but you can't just change the rules of JSON from the outside.

The consequence of dropping the quotes is simply that we're no longer encoding strings in compliance with JSON, i.e. we need to drop the JSON reference altogether and just say that everything is a string and then constrain the string content either at the type level (if we want to keep those) or at the attribute level.

format][json-format] specification.

Some CloudEvents metadata attributes can contain arbitrary UTF-8 string content,
Expand All @@ -226,8 +226,6 @@ with [RFC7230, sections 3, 3.2, 3.2.6][rfc7230-section-3]. The rules for
encoding of the percent character ('%') apply as defined in [RFC 3986 Section
2.4.][rfc3986-section-2-4].

JSON objects and arrays are NOT surrounded with single or double quotes.

#### 3.1.4 Examples

This example shows the _binary_ mode mapping of an event with an HTTP POST
Expand All @@ -236,11 +234,11 @@ request:
```text
POST /someresource HTTP/1.1
Host: webhook.example.com
ce-specversion: "0.3-wip"
ce-type: "com.example.someevent"
ce-time: "2018-04-05T03:56:24Z"
ce-id: "1234-1234-1234"
ce-source: "/mycontext/subcontext"
ce-specversion: 0.3-wip
ce-type: com.example.someevent
ce-time: 2018-04-05T03:56:24Z
ce-id: 1234-1234-1234
ce-source: /mycontext/subcontext
.... further attributes ...
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
Expand All @@ -254,11 +252,11 @@ This example shows a response containing an event:

```text
HTTP/1.1 200 OK
ce-specversion: "0.3-wip"
ce-type: "com.example.someevent"
ce-time: "2018-04-05T03:56:24Z"
ce-id: "1234-1234-1234"
ce-source: "/mycontext/subcontext"
ce-specversion: 0.3-wip
ce-type: com.example.someevent
ce-time: 2018-04-05T03:56:24Z
ce-id: 1234-1234-1234
ce-source: /mycontext/subcontext
.... further attributes ...
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
Expand Down Expand Up @@ -467,6 +465,7 @@ Content-Length: nnnn
- [RFC7540][rfc7540] Hypertext Transfer Protocol Version 2 (HTTP/2)

[ce]: ./spec.md
[extensions]: ./extensions/
[json-format]: ./json-format.md
[json-batch-format]: ./json-format.md#4-json-batch-format
[content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5
Expand Down
12 changes: 6 additions & 6 deletions json-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ exceptions noted below.
| CloudEvents | JSON |
| ------------- | -------------------------------------------------------------- |
| String | [string][json-string] |
| Integer | [number][json-number], only the `int` component is permitted |
| Integer | [string][json-string], interpreted as a [number][json-number] |
| Binary | [string][json-string], [Base64-encoded][base64] binary |
| URI-reference | [string][json-string] following [RFC 3986][rfc3986] |
| Timestamp | [string][json-string] following [RFC 3339][rfc3339] (ISO 8601) |
Expand Down Expand Up @@ -180,7 +180,7 @@ Example event with `String`-valued `data`:
"time" : "2018-04-05T17:31:00Z",
"comexampleextension1" : "value",
"comexampleextension2" : {
"otherValue": 5
"otherValue": "5"
},
"datacontenttype" : "text/xml",
"data" : "<much wow=\"xml\"/>"
Expand All @@ -198,7 +198,7 @@ Example event with `Binary`-valued data
"time" : "2018-04-05T17:31:00Z",
"comexampleextension1" : "value",
"comexampleextension2" : {
"otherValue": 5
"otherValue": "5"
},
"datacontenttype" : "application/vnd.apache.thrift.binary",
"data" : "... base64 encoded string ..."
Expand All @@ -217,7 +217,7 @@ or [JSON data](#31-special-handling-of-the-data-attribute) data:
"time" : "2018-04-05T17:31:00Z",
"comexampleextension1" : "value",
"comexampleextension2" : {
"otherValue": 5
"otherValue": "5"
},
"datacontenttype" : "application/json",
"data" : {
Expand Down Expand Up @@ -267,7 +267,7 @@ second with JSON data.
"time" : "2018-04-05T17:31:00Z",
"comexampleextension1" : "value",
"comexampleextension2" : {
"otherValue": 5
"otherValue": "5"
},
"datacontenttype" : "application/vnd.apache.thrift.binary",
"data" : "... base64 encoded string ..."
Expand All @@ -280,7 +280,7 @@ second with JSON data.
"time" : "2018-04-05T17:31:05Z",
"comexampleextension1" : "value",
"comexampleextension2" : {
"otherValue": 5
"otherValue": "5"
},
"datacontenttype" : "application/json",
"data" : {
Expand Down
2 changes: 1 addition & 1 deletion spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -411,7 +411,7 @@ The following example shows a CloudEvent serialized as JSON:
"time" : "2018-04-05T17:31:00Z",
"comexampleextension1" : "value",
"comexampleextension2" : {
"othervalue": 5
"othervalue": "5"
},
"datacontenttype" : "text/xml",
"data" : "<much wow=\"xml\"/>"
Expand Down