Apache Avro# 1.8.2 Specification

（英文原文：http://avro.apache.org/docs/current/spec.pdf）

1 介绍

本文定义了Apache Avro，这是avro的权威规范。所有Avro的实现都必须遵循本文档。

2 Schema声明

Schema用json表示，可以有以下几种方式：

• 一个JSON字符串，命名一个定义的类型（defined type）；

• 一个JSON对象，形如：

{"type": "typeName" ...attributes...}

typeName可以是基本类型或派生类型名（见下文）。未在本文档中定义的属性是允许出现的，作为元数据，但是不能影响序列化数据的格式。

• 一个JSON数组，表示内嵌类型的集合。

2.1 基本类型

基本类型的命名如下：

• null没有值

• boolean一个二进制值

• int 32位有符号整数

• long 64位有符号整数

• float单精度(32位)IEEE754浮点数

• double双精度(64位)IEEE754浮点数

• bytes 8位无符号字节序列

• string unicode字符序列

基本类型没有指定的属性。

基本类型名也是定义类型名（defined type names）。因此，schema "string"等价于

{"type": "string"}

2.2 复合类型

Avro支持6种复合类型: records, enums, arrays, maps, unions and fixed.

2.2.1. Records

Records使用类型名record，并支持如下属性:

• name JSON字符串，提供record名称（必填）

• namespace JSON字符串，用来限定name

• doc JSON字符串，为Schema用户提供文档（可选）

• aliases字符串类型的JSON数组，为record提供备选名称（可选）

• fields JSON数组，列出字段(必填)。每个filed都是一个具有如下属性的JSON对象：

• name JSON字符串，提供字段的名称（必填）

• doc JSON字符串，为用户描述此字段

• type 可以是一个定以schema的JSON对象，或者是一个命名一个record定义的JSON字符串（必填）

• default 字段的缺省值，用于读取缺少该字段的实例（可选）。允许的值取决于字段的schema类型，参考下表。union字段的缺省值取union中第一个schema的缺省值。bytes和fixed的缺省是JSON字符串，其中unicode码点0-255被映射到无符号8位byte值0-255。

avro type	json type	example
null	null	null
boolean	boolean	true
int,long	integer	1
float,double	number	1.1
bytes	string	"\u00FF"
string	string	"foo"
record	object	{"a": 1}
enum	string	"FOO"
array	array	[1]
map	object	{"a": 1}
fixed	string	"\u00ff"

表一字段缺省值

• order 指定此字段如何影响record的排序顺序（可选）。有效值包括 "ascending" (缺省), "descending", or "ignore".

想要了解更多如何使用此字段的详细说明参考后面的排序部分。

• aliases 字符串类型的JSON数组，为本字段提供替代名称（可选）

例如，可以定义64位值的链表

{

"type": "record",

"name": "LongList",

"aliases": ["LinkedLongs"], // old name for this

"fields" : [

{"name": "value", "type": "long"}, // each element has a long

{"name": "next", "type": ["null", "LongList"]} // optional next element

]

}

2.2.2. Enums

Enums使用类型名enum，支持以下属性：

• name JSON字符串，提供enum的名称（必填）

• namespace JSON字符串，用来限定名称

• aliases 字符串类型的JSON数组，提供该enum的替代名称（可选）

• doc JSON字符串，为schema的用户提供文档（可选）

• symbols JSON数组，以字符串的形式列出符号（必填）。一个enum中的所有符号（symbols）必须是唯一的；禁止重复。每个symbol必须匹配正则表达式[A-Za-z_][A-Za-z0-9_]*（对name有同样的要求）

例如，扑克牌的花色可以定义如下：

{ "type": "enum",

"name": "Suit",

"symbols" : ["SPADES", "HEARTS", "DIAMONDS", "CLUBS"]

}

2.2.3. Arrays

Arrays使用类型名array，只支持一个属性：

• items array项的schema

例如，字符串的数组可以定义如下：

{"type": "array", "items": "string"}

2.2.4. Maps

Maps使用类型名map，支持一个属性：

• values map值的schema

map key的类型是string类型

例如，一个从string到long的map可以声明如下：

{"type": "map", "values": "long"}

2.2.5. Unions

如上所述，Unions用JSON数组表示。例如,["null","string"]声明了一个可能是null或string的schema。

（注意，当为一个record 的union字段取缺省值时，类型的缺省值必须与union第一个元素匹配。因此，对于包含null的union，null通常列在第一位，因为这样的union的缺省通常是null）

union不能包含两个以上相同类型的schema，除了命名类型（named types）record，fixed和enum。例如，包含两个array类型或两个map类型是不允许的，但是两个不同名称的类型是允许的。（当读写union时名称可以有效解决）

union不能直接包含union

2.2.6. Fixed

Fixed使用类型名fixed，支持以下属性：

• name命名fixed的字符串（必填）

• namespace字符串，用来限定name

• aliases字符串类型的JSON数组，为fixed提供可替换的名称（可选）

• size一个整数，指定每个值的字节数（必填）

例如, 16字节量可以声明如下：

{"type": "fixed", "size": 16, "name": "md5"}

2.3. Names

union、enum 和fixed都是命名类型（named types）。每个都有fullname，由两部分组成：name和namespace。等价的名称定义在fullname上。

fullname的name部分，record的字段name，enum的symbols必须：

• 以字母或下划线开头[A-Za-z_]

• 随后只能包含字母下划线和数字[A-Za-z0-9_]

namespace是一个以点分割的名称序列。空字符串也可以用作命名空间来指示null命名空间。等价名称（包括字段名和enum符号）以及fullname都是大小写敏感的。

在record、enum和fixed的定义中，fullname由以下方式来确定：

• name和namespace都被指定。例如，可以使用"name": "X","namespace": "org.foo" ，表明fullname为org.foo.X

• fullname被指定。如果name定义中包含一个点，则它被认为是一个fullname，指定的namespace被忽略。例如使用"name":"org.foo.X" 指明fullname为org.foo.X

• 只有name被指定，例如name不包含点。在这种情况下，namespace取自最近的schema或protocol。例如"name": "X" 被指定，如果这发生在名为org.foo.Y的reccord的一个属性范围内，则fullname是org.foo.X。如果没有最近的命名空间，则使用null命名空间。

对前面定义的名称（defined names）的引用与上面后两个例子相同：如果它们包含一个点，它们就是一个fullname，如果不包含点，namespace就是最近定义的命名空间。

基本类型没有命名空间，它们的名称不能在任何命名空间中定义。

schema或protocol不能包含fullname的多重定义。此外，name在使用前必须定义（所谓“前”，是按照深度优先，从左到右的顺序遍历JSON 解析树，其中，protocol的类型属性总是认为在消息属性之前）

2.4. Aliases

命名类型和字段可以有别名。可选用别名实现从写入端schema到读取端schema的映射。这方便schema的演变和处理不同的数据集。

别名功能的实现是通过用reader端schema中的别名来重写writer端的schema。例如，如果writer端schema被命名为Foo，reader端schema被命名为Bar，并有一个别名Foo，实现就像是当读取时将Foo命名为Bar。同样地，如果数据作为一个包含名为x属性的record写入，读时按照一个包含名为y、别名为x属性的record读取，实现就像是读取时将x命名为y。类型别名可以指定为完整命名空间限定，也可以指定为别名对应的name的命名空间。例如，一个名为a.b的类型，有别名c和x.y，则别名的完整限定名为a.c和x.y。