Skip to content

add json serialization #124

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

Merged
duglin merged 2 commits into from
Mar 29, 2018
Merged

add json serialization #124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6e74891
add json serialization
Mar 24, 2018
ae3820b
add example and make it clear optional stuff is optional
Mar 29, 2018
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
69 changes: 69 additions & 0 deletions serialization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# CloudEvents Serialization Profile - Version 0.1

This document specifies how a CloudEvent is to be serialized into certain
encoding formats. Compliant CloudEvents implementations that support these
formats MUST adhere to these rules for these formats.

## Table of Contents
- [Notational Conventions](#notational-conventions)
- [JSON](#json)

## Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to
be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).

## JSON

When serialized in [JSON](https://tools.ietf.org/html/rfc7159) a CloudEvent
MUST adhere to the following format:

```
{
"cloud-events-version": "cloud-events-version value",
Copy link
Copy Markdown
Contributor

@inlined inlined Mar 28, 2018

Choose a reason for hiding this comment

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

I'm curious whether it would be more useful to use valid fake values rather than prose in quotes.

Copy link
Copy Markdown
Collaborator Author

@duglin duglin Mar 28, 2018

Choose a reason for hiding this comment

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

I struggled with this because if we put fake values in there then we need something to say "property X from the spec goes into json property 'x'". While in many cases it should be really really obvious, I felt that a spec should be more explicit about it. If all we cared about was JSON I actually would have proposed that we have the serialization of each property next to its definition in the spec itself. But I didn't want to assume everyone would be ok with JSON getting special treatment.

Copy link
Copy Markdown
Collaborator Author

@duglin duglin Mar 29, 2018

Choose a reason for hiding this comment

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

@inlined I added an example to try to address your concern. See if that helps.

"event-id": "event-id value",
"namespace": "namespace value",
"source": {
Copy link
Copy Markdown

@SeanFeldman SeanFeldman Mar 24, 2018

Choose a reason for hiding this comment

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

@duglin isn't source a URI?

Copy link
Copy Markdown
Collaborator Author

@duglin duglin Mar 24, 2018

Choose a reason for hiding this comment

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

Not yet :-)

Copy link
Copy Markdown

@SeanFeldman SeanFeldman Mar 24, 2018

Choose a reason for hiding this comment

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

Fair enough. Pending #123 🙂

"type": "source-id value",
"id": "source-id value"
},
"event-type": "event-type value",
"event-type-version": "event-type value",
"schema-url": "schema-url value",
"extensions": {
... extensions values ...
},
"data": ... data value ...
Copy link
Copy Markdown
Contributor

@inlined inlined Mar 28, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

As an FYI: though Google&Firebase started out with a model like this where all context is at the top level with one magic field called "data", we generally considered this to be a mistake. Many languages have better ways to expose context (e.g. Golang's Context.context, or JavaScript's variadic parameter system) so we are migrating to a world where data & context are exposed separately/natively our runtimes. Alpha testers have given very positive feedback for this because it allows any existing function(SomeNativeType) to be a CloudFunction<SomeNativeType>.

To match this, the REST JSON is being migrated to a two-field JSON object with {"context", "data"}

Copy link
Copy Markdown
Collaborator Author

@duglin duglin Mar 28, 2018

Choose a reason for hiding this comment

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

I could live with that. What do other people think?

Copy link
Copy Markdown

@SeanFeldman SeanFeldman Mar 29, 2018

Choose a reason for hiding this comment

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

@inlined would extensions be under context or another sibling at the root level?

Copy link
Copy Markdown
Collaborator Author

@duglin duglin Mar 29, 2018

Choose a reason for hiding this comment

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

@inlined where would "could-events-version" go? I can see it being useful as a top-level thing since we may choose to rename data or context in a future version, but I can also see a need for that info to be passed downstream so people know how to interpret the context attributes based on our spec's version number.

I do want to explore this option, it feels cleaner - would make for a great follow-on PR

Copy link
Copy Markdown
Contributor

@deissnerk deissnerk Mar 29, 2018

Choose a reason for hiding this comment

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

@duglin I agree with @inlined that context and data should be on the same level as he suggested.

One more thing:
Do we need rules how to encode data, if the content-type is something binary or text/xml?

Copy link
Copy Markdown
Collaborator Author

@duglin duglin Mar 29, 2018

Choose a reason for hiding this comment

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

would that be something that the definition of the content-type (e.g. json spec) would need to define?

Copy link
Copy Markdown
Contributor

@deissnerk deissnerk Mar 29, 2018

Choose a reason for hiding this comment

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

afaik json spec does not cover this explicitly. Most people seem to base64 encode data.

Copy link
Copy Markdown
Collaborator Author

@duglin duglin Mar 29, 2018

Choose a reason for hiding this comment

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

yea, I did a quick search too and didn't find a lot. I guess we could offer some recommendations...

Copy link
Copy Markdown
Contributor

@inlined inlined Mar 29, 2018

Choose a reason for hiding this comment

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

Honestly I don't have the practical experience with content-type and cloud-events-version that I do with the other fields. Here's my first SWAG:

  • In my opinion, content-type is/should be meta to the whole spec (why are we dictating the content type within a payload that's already explicitly JSON encoded?). This should be dictated in the transport layer, not the encoding layer.
  • cloud-events-version looks cleanest at the top level in JSON though if it's going to show up in the programming model it might be easier to put it in context.
  • I have the strong opinion (weakly held) that extensions should be in context. The developer is likely to depend on these extensions and they should be easily accessible.

Copy link
Copy Markdown
Contributor

@deissnerk deissnerk Mar 29, 2018

Choose a reason for hiding this comment

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

@inlined My understanding is that this PR is about how to package an arbitrary cloudevent into json. I was just wondering what happens if the content-type (the context attribute) is text/xml or image/png. The result is supposed to be a valid json object. So data would need to be encoded somehow. I don't see how this can be delegated to another layer. For events that use json for their data section, there is of course no need for encoding.

}
```

Notes:
Copy link
Copy Markdown
Contributor

@markpeek markpeek Mar 24, 2018

Choose a reason for hiding this comment

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

Should there be a comment about extra fields in the serialized data? Such as:

- It is undefined whether extra fields are passed along or removed depending on the usage role and implementation. Those fields are best placed in the extensions map.

Copy link
Copy Markdown
Collaborator Author

@duglin duglin Mar 24, 2018

Choose a reason for hiding this comment

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

I expanded on the thought a little - see what you think.

Copy link
Copy Markdown
Contributor

@markpeek markpeek Mar 24, 2018

Choose a reason for hiding this comment

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

Thanks for the update. LGTM.

- The use of whitespace is not significant.
- The order of the properties, at any level, is not significant.
- CloudEvent producers MAY include additional properties in the JSON
but receivers MAY choose to ignore them. However, it is RECOMMENDED that
they be placed as children of the `extensions` property. Receivers
MUST NOT treat unkonwn additional properties as an error and MUST NOT stop
processing of the event as a result of their presence.
- Non-mandatory properties are NOT REQUIRED to be included in the JSON, but
if they are present then they MUST adhere to the format described.

Example:
```
{
"cloud-events-version": "0.1",
"event-id": "6480da1a-5028-4301-acc3-fbae628207b3",
"namespace": "product.example.com",
"source": {
"type": "repository",
"id": "AFN234769347623"
},
"event-type": "created",
"event-type-version": "v1.5",
"schema-url": "https://product.example.com/schema/repo-create",
"data": {
"path": "/JaneDoe/repos/mycode"
}
}
```
5 changes: 5 additions & 0 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@ Enter CloudEvents, a specification for describing event data in a common way.
CloudEvents seeks to ease event declaration and delivery across services,
platforms and beyond.

The [Serialization Profile](serialization.md) specifies how to
serialize a CloudEvent into certain encoding formats. Compliant CloudEvents
implementations that support those formats MUST adhere to the encoding rules
specified in the profile for those formats.

# Design Goals

CloudEvents are typically used in a distributed system to allow for services to
Expand Down