spec
spec copied to clipboard
XML format "looseness" voting issue
This is a somewhat experimental way of gathering opinions on this issue, but hopefully it'll be clear enough.
Each of my comments below contains:
- A description of what it's trying to convey
- A complete example of an XML CloudEvent or batch of CloudEvents. It doesn't include the XML document preamble, but does include all namespaces - so if anything is missing, its presence should not be inferred.
For each example, please add a 👍 response if you think it should be valid, and a 👎 if you think it should be invalid. (😕 is okay if you're on the fence!) The assumption is that any "extra data" that we deem valid would be ignored by SDKs by default, although any given SDK could have hooks to make additional information available of course.
Example 1: additional attribute in the <event>
element
<event additional="extra" specversion="1.0" xmlns="http://cloudevents.io/xmlformat/V1">
<id>sample-id</id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
</event>
Note: I wouldn't expect to count xml:space="preserve"
and similar attributes as "additional" - if we decide to prohibit additional attributes, we'll need to spec out exactly what we mean by "additional".
Example 2: text node in the <event>
element
<event specversion="1.0" xmlns="http://cloudevents.io/xmlformat/V1">
Additional text
<id>sample-id</id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
</event>
Example 3: non-CE-namespace element in the <event>
element
<event specversion="1.0" xmlns="http://cloudevents.io/xmlformat/V1">
<additional xmlns="http://example.com">This is not in the CE namespace</additional>
<id>sample-id</id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
</event>
Example 4: additional attribute in an element representing a context attribute
<event specversion="1.0" xmlns="http://cloudevents.io/xmlformat/V1">
<id additional="extra">sample-id</id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
</event>
Example 5: element within an element representing a context attribute
<event specversion="1.0" xmlns="http://cloudevents.io/xmlformat/V1">
<id>sample-id
<additional>Extra</additional>
</id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
</event>
(We could break this into 5a and 5b if the namespace of the unexpected element matters to folks.)
Example 6: additional element within a binary data element
<event specversion="1.0" xmlns="http://cloudevents.io/xmlformat/V1">
<id>sample-id</id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
<data xsi:type="xs:base64Binary">AQID
<additional>Extra</additional>
</data>
</event>
Example 7: additional element within a text data element
<event specversion="1.0" xmlns="http://cloudevents.io/xmlformat/V1">
<id>sample-id</id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
<data xsi:type="xs:string">Text
<additional>Extra</additional>
</data>
</event>
Example 8: text node as a direct child of an "any" data element
<event specversion="1.0" xmlns="http://cloudevents.io/xmlformat/V1">
<id>sample-id</id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
<data xsi:type="xs:any">Additional text
<actualData>Extra</actualData>
</data>
</event>
Example 9: additional attribute in the <batch>
element
<batch additional="extra" xmlns="http://cloudevents.io/xmlformat/V1">
<event specversion="1.0">
<id>sample-id</id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
</event>
</batch>
Example 10: text node in the <batch>
element
<batch xmlns="http://cloudevents.io/xmlformat/V1">
Additional text
<event specversion="1.0">
<id>sample-id</id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
</event>
</batch>
Example 11: non-CE-namespace element in the <batch>
element
<batch xmlns="http://cloudevents.io/xmlformat/V1">
<additional xmlns="http://example.com">This is not in the CE namespace</additional>
<event specversion="1.0">
<id>sample-id</id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
</event>
</batch>
Example 12: Comments anywhere
<batch xmlns="http://cloudevents.io/xmlformat/V1">
<!-- This is a comment in a batch -->
<event specversion="1.0">
<!-- This is a comment in an event -->
<id>sample-id<!-- This is a comment in a context attribute --></id>
<source>https://github.com/cloudevents</source>
<type>io.cncf.sample</type>
</event>
</batch>
(All in one example as I'm expecting this to be uncontroversially okay.)
Nice issue! Some comments to go along with my votes:
1 - as long as we make it clear that the only attribute CE defines is 'specversion' then SDKs can freely ignore all others w/o any harm
2 - this feels similar to unknown elements and comments, so for consistency we should ignore Text Nodes
3 - easy to detect and therefore easy to ignore. Doesn't interfere with our ability to add new elements later
4 - as long as we never see the need to define attributes for CE element then this seems like a very powerful extensibility tool for people
5 - just too weird for our simple typing system :-) Not sure what to do about cases like TEXT<element/>TEXT
6 - no because of 5 and because therefore it's not base64 encoded
7 - yes because it's just part of the string, no? or would they need to escape the child XML stuff? If they need to escape, then I'd change my vote to "no" to align with my response on 5
8 - yes, it's just part of the raw data, no? Similar questions to 7
9,10,11 - same as above since I don't see a difference so for consistency we should have the same answers
12 - yes but I'm not sure what they mean as part of <data>
... are they comments or part of the data? I suspect they're comments first and therefore would be removed before the data was converted into a string or binary blog. Right?
@duglin: For 7, no, I don't expect it to be part of the raw data. If you want to represent the text "Additional text <actualData>Extra</actualData>"
in any other XML document - as a single piece of text rather than a text node and an element node - you need to escape the <
as <
. If we were to allow this, I'd expect any SDK to either just make the data "Additional text" or (potentially, and horribly) "AdditionalTextExtra" (by concatenating all text nodes).
Let's see what others make of it all :)
@duglin: I've added an "on the fence" option as I couldn't quite bring myself to vote against all but the last one, which is my natural inclination. I don't know whether that affects any of your votes - I guess there are two ways in which one could be neutral, one of "I'm not sure what this would mean" and another of which is "I'm confident of what this would mean, but I don't know whether or not I like it".
ok - I think I agree with your view on 7, changed my vote for 7. On 8... doesn't the "any" allow for it to be valid?
Did some more thinking about 2 and 8... and while in general I like the idea, I just couldn't figure out how that would be presented to a user - especially if there's extra text between multiple CE elements. Seems like asking people to just use elements and attributes as extensions is cleaner.
On 8... doesn't the "any" allow for it to be valid?
I expect it's valid in terms of not breaking the terms of xs:any
- but multiple child elements would be too, and we've prohibited that. The intention of a <data>
element with a type of xs:any
is "my data is an XML element".
Please review this,and vote, by Monday next week so that @jskeet might be able to take some action in prep for next week's call.
ping @cloudevents/notify
Examples 1, 4, & 9...
In this scenario I'd ask that the additional attribute be in its own namespace ensuring the ce
namespace isn't polluted ... this also mean there's no chance of collisions in the future if/when we introduce new constructs.
@jskeet what's the status of this one?
Hmm... I'll need to look at it again to work out which ones have been decided on one way or another, and what's still open. I'll try to do that before Thursday's meeting.
So, out of these, examples 2, 5, 6, 7, 8, 10 and 12 are now implemented via #1002.
The summary of what remains:
- 1 and 9: additional attributes in the
event
orbatch
elements - 3 and 11: non-CE namespaced elements in the
event
orbatch
elements - 4: additional attribute in an element representing a context attribute
We still need to decide on those one way or another.
@jskeet what's the status of this issue? Still needed?
We should probably go with whatever @JemDay has implemented in Java, as that's now "in" - at least if it's been released in a stable version.
per 1/19 call @jskeet will PR remain open points
per 1/19 call @jskeet will PR remain open points