Skip to content

Latest commit

 

History

History
365 lines (287 loc) · 12.1 KB

xml-format.md

File metadata and controls

365 lines (287 loc) · 12.1 KB
Raw

XML Event Format for CloudEvents - Version 1.0.3-wip

Abstract

This format specification for CloudEvents defines how events are expressed in XML documents.

Status of this document

This document is a working draft.

Table of Contents

  1. Introduction
  2. Attributes
  3. Data
  4. Envelope
  5. XML Batch Format
  6. Examples

1. Introduction

CloudEvents is a standardized and protocol-agnostic definition of the structure and metadata description of events. This specification defines how elements defined in the CloudEvents specification are to be represented using Extensible Markup Language (XML) elements.

  • The Attributes section describes the representation and data type mappings for CloudEvents context attributes.

  • The Data section defines the container for the data portion of a CloudEvent.

  • The Envelope section defines an XML element to contain CloudEvent context attributes and data.

  • The Batch section describes how multiple CloudEvents can be packaged into a single XML element.

1.1. Conformance

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 RFC2119.

1.2 Approach

The XML representation used is deliberately verbose in favor of readability and deterministic processing.

Preservation of type information for CloudEvent attributes is supported allowing custom extensions to be communicated without type loss.

A schema-less approach has been taken favoring convention over rigid document structure.

The namespace http://cloudevents.io/xmlformat/V1 MUST be used.

When namespace prefixes are used a prefix of ce is preferred but MUST NOT be expected from an XML document processing perspective.

Where an event (or batch of events) is represented as a complete XML document, an XML document preamble SHOULD be included to ensure deterministic processing.

2. Attributes

The CloudEvents type system is mapped to a set of CloudEvent specific type designators as follows :

CloudEvents Type XML Format Type XML Schema Type Notes
Boolean ce:boolean xs:boolean true or false
Integer ce:integer xs:int
String ce:string xs:string
Binary ce:binary xs:base64Binary
URI ce:uri xs:anyURI following RFC 3986
URI-reference ce:uriRef xs:anyURI following RFC 3986
Timestamp ce:timestamp xs:dateTime following RFC 3339

Each CloudEvent context attribute MUST be represented as an XML element whose local name exactly matches that of the attribute.

See the envelope for special handing of the specversion context attribute.

Extension context attributes MUST be decorated with the appropriate CloudEvent type format designators using an xsi:type XML attribute, this allows them to be exchanged without loss of type information.

An XML element representing a core context attribute MAY be decorated with an xsi:type XML attribute. If present, this designator MUST match that of the type specified by the CloudEvent context attributes.

No other XML element attributes are expected, if present they MUST be ignored during processing.

    ...
    <id>AAABBBCCCNNN0000</id>
    ..
    <time>2021-08-14T14:30:22-08:00</time>
    ..
    <myextension xsi:type="ce:string">my extension value</myextension>
    <myboolean xsi:type="ce:boolean">false</myboolean>

3. Data

The data portion of a CloudEvent follows a similar model to that employed by the JSON Format specification. A <data> element MUST be used to encapsulate the payload.

An xsi:type is used to discrimate the payload type and MUST be present.

The <data> element MUST NOT occur more than once within an <event> element.

The following data representations are supported:

3.1 Binary Data

Binary data MUST be carried in an element with an defined type of xs:base64Binary and encoded appropriately..

Example:

<data xsi:type="xs:base64Binary">.........</data>

3.2 Text Data

Text MUST be carried in an element with a defined type of xs:string.

Example:

<data xsi:type="xs:string">This is text</data>

3.3 XML Data

XML data MUST be carried in an element with a defined type of xs:any with exactly one child XML element (with any mandatory namespace definitions).

Example:

<data xsi:type="xs:any">
    <myData xmlns="http://my.org/namespace">
        ....
    </myData>  
</data>

4. Envelope

Each CloudEvent is wholly represented as an <event> XML element that MUST carry the specversion as an XML attribute value.

Such a representation MUST use the media type application/cloudevents+xml.

The enveloping element contains:

  • A set of CloudEvent context attribute XML elements.
  • An OPTIONAL <data> XML element.

Example (XML preamble and namespace definitions omitted for brevity):

<event specversion="1.0">
    <time>2020-03-19T12:54:00-07:00</time>
    <datacontenttype>text/plain</datacontenttype>
    <id>000-1111-2222</id>
    <source>urn:uuid:123e4567-e89b-12d3-a456-426614174000</source>
    <type>SOME.EVENT.TYPE</type>
    <myboolean xsi:type="ce:boolean">false</myboolean>
    <data xsi:type="xs:string">Now is the winter of our discount tents...</data>
</event>

5. XML Batch Format

In the XML Batch Format several CloudEvents are batched into a single XML <batch> element. The element comprises a list of elements in the XML Format.

Although the XML Batch Format builds on top of the XML Format, it is considered as a separate format: a valid implementation of the XML Format doesn't need to support it. The XML Batch Format MUST NOT be used when only support for the XML Format is indicated.

An XML Batch of CloudEvents MUST use the media type application/cloudevents-batch+xml.

Example (XML preamble and namespace definitions omitted for brevity):

<batch>
    <event specversion="1.0">
       ....
    </event>
    <event specversion="1.0">
       ....
    </event>
    ....
</batch>

6. Examples

6.1 CloudEvent with PNG image data

