Skip to content

HTTP transport and JSON mapping#148

Merged
duglin merged 12 commits intocloudevents:masterfrom
clemensv:issue93
Apr 19, 2018
Merged

HTTP transport and JSON mapping#148
duglin merged 12 commits intocloudevents:masterfrom
clemensv:issue93

Conversation

@clemensv
Copy link
Copy Markdown
Contributor

@clemensv clemensv commented Apr 5, 2018

Refers to #93

These two documents are proposals for the HTTP transport mapping and for the JSON event format.

Expect some unprompted churn for the next couple of days while I add a further clarifications and examples and do fixups for links, etc.

Please ask each and all questions you may have here in the form of comments; all questions will help to make the spec more legible.

Closes: #93

Signed-off-by: clemensv clemensv@microsoft.com


#### 3.2.4 Examples

This example shows a JSON event format encoded event, sent with a PUT request:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

maybe 'JSON encoded event'

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I agree the wording comes out a bit awkward, but it's indeed encoded using the JSON event format.

@@ -0,0 +1,338 @@
# HTTP Transport Binding for Cloud Events

Editor: Clemens Vasters (clemensv@microsoft.com)
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I'd prefer to remove this section. Or add the same (c) for all of our docs, but IMO its unnecessary.

We should, at some point, discuss the versioning scheme we're going to use for these secondary documents. I'm leaning towards having all docs be at the same level, otherwise mixing-n-matching will be kind of awkward.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Will do that


### 1.3. Content Modes

The specification defines two content modes for transferring events:
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

"The" or "This"? I assume you mean "This http mapping doc", so then "This" would be appropriate. With "The" I wasn't sure if you were referring to this doc or the CloudEvents spec.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I mean "this"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

handling.


### 2.1. contentType Attribute

The `contentType` attribute is assumed to contain a [RFC2046][RFC2046]
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

While technically correct, this section feels a bit odd. Its so short and doesn't add anything beyond what the CE spec itself says. In fact, I don't think we should be repeating what the spec says since it could lead to things being out of sync at some point. For now I think we can remove this section

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I'm using the section as a reference point in this spec, and it's also putting a hard reference on the contentType attribute in the main spec. If there were a debate breaking out about contentType in the main spec potentially also accommodating some oder kind of reference, I'm saying here that this won't work for HTTP. So that reinforcement of the string REALLY being RFC2046 is deliberate, because I prescribe how to evaluate it.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I'd like to keep the "contentType" section because it discusses one of the two properties that we do special handling for and with, even through I admit that it doesn't say anything substantially new for the property itself aside from aforementioned reinforcement of RFC2046.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I'd prefer not to duplicate RFC references from the spec. Propose simply linking to https://github.com/cloudevents/spec/blob/master/spec.md#contenttype

defaults to *binary* mode.

If a receiver detects the Cloud Events media type, but with an event format that
it cannot handle, for instance `application/cloudevents+avro`, it MAY still
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I wonder what "handle" means in this case? Do we need to get into the processing model at all?


#### 3.1.3. Metadata Headers

All [Cloud Events][CE] attributes with exception of `contentType` and `data`
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Didn't we already say this? Perhaps we need to reorder things so we only say it once.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

This is specifically saying that all attributes except those two become HTTP headers in this mode. So, it's not about contentType/data (which section 2 is largely about), but about the rest.


The naming convention for the HTTP header mapping of attributes is:

* Prefixed with "CE-"
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

MUST be prefixed with CE-

Examples:

* `eventTime` maps to `CE-EventTime`
* `eventId` maps to `CE-EventId`
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

s/Id/ID/ :-)

[JSON value][JSON-value] representation, compliant with the [JSON event
format][JSON-format] specification.

