-
Notifications
You must be signed in to change notification settings - Fork 612
Type system changes // canonical string representation #432
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.
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
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -148,20 +148,47 @@ specific protocols (AWS Kinesis, Azure Event Grid). | |
|
|
||
| ## Type System | ||
|
|
||
| The following abstract data types are available for use in attributes. | ||
| The following abstract data types are available for use in attributes. Each of | ||
| these types MAY be represented differently by different event formats and in | ||
| transport metadata fields. This specification defines a canonical string-encoding | ||
| for each type that MUST be supported by all implementations. | ||
|
|
||
| A strongly-typed programming model that represents a CloudEvent or any | ||
| extension MUST be able to convert from and to the canonical string-encoding to | ||
| the runtime/language native type that best corresponds to the abstract type. | ||
|
|
||
| For example, the `time` attribute might be represented by the language's native | ||
| *datetime* type in a given implementation, but it MUST be settable providing | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "MUST be settable"... not sure what this means. Does this mean the SDK's setter MUST accept a "string" value from the user? Or is this more about how there are certain transports that will use the string-encoding and impls that support that transport must be prepared to convert between strings and the native type?
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Oh, the next sentence covers the transport stuff. So I think I'm back to not understanding what the "settable" part means in practice.
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @duglin "settable" means that the implementation MUST ALWAYS allow the app to set a
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ok that helps clarify things- thanks. However, is this out of scope for the spec? Should this be guidance in the sdk doc? I'm not sure the spec, which is just about (mainly) defining the metadata, should get into how the metadata is set/retrieved by the app/user. Especially via a "MUST" - as non-normative guidance I can see though. |
||
| an RFC3339 string, and it MUST be convertible to an RFC3339 string when mapped | ||
| to a header of an HTTP message. | ||
|
|
||
| A CloudEvents transport binding or event format implementation MUST likewise | ||
| be able to convert from and to the canonical string-encoding to the | ||
| corresponding data type in the encoding or in transport metadata fields. | ||
|
|
||
| An attribute value of type `Timestamp` might indeed be routed as a string | ||
| through multiple hops and only materialize as a native runtime/language type | ||
| at the producer and ultimate consumer. The `Timestamp` might also | ||
| be routed as a native transport type and might be mapped to/from the respective | ||
| language/runtime types at the producer and consumer ends, and never materialize | ||
| as a string. | ||
|
|
||
| - `Integer` - A whole number in the range -2,147,483,648 to +2,147,483,647 | ||
| inclusive. This is the range of a signed, 32-bit, twos-complement encoding. | ||
| Event formats do not have to use this encoding, but they MUST only use | ||
| `Integer` values in this range. | ||
| - String encoding: Integer portion of the JSON Number per [RFC 7159, Section 6](https://tools.ietf.org/html/rfc7159#section-6) | ||
| - `String` - Sequence of printable Unicode characters. | ||
| - `Binary` - Sequence of bytes. | ||
| - String encoding: Base64 encoding per [RFC4648](https://tools.ietf.org/html/rfc4648). | ||
| - `Map` - `String`-indexed dictionary of `Any`-typed values. | ||
| - String encoding: JSON Object per [RFC 7159, Section 4](https://tools.ietf.org/html/rfc7159#section-4) | ||
| - `Any` - Either a `Binary`, `Integer`, `Map` or `String`. | ||
| - `URI-reference` - String expression conforming to `URI-reference` as defined | ||
| in [RFC 3986 §4.1](https://tools.ietf.org/html/rfc3986#section-4.1). | ||
| - `Timestamp` - String expression as defined in | ||
| [RFC 3339](https://tools.ietf.org/html/rfc3339). | ||
| - `URI-reference` - Uniform resource identifier reference. | ||
| - String encoding: `URI-reference` as defined | ||
| in [RFC 3986 Section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1). | ||
| - `Timestamp` - Date and time expression using the Gregorian Calendar. | ||
| - String encoding: [RFC 3339](https://tools.ietf.org/html/rfc3339). | ||
|
|
||
| The `Any` type is a variant type that can take the shape of either a `Binary`, | ||
| `Integer`, `Map` or `String`. The type system is intentionally abstract, and | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Even if that impl only supports transports/formats that don't use the string encoding?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@duglin Yes, all implementations need to expect a string value to come across the wire where the "native" representation would be a binary-encoded number, for instance. Interop.