Skip to content

Latest commit

 

History

History
213 lines (153 loc) · 5.83 KB

xml-format.md

File metadata and controls

213 lines (153 loc) · 5.83 KB
Raw

XML Event Format for CloudEvents

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

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) documents.

  • The associated schema formalizes the structure of the XML document.

  • 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 container for CloudEvents attributes and an associated media type.

  • The Batch section describes how multiple CloudEvents may be packaged into a single XML document.

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

This specification promotes an attribute heavy XML document style; such a model presents advantages in terms of parsing/processing along with a more compact XML document representation.

Attribute and Element names are deliberately terse for performance reasons.

Preservation of attribute value type information is supported allowing custom extensions to be communicated without value type loss.

The model is formalized by this XML Schema.

2. Attributes

The CloudEvents type system is mapped to XML schema types as follows :

CloudEvents XML Type Tag
Boolean xs:boolean B
Integer xs:int I
String xs:string S
Binary xs:base64Binary BI
URI xs:anyURI following RFC 3986 U
URI-reference xs:anyURI following RFC 3986 UR
Timestamp xs:dateTime following RFC 3339 T

Each concrete CloudEvent context attribute is represented using an XML element with the following shape:

<Attr n="id" v="XXX-YYY-ZZZ-0000" t="S">

where :

  • n is the name of the context attribute
  • v is the value of the context attribute
  • t is the type of the attribute value acording to the Tag defined in the table above.

See section below on special handling for specversion

2.1 Specification Version

To better support streaming style processing the specification version (specversion context attribute) is communicated as an attribute of the enclosing CloudEvent enveloping element.

<CloudEvent specver="1.0">
</CloudEvent>

3. Data

The Data portion of a CloudEvent is contained is a <Data></Data> element and supports Binary, Text, and XML Data. Each represention is wrapped in a discriminating element:

Binary Data

Carried in an element with an expected type of xs:base64Binary

<Data>
    <Bin>... base64 encoded string ...</Bin>
</Data>

Text Data

Carried in an element with an expected type of xs:string

<Data>
    <Txt>Hello World</Txt>
</Data>

XML Data

Carried in an element with an expected type of xs:any

<Data>
    <Xml>
        <SomeElement>
            ....
        </SomeElement>
    </Xml>
</Data>

4. Envelope

Each CloudEvent is wholly represented as an XML element, the root xml document element is <CloudEvent ver="n.n"> with the ver attribute used to define the specification version being followed.

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

The enveloping element contains:

  • A set of context attributes.
  • An optional data element.

eg:

<CloudEvent ver="1.0" >
    <Attr n="id" v="000-1111-2222" t="S">
    <Attr n="time" v="2020-03-19T12:54:00-07:00" t="T">
    <Attr n="type" v="SOME.EVENT.TYPE" t="S"/>
    ....
    <Data>
        <Txt>Now is the winter of our discount tents...</Txt>
    </Data>
</CloudEvent>

5. XML Batch Format

In the XML Batch Format several CloudEvents are batched into a single XML document. The document 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:

<CloudEventBatch>
    <CloudEvent ver="1.0">
       ....
    </CloudEvent>
    <CloudEvent ver="1.0">
       ....
    </CloudEvent>
    ....
</CloudEventBatch>

An example of an empty batch of CloudEvents (typically used in a response, but also valid in a request):

<CloudEventBatch />

6. References

CloudEvents XML Schema