Skip to content

Latest commit

 

History

History
109 lines (79 loc) · 4.61 KB

avro-compact-format.md

File metadata and controls

109 lines (79 loc) · 4.61 KB
Raw

Avro Compact Event Format for CloudEvents - Version 1.0.3-wip

Abstract

The Avro Compact Format for CloudEvents defines how events are expressed in the Avro 1.9.0 Specification.

This differs from the Avro format in that:

  • It is optimized for performance, preferring a more compact representation.
  • It only supports spec version 1.0 (any changes to spec version requires changes to the Avro schema, which changes the fingerprint, breaking compatibility).
  • It does not natively support JSON (JSON can be straight-forwardly serialized to bytes and this was therefore not considered necessary).

Table of Contents

  1. Introduction
  2. Attributes
  3. Transport
  4. Examples

1. Introduction

CloudEvents is a standardized and protocol-agnostic definition of the structure and metadata description of events. This specification defines how the CloudEvents are to be represented as Avro 1.9.0.

The Attributes section describes the naming conventions and data type mappings for CloudEvents attributes for use as Avro message properties.

This specification does not define an envelope format. The Avro type system's intent is primarily to provide a consistent type system for Avro itself and not for message payloads.

The Avro event format does not currently define a batch mode format.

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.

2. Attributes

This section defines how CloudEvents attributes are mapped to the Avro type-system. This specification explicitly maps each attribute.

2.1 Type System Mapping

The CloudEvents type system MUST be mapped to Avro types as follows.

CloudEvents Avro
Boolean boolean
Integer int
String string
Binary bytes
URI string following RFC 3986 §4.3
URI-reference string following RFC 3986 §4.1
Timestamp long using timestamp-micros logical type

Extension specifications MAY define secondary mapping rules for the values of attributes they define, but MUST also include the previously defined primary mapping.

2.2 Definition

Users of Avro MUST use a message whose binary encoding is identical to the one described by the CloudEvent Avro Compact Schema.

3 Transport

Transports that support content identification MUST use the following designation:

application/cloudevents+avro-compact

4 Examples

The following table shows exemplary mappings:

CloudEvents Type Exemplary Avro Value
id string 7a0dc520-c870-4193c8
source string https://github.com/cloudevents
specversion N/A Spec version is always 1.0.
type string com.example.object.deleted.v2
datacontenttype string application/octet-stream
dataschema string http://registry.com/schema/v1/much.json
subject string mynewfile.jpg
time long 1685121689691000
data bytes [bytes]

References