h4 { text-indent: 0.71cm; margin-top: 0.49cm; margin-bottom: 0.51cm; direction: ltr; color: #000000; line-height: 155%; text-align: justify; page-break-inside: avoid; orphans: 0; widows: 0 }
h4.western { font-family: "Arial", sans-serif; font-size: 14pt }
h4.cjk { font-family: "黑体"; font-size: 14pt }
h4.ctl { font-family: "Arial", sans-serif; font-size: 10pt; font-weight: normal }
h3 { text-indent: 0.71cm; margin-top: 0.46cm; margin-bottom: 0.46cm; direction: ltr; color: #000000; line-height: 172%; text-align: justify; page-break-inside: avoid; orphans: 0; widows: 0 }
h3.western { font-family: "Times New Roman", serif; font-size: 16pt }
h3.cjk { font-family: "宋体"; font-size: 16pt }
h3.ctl { font-family: "Times New Roman", serif; font-size: 10pt; font-weight: normal }
h2 { margin-top: 0.46cm; margin-bottom: 0.46cm; direction: ltr; color: #000000; line-height: 172%; text-align: justify; page-break-inside: avoid; orphans: 0; widows: 0 }
h2.western { font-family: "Arial", sans-serif; font-size: 16pt }
h2.cjk { font-family: "黑体"; font-size: 16pt }
h2.ctl { font-family: "Arial", sans-serif; font-size: 10pt; font-weight: normal }
h1 { margin-top: 0.6cm; margin-bottom: 0.58cm; direction: ltr; color: #000000; line-height: 200%; text-align: justify; page-break-inside: avoid; orphans: 0; widows: 0 }
h1.western { font-family: "Times New Roman", serif; font-size: 22pt }
h1.cjk { font-family: "宋体" }
h1.ctl { font-family: "Times New Roman", serif; font-size: 10pt; font-weight: normal }
p { margin-bottom: 0.25cm; direction: ltr; color: #000000; line-height: 120%; text-align: justify; orphans: 0; widows: 0 }
p.western { font-family: "Times New Roman", serif; font-size: 10pt }
p.cjk { font-family: "宋体"; font-size: 10pt }
p.ctl { font-family: "Times New Roman", serif; font-size: 10pt }

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。