<?xml version="1.0" encoding="UTF-8"?>
<event xmlns="http://cloudevents.io/xmlformat/V1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xmlns:xs="http://www.w3.org/2001/XMLSchema" specversion="1.0" >
    <time>2020-03-19T12:54:00-07:00</time>
    <datacontenttype>image/png</datacontenttype>
    <id>000-1111-2222</id>
    <source>urn:uuid:123e4567-e89b-12d3-a456-426614174000</source>
    <type>SOME.EVENT.TYPE</type>
    <data xsi:type="xs:base64Binary">... Base64 encoded data...</data>
</event>

6.2 CloudEvent with JSON event data

<?xml version="1.0" encoding="UTF-8"?>
<event xmlns="http://cloudevents.io/xmlformat/V1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xmlns:xs="http://www.w3.org/2001/XMLSchema" specversion="1.0" >
    <time>2020-03-19T12:54:00-07:00</time>
    <datacontenttype>application/json</datacontenttype>
    <id>000-1111-2222</id>
    <source>urn:uuid:123e4567-e89b-12d3-a456-426614174000</source>
    <type>SOME.EVENT.TYPE</type>
    <data xsi:type="xs:string">{ "salutation": "Good Morning", "text": "hello world" }</data>
</event>

6.3 CloudEvent with XML event data

6.3.1 Locally namespaced event data

<?xml version="1.0" encoding="UTF-8"?>
<event xmlns="http://cloudevents.io/xmlformat/V1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xmlns:xs="http://www.w3.org/2001/XMLSchema" specversion="1.0" >
    <time>2020-03-19T12:54:00-07:00</time>
    <datacontenttype>application/xml</datacontenttype>
    <id>000-1111-2222</id>
    <source>urn:uuid:123e4567-e89b-12d3-a456-426614174000</source>
    <type>SOME.EVENT.TYPE</type>
    <data xsi:type="xs:any">
        <geo:Location xmlns:geo="http://someauthority.example/">
            <geo:Latitude>51.509865</geo:Latitude>
            <geo:Longitude>-0.118092</geo:Longitude>
        </geo:Location>
    </data>
</event>

6.3.2 Explicit namespacing

<?xml version="1.0" encoding="UTF-8"?>
<ce:event xmlns:ce="http://cloudevents.io/xmlformat/V1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:geo="http://someauthority.example/"
          specversion="1.0" >
    <ce:time>2020-03-19T12:54:00-07:00</ce:time>
    <ce:datacontenttype>application/xml</ce:datacontenttype>
    <ce:id>000-1111-2222</ce:id>
    <ce:source>urn:uuid:123e4567-e89b-12d3-a456-426614174000</ce:source>
    <ce:type>SOME.EVENT.TYPE</ce:type>
    <ce:data xsi:type="xs:any">
        <geo:Location>
            <geo:Latitude>51.509865</geo:Latitude>
            <geo:Longitude>-0.118092</geo:Longitude>
        </geo:Location>
    </ce:data>
</ce:event>

6.3.3 ISO 20022 Usage Example

ISO 20022 is an XML based messaging standard used in the financial industry; this is a non-normative example.

<?xml version="1.0" encoding="UTF-8"?>
<event xmlns="http://cloudevents.io/xmlformat/V1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xmlns:xs="http://www.w3.org/2001/XMLSchema" specversion="1.0" >
    <time>2022-02-22T15:12:00-08:00</time>
    <datacontenttype>application/xml</datacontenttype>
    <id>000-1111-2222</id>
    <source>urn:uuid:123e4567-e89b-12d3-a456-426614174000</source>
    <type>com.mybank.pain.001.001.03</type>
    <data xsi:type="xs:any">
        <Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03">
            <CstmrCdtTrfInitn>
            <GrpHdr>
                <MsgId>ABC/060928/CCT001</MsgId>
                <CreDtTm>2022-02-22T14:07:00</CreDtTm>
                <NbOfTxs>3</NbOfTxs>
                <CtrlSum>2400.56</CtrlSum>
                <InitgPty>
                    <Nm>Cobelfac</Nm>
                    <Id>
                        <OrgId>
                            <Othr>
                                <Id>0468651441</Id>
                                <Issr>KBO-BCE</Issr>
                            </Othr>
                        </OrgId>
                    </Id>
                </InitgPty>
            </GrpHdr>
            <PmtInf>
                <PmtInfId> ABC/4560/2008-09-25</PmtInfId>
                <PmtMtd>TRF</PmtMtd>
                <BtchBookg>false</BtchBookg>

            <!-- Content ommited for brevity -->

            </PmtInf>
        </Document>
    </data>
</event>

6.3.4 Batch Example

<?xml version="1.0" encoding="UTF-8"?>
<batch xmlns="http://cloudevents.io/xmlformat/V1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <event specversion="1.0" >
        <time>2020-03-19T12:54:00-07:00</time>
        <datacontenttype>image/png</datacontenttype>
        <id>000-1111-2222</id>
        <source>urn:uuid:123e4567-e89b-12d3-a456-426614174000</source>
        <type>SOME.EVENT.TYPE</type>
        <data xsi:type="xs:base64Binary">... Base64 encoded data...</data>
    </event>
    <event specversion="1.0" >
        <time>2020-03-19T12:59:00-07:00</time>
        <datacontenttype>image/png</datacontenttype>
        <id>000-1111-3333</id>
        <source>urn:uuid:123e4567-e89b-12d3-a456-426614174000</source>
        <type>SOME.EVENT.TYPE</type>
        <data xsi:type="xs:base64Binary">... Base64 encoded data...</data>
    </event>
    .....
</batch>