Skip to content

Make extension attributes siblings to our attributes #225

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
duglin wants to merge 1 commit into from
Closed

Make extension attributes siblings to our attributes #225

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
19 changes: 6 additions & 13 deletions json-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,6 @@ The following table shows exemplary mappings:
| eventID | String | "1234-1234-1234"
| eventTime | Timestamp| "2018-04-05T17:31:00Z"
| contentType | String | "application/json"
| extensions | Map | { "extA" : "vA", "extB", "vB" }
| data | String | "<much wow=\"xml\"/>"
| data | Binary | "Q2xvdWRFdmVudHM="
| data | Map | { "objA" : "vA", "objB", "vB" }
Expand Down Expand Up @@ -140,11 +139,9 @@ Example event with `String`-valued `data`:
"source" : "/mycontext",
"eventID" : "A234-1234-1234",
"eventTime" : "2018-04-05T17:31:00Z",
"extensions" : {
"comExampleExtension" : "value"
},
"contentType" : "text/xml",
"data" : "<much wow=\"xml\"/>"
"data" : "<much wow=\"xml\"/>",
Copy link
Copy Markdown
Contributor

@inlined inlined Jun 20, 2018

Choose a reason for hiding this comment

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

It seems like we should still have some prose that says something along the lines of "additional attributes (extensions) are added as top-level keys to this document."

Copy link
Copy Markdown
Collaborator Author

@duglin duglin Jun 20, 2018

Choose a reason for hiding this comment

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

Hoping that'll be done by @clemensv's PR

"comExampleExtension" : "value"
}
```

Expand All @@ -157,11 +154,9 @@ Example event with `Binary`-valued data
"source" : "/mycontext",
"eventID" : "B234-1234-1234",
"eventTime" : "2018-04-05T17:31:00Z",
"extensions" : {
"comExampleExtension" : "value"
},
"contentType" : "application/vnd.apache.thrift.binary",
"data" : "... base64 encoded string ..."
"data" : "... base64 encoded string ...",
"comExampleExtension" : "value"
}
```

Expand All @@ -175,15 +170,13 @@ a `Map` or [JSON data](#31-special-handling-of-the-data-attribute) data:
"source" : "/mycontext",
"eventID" : "C234-1234-1234",
"eventTime" : "2018-04-05T17:31:00Z",
"extensions" : {
"comExampleExtension" : "value"
},
"contentType" : "application/json",
"data" : {
"appinfoA" : "abc",
"appinfoB" : 123,
"appinfoC" : true
}
},
"comExampleExtension" : "value"
}
```

Expand Down
36 changes: 15 additions & 21 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,14 @@ attributes and the event data will be materialized. For example, in the case
of a JSON serialization, the context attributes and the event data might
both appear within the same JSON object.

CloudEvent producers MAY include additional extension attributes within the
event. Each specification that defines how to serialize a CloudEvent will
define how extension attributes will appear. When defining a new extension
Copy link
Copy Markdown

@cathyhongzhang cathyhongzhang Jul 5, 2018

Choose a reason for hiding this comment

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

Need to clarify what is meant by "include additional extension attributes within the event"? Do you mean Event producer can include any random attributes (and give it a name the producer likes) within the top level event attributes? If so, how could the event consumers know the semantics of those attributes? How could the event consumers know how to decode the random attributes (are they strings or ints ?) and properly use them?

Copy link
Copy Markdown
Collaborator Author

@duglin duglin Jul 5, 2018

Choose a reason for hiding this comment

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

your question applies to all extensions no matter where they appear.

care SHOULD be taken to use a name that is descriptive enough to reduce the
chances of it overlapping with other extensions.
Copy link
Copy Markdown

@cathyhongzhang cathyhongzhang Jul 5, 2018

Choose a reason for hiding this comment

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

If we put all new attributes at the top level of the CloudEvents or in one big extension bag, then no matter how descriptive the name is, different people could interpret it differently since the same name could mean different things in different context. Proper categorization/grouping of attributes seems the way to go.

Copy link
Copy Markdown
Collaborator Author

@duglin duglin Jul 5, 2018

Choose a reason for hiding this comment

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

Actually, I come the opposite conclusion. Trying to define lots of different bags feels like an exercise in futility to me. Even the one bag you've defined for "correlation" already is ambiguous (see #258 (comment)) and overlaps with CE's own properties. If we can't even define one bag that doesn't overlap then I don't see how we'll be able to create lots.

I would much prefer a simple model where we have a single location for properties and people clearly define what each property "means", not necessarily what its "used for" since how each might be used (and in how many ways it might be used) will vary in each case. Note that the same property might be used for more than one reason at the same time and I think asking people to duplicate it would be a bad UX.

Copy link
Copy Markdown

@cathyhongzhang cathyhongzhang Jul 5, 2018

Choose a reason for hiding this comment

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

I feel defining lots of and thousands of random unrelated attributes in a single bag will be very confusing to the event consumer. The ambiguity you listed in #258 (comment)) applies to existing attribute eventTime and contentType etc. too.

See the [Extensions](extensions.md) document for a list of documented extension
attributes.

### eventType
* Type: `String`
* Description: Type of occurrence which has happened. Often this
Expand Down Expand Up @@ -206,38 +214,24 @@ Incompatible changes to the schema SHOULD be reflected by a different URL.
`contentType` values are defined in the event format specifications; for
example, the JSON event format defines the relationship in
[section 3.1](./json-format.md#31-special-handling-of-the-data-attribute).
When this attribute is omitted, the "data" attribute simply follows the
event format's encoding rules. For the JSON event format, the "data"
attribute value can therefore be a JSON object, array, or value.

When this attribute is omitted, the "data" attribute follows the
event format's encoding rules. For the JSON event format, the "data"
attribute value can therefore be a JSON object, array, or value.

For the binary mode of some of the CloudEvents transport bindings,
where the "data" content is immediately mapped into the payload of the
transport frame, this field is directly mapped to the respective transport
or application protocol's content-type metadata property. Normative rules
for the binary mode and the content-type metadata mapping can be found
for the binary mode and the content-type metadata mapping can be found
in the respective transport mapping specifications.

* Constraints:
* OPTIONAL
* If present, MUST adhere to the format specified in
[RFC 2046](https://tools.ietf.org/html/rfc2046)
* For Media Type examples see [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml)

### extensions
* Type: `Map`
* Description: This is for additional metadata and this does not have a
mandated structure. This enables a place for custom fields a producer or
middleware might want to include and provides a place to test metadata before
adding them to the CloudEvents specification.
See the [Extensions](extensions.md) document for a list of possible
attributes.
* Constraints:
* OPTIONAL
* If present, MUST contain at least one entry
* Examples:
* authorization data

## Data Attribute

As defined by the term [Data](#data), CloudEvents MAY include domain-specific
Expand Down