The JSON value MUST NOT contain any unencoded LF (ASCII 0x10) or CR (ASCII
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Perhaps it would be better to point to the HTTP spec and let it define what value http header values can/should be - and how to encode/escape them?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I do this here specifically to bring this spec into compliance with HTTP. We can't have CRLF inside of a value (and neither of them singly), inside an HTTP header.

https://tools.ietf.org/html/rfc7230#section-3

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I've been doing a substantial rework of that rule now to cover UTF-8 content as well.

CE-CloudEventsVersion: "0.1"
CE-EventType: "com.example.someevent"
CE-EventTime: "2018-04-05T03:56:24Z"
CE-EventId: "1234-1234-1234"
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

s/Id/ID/

Content-Type: application/json; charset=utf-8
Content-Length: nnnn

{
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I wonder if we should remove the {}'s otherwise people might thing that {} isn't part of the app data, and I believe in this example it is.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

That's why I broke those across multiple lines. I find the notation here somewhat better than adding fake data that people will then argue about.


#### 3.2.3. Metadata Headers

Implementations MAY include the same HTTP headers as defined for the [binary
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

While I think its ok for people to do this, we should make it clear that doing so doesn't remove their requirement to include the same properties in the JSON/body.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I'm clarifying that.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

looks good

json-format.md Outdated

Such a representation uses the media type `application/cloudevents+json`

> The media type must be registered with IANA
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

We should open an issue to track this - then we can remove it from this doc.

json-format.md Outdated
"eventType" : "com.example.someevent",
"eventTypeVersion" : "1.0",
"source" : "/mycontext",
"eventId" : "A234-1234-1234",
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

s/Id/ID/

json-format.md Outdated
"eventType" : "com.example.someevent",
"eventTypeVersion" : "1.0",
"source" : "/mycontext",
"eventId" : "B234-1234-1234",
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

s/Id/ID/

@duglin
Copy link
Copy Markdown
Collaborator

duglin commented Apr 9, 2018

Overall I like what's in here. I think the 2nd doc and the existing serialization.md docs should probably be merged - don't see much value in splitting the json serialization details across two docs. But, that merging and other syntax restructuring can be done later.

LGTM to getting this in there so people can submit follow-on PR to tweak, but it gives us a good baseline to work with for now.

@duglin
Copy link
Copy Markdown
Collaborator

duglin commented Apr 9, 2018

DCO checker failing - need to sign all commits

@clemensv
Copy link
Copy Markdown
Contributor Author

clemensv commented Apr 9, 2018

What makes the DCO checker required?

@duglin
Copy link
Copy Markdown
Collaborator

duglin commented Apr 9, 2018

We need some kind of legal check in-place, usually either CLAs or DCOs. Not sure we want to deal with CLAs

@caniszczyk
Copy link
Copy Markdown
Contributor

caniszczyk commented Apr 9, 2018 via email

@clemensv
Copy link
Copy Markdown
Contributor Author

clemensv commented Apr 9, 2018

@duglin I will also have an AMQP serialization doc to go along with the AMQP transport binding because I need a type system mapping for AMQP metadata (this will only define elements and not a body format). I also think we'll want to have BSON or MessagePack event formats eventually, so I think there ought to be format specific docs.


##### 3.1.3.1 HTTP Header Names

The naming convention for the HTTP header mapping of attributes is:
Copy link
Copy Markdown
Collaborator

@duglin duglin Apr 15, 2018

Choose a reason for hiding this comment

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

Where do the set of "extension" attributes go? I assuming as HTTP headers, but we probably need to prefix them with something like CE-X-...

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yes, it'll make sense to promote each extension to being its own field. CE-X- seems ok. I'l add that.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Looks good thanks

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

+1 to CE-X-

duglin pushed a commit to duglin/spec that referenced this pull request Apr 15, 2018
We don't need the TBD since each mapping/serialization doc we produce
should state how extensions should appear. E.g. cloudevents#148

Closes: cloudevents#125

Signed-off-by: Doug Davis <dug@us.ibm.com>
@duglin
Copy link
Copy Markdown
Collaborator

duglin commented Apr 15, 2018

might want to "s/Cloud Event/CloudEvent/g"

@duglin
Copy link
Copy Markdown
Collaborator

duglin commented Apr 15, 2018

Should this PR delete the serialization.md file? Or if not, it seems like it should reference the doc.

Clemens Vasters added 5 commits April 17, 2018 15:10
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
Clemens Vasters added 5 commits April 17, 2018 15:16
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

#### 3.2.1. HTTP Content-Type

The [HTTP `Content-Type`][Content-Type] header is set to the media type of an
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

s/is set/MUST be set/ ?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

yes. will correct.

json-format.md Outdated
Such a representation uses the media type `application/cloudevents+json`

All REQUIRED and all not omitted OPTIONAL attributes in the given event
become members of the JSON object, with the respective JSON object member
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

s/become/MUST become/

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

We should probably mention that the order of the members in the resulting JSON is not relevant.

And, at some point (not as part of this PR) we should say whether its ok for people to include additional json properties in there outside of the extensions property. Normally I've seen people say its ok but then receivers just ignore unknown ones but when you have a well-defined location for extensions it becomes less clear if that's ok since you now have two spots for them. This could be a rat-hole discussion which is why I think a follow-on PR would be better. :-)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

agree on the "MUST become". will change.

Order is already addressed in https://tools.ietf.org/html/rfc7159#section-1 by stating that an object is an unordered collection, but I will add the hint.

The additional properties thing is probably a topic for the F2F. I'm in the "be lenient" camp and we do have versioning that helps with deconflicting collisions, but let's hear what others say.

@duglin
Copy link
Copy Markdown
Collaborator

duglin commented Apr 17, 2018

None of my suggested edit/comments are blocking, so LGTM - and thanks!

The naming convention for the HTTP header mapping of attributes is:

* MUST be prefixed with "CE-"
* Each attribute name's first character MUST be capitalized
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Since headers are case insensitive it seems strange to dictate their capitalization.


The receiver of the event can distinguish between the two modes by inspecting
the `Content-Type` header value. If the value is prefixed with the CloudEvents
media type `application/cloudevents`, indicating the use of a known [event
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I'm not happy with us inventing a new "application/cloudevents" content type. I strongly believe this should be an encoding format alone. E.g. application/json, text/xml, application/protobuf.

Failing to do so will make processing CloudEvents harder with off-the-shelf HTTP frameworks. For example, expressJS's built-in parsers will convert bodies to buffer instead of JS objects when the content-type is "application/cloudevents+json"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I don't buy that argument. By that logic, we could not have anything but text and octet-stream, ever. We are factually defining a media type here and that media type has different renderings. if ExpressJS doesn't know +json, someone should teach it that.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

AI: Thomas - will open an issue to track this

### 1.3. Content Modes

This specification defines two content modes for transferring events:
*structured* and *binary*. Every compliant implementation SHOULD support both
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Based on section 3, it sounds like every compliant receiver of events SHOULD support both. Unless I'm misinterpreting and anything that sends CloudEvents should be configurable to send either format?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I wrote "implementation" specifically so that producers and consumers have a choice when they use said implementation. Senders will typically pick one of the two and Consumers should be prepared to understand both. Do you think that needs rephrasing?

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

@inlined should we open an issue to revisit this? If you have some text in mind perhaps you could PR it? If you have some questions about the wording then others might as well

The naming convention for the HTTP header mapping of attributes is:

* Each attribute name MUST be prefixed with "CE-"
* Each attribute name's first character MUST be capitalized
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

It doesn't make sense to dictate the capitalization of headers when HTTP defines header names as case insensitive.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

We can drop that. I just think it helps with consistency.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

For tracking: #168

Examples:

* `example` maps to `CE-X-Example`
* `testExtension` maps to `CE-X-TestExtension`
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Many extensions will not be scalars. It may be worthwhile to define how extensions should be encoded into headers.

FWIW, with the labels proposal I was going to consider

CE-Label: key: value
CE-Label: secondkey: secondvalue

Though this will only work for a single map -> scalar

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The spec actually says that precisely https://github.com/cloudevents/spec/pull/148/files#diff-a60455371e295444f7369e2d9329c95bR188

The header value is actually a JSON value. You may not have caught that.

CE-EventType: "com.example.someevent"
CE-EventTime: "2018-04-05T03:56:24Z"
CE-EventID: "1234-1234-1234"
CE-Source: "/mycontext/subcontext"
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I know I've been confused in the past, but are we now allowing Source to be a URI-reference or still a full URI

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I believe URI references ought to be permissible.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

4/19 - Clemens will make it a full URI

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

AI: Thomas - Consider a new PR to change spec to change this property from URI to URI-Reference

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Thomas will open a PR later today to change URI to URI-Reference before we create v0.1 release

names in URIs [RFC3986 3.2.2][RFC3986], the JSON value MUST be encoded as
follows:

Non-printable ASCII characters and non-ASCII characters MUST first be encoded
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nit: to make this reversible we must also require percents to be re-encoded. Then we require percent decoding for all headers

As an example, Stackdriver logging unfortunately uses semantically different "/" (log repository structure) and "%2F" (client's resource structure).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I likely need to point clearer to the percent encoding rules in RFC3986 here; I actually don't want to define that here at all but fully lean on prior art. This here is intended to be a summary.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

4/19 call - Clemens will tweak

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

@inlined @clemensv added a sentence about % encoding. See if that helps. If not, let's open an issue to give it another try :-)


#### 3.2.2. Event Data Encoding

The chosen [event format](#14-event-formats) defines how all attributes,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I vehemently agree with this statement and wish it could be hoisted up even higher (e.g. this is not just a nuance of HTTP, but that CloudEvents will not support mixed-encoding).

This is the meat behind my argument that "content-type" is a requirement of every transport which we define in this spec, but is not itself a feature of a CloudEvent.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Content-Type is required in the event, because it designates the event payload and not the event.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

It really is about encoding. Maybe it should be a separate part of the CloudEvent spec, since it is about how the event is formatted, rather than the semantic of the event itself. (This was why I originally thought it didn't belong in the spec, but can see that people really want to put some encoding semantics in the spec itself. I'm ok with leaving this interpretation for now, and then seeing how it plays out in implementations.)

@austencollins
Copy link
Copy Markdown
Contributor

@clemensv This is incredible work. Thank you for thinking through all of this.

Copy link
Copy Markdown
Contributor

@ultrasaurus ultrasaurus left a comment

Choose a reason for hiding this comment

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

Please remove duplications from spec (and instead just reference the spec)


### 2.1. contentType Attribute

The `contentType` attribute is assumed to contain a [RFC2046][RFC2046]
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I'd prefer not to duplicate RFC references from the spec. Propose simply linking to https://github.com/cloudevents/spec/blob/master/spec.md#contenttype


## 3. HTTP Message Mapping

The event binding is identical for both HTTP request and response messages.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Is this implying that the system that receives an event is expected to return a response in CloudEvents format? Interesting, yet feels a bit outside of the scope of what we've been talking about.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I believe the intention is to say that this serialization is good for request and responses, not that both MUST be in our serialization formats at the same time.

The event binding is identical for both HTTP request and response messages.

The content mode is chosen by the sender of the event, which is either the
requesting or the responding party. Gestures that might allow solicitation of
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

What's a "gesture?"

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I paused on that one too :-) I think he meant "there may be data elsewhere" - but that's just a guess.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

We can reword that. With "gesture" I generally refer to an protocol interaction pattern. "Using a GET request to obtain an event held in a buffer". That's broader than "method".

### 2.2. data Attribute

The `data` attribute is assumed to contain opaque application data that is
encoded as declared by the `contentType` attribute.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This is confusing. How is the event meta-data encoded then? this seems to invite multiple kinds of encoding. contentType is pretty ambiguous in the specification -- there was prior discussion that it applied to meta-data attributes as well. The spec says "Describe the data encoding format" which it seems @clemensv interprets as the encoding of the data attribute (and others previously discussed as including all of the event data). Whatever is decided, please clarify in the spec.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I agree we should clarify that in the core spec. The contentType field only makes sense to describe the data field, but for that it is required.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

@clemensv can you open an issue (or PR if you have text in mind) for this so we don't lose track of it?


#### 3.2.2. Event Data Encoding

The chosen [event format](#14-event-formats) defines how all attributes,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

It really is about encoding. Maybe it should be a separate part of the CloudEvent spec, since it is about how the event is formatted, rather than the semantic of the event itself. (This was why I originally thought it didn't belong in the spec, but can see that people really want to put some encoding semantics in the spec itself. I'm ok with leaving this interpretation for now, and then seeing how it plays out in implementations.)

duglin pushed a commit that referenced this pull request Apr 19, 2018
We don't need the TBD since each mapping/serialization doc we produce
should state how extensions should appear. E.g. #148

Closes: #125

Signed-off-by: Doug Davis <dug@us.ibm.com>
Clemens Vasters added 2 commits April 19, 2018 19:28
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
@duglin duglin merged commit c11abc0 into cloudevents:master Apr 19, 2018
clemensv pushed a commit to clemensv/spec that referenced this pull request May 16, 2018
We don't need the TBD since each mapping/serialization doc we produce
should state how extensions should appear. E.g. cloudevents#148

Closes: cloudevents#125

Signed-off-by: Doug Davis <dug@us.ibm.com>
clemensv added a commit to clemensv/spec that referenced this pull request May 16, 2018
* HTTP binding and JSON event format

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

* HTTP header encoding changes and feedback fixes

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

* Cloud Events to CloudEvents

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

* Deleting serialization.md

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

* Adding extension header mapping

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

* TOC reference fix

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

* refer to JSON format

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

* change Makefile to remove serialization.md and add new specs

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

* fix RFC issues and branding

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

* fix RFC issues and branding

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

* added MUST clauses per Doug's comments on cloudevents#93

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>

* clarification for percent encoding with percent sign

Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
This was referenced May 24, 2018
@longit644 longit644 mentioned this pull request Sep 1, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

HTTP Mapping Strawman

7 participants