Avrotize

Avrotize & Structurize

mcp-name: io.github.clemensv/avrotize

📚 文档与示例 | 🎨 转换示例集

Avrotize 是数据结构定义的“罗塞塔石碑”，可在多种数据和数据库架构格式之间进行转换，并为不同的编程语言生成代码。

例如，它是一个文档完善、行为可预测的转换器和代码生成器，可处理最初以 JSON Schema 定义的数据结构（复杂度不限）。

该工具采用源自 Apache Avro 的 Avrotize Schema 作为架构模型。

• 编程语言：Python、C#、Java、TypeScript、JavaScript、Rust、Go、C++
• SQL 数据库：MySQL、MariaDB、PostgreSQL、SQL Server、Oracle、SQLite、BigQuery、Snowflake、Redshift、DB2
• 其他数据库：KQL/Kusto、SurrealDB、MongoDB、Cassandra、Redis、Elasticsearch、DynamoDB、CosmosDB
• 数据架构格式：Avro、JSON Schema、JSON Structure、XML Schema（XSD）、Protocol Buffers 2 和 3、ASN.1、Apache Parquet、JSON Type Definition（JTD）、CDDL、CUE、FlatBuffers、Apache Thrift IDL、Smithy IDL、Cap'n Proto、RAML 1.0 Data Types 和 OpenAPI 3.x

安装

安装 Python 3.10 或更高版本后，即可从 PyPI 安装 Avrotize：Python 下载页面：

pip install avrotize

如需 MCP 服务支持（avrotize mcp），请安装 MCP extra：

pip install "avrotize[mcp]"

如需 SQL 数据库支持（sql2a 命令），请安装可选数据库驱动：

# PostgreSQL
pip install avrotize[postgres]

# MySQL
pip install avrotize[mysql]

# SQL Server
pip install avrotize[sqlserver]

# All SQL databases
pip install avrotize[all-sql]

用法

Avrotize 提供多个命令，可通过 Avrotize Schema 转换架构格式。

转换为 Avrotize Schema：

• avrotize s2a - 将 JSON 结构转换为 Avrotize Schema。
• avrotize j2a - 将 JSON Schema 转换为 Avrotize Schema。
• avrotize p2a - 将 Protobuf（2 或 3）Schema 转换为 Avrotize Schema。
• avrotize x2a - 将 XML Schema 转换为 Avrotize Schema。
• avrotize asn2a - 将 ASN.1 转换为 Avrotize Schema。
• avrotize jtd2a - 将 JSON Type Definition（JTD）转换为 Avrotize Schema。
• avrotize cue2a - 将受支持的 CUE Schema 子集转换为 Avrotize Schema。
• avrotize fbs2a - 将 FlatBuffers Schema 转换为 Avrotize Schema。
• avrotize thrift2a - 将 Apache Thrift IDL 转换为 Avrotize Schema。
• avrotize smithy2a - 将 Smithy 2.0 IDL 数据形状转换为 Avrotize Schema。
• avrotize capnp2a - 将 Cap'n Proto Schema 转换为 Avrotize Schema。
• avrotize raml2a - 将 RAML 1.0 数据类型转换为 Avrotize Schema。
• avrotize kstruct2a - 将 Kafka Connect Schema 转换为 Avrotize Schema。
• avrotize sql2a - 将 SQL 数据库 Schema 转换为 Avrotize Schema。
• avrotize k2a - 将 Kusto 表定义转换为 Avrotize Schema。
• avrotize surreal2a - 将 SurrealQL Schema 定义转换为 Avrotize Schema。
• avrotize pq2a - 将 Parquet Schema 转换为 Avrotize Schema。
• avrotize csv2a - 将 CSV 文件转换为 Avrotize Schema。

从 Avrotize Schema 转换：

• avrotize a2s - 将 Avrotize Schema 转换为 JSON 结构。
• avrotize a2j - 将 Avrotize Schema 转换为 JSON Schema。
• avrotize a2p - 将 Avrotize Schema 转换为 Protobuf 3 Schema。
• avrotize a2x - 将 Avrotize Schema 转换为 XML Schema。
• avrotize a2asn - 将 Avrotize Schema 转换为 ASN.1 Schema。
• avrotize a2jtd - 将 Avrotize Schema 转换为 JSON Type Definition（JTD）。
• avrotize a2cue - 将 Avrotize Schema 转换为受支持的 CUE Schema 子集。
• avrotize a2fbs - 将 Avrotize Schema 转换为 FlatBuffers Schema。
• avrotize a2thrift - 将 Avrotize Schema 转换为 Apache Thrift IDL。
• avrotize a2smithy - 将 Avrotize Schema 转换为 Smithy 2.0 IDL 数据形状。
• avrotize a2capnp - 将 Avrotize Schema 转换为 Cap'n Proto Schema。
• avrotize a2raml - 将 Avrotize Schema 转换为 RAML 1.0 数据类型。
• avrotize a2sql - 将 Avrotize Schema 转换为 SQL 表定义。
• avrotize a2k - 将 Avrotize Schema 转换为 Kusto 表定义。
• avrotize a2tsml - 将 Avrotize Schema 转换为表格模型脚本语言（TMSL）。
• avrotize a2surreal - 将 Avrotize Schema 转换为 SurrealQL Schema 定义。
• avrotize a2pq - 将 Avrotize Schema 转换为 Parquet 或 Iceberg Schema。
• avrotize a2ib - 将 Avrotize Schema 转换为 Iceberg Schema。
• avrotize a2mongo - 将 Avrotize Schema 转换为 MongoDB Schema。
• avrotize a2cassandra - 将 Avrotize Schema 转换为 Cassandra Schema。
• avrotize a2es - 将 Avrotize Schema 转换为 Elasticsearch Schema。
• avrotize a2dynamodb - 将 Avrotize Schema 转换为 DynamoDB Schema。
• avrotize a2cosmos - 将 Avrotize Schema 转换为 CosmosDB Schema。
• avrotize a2couchdb - 将 Avrotize Schema 转换为 CouchDB Schema。
• avrotize a2firebase - 将 Avrotize Schema 转换为 Firebase Schema。
• avrotize a2hbase - 将 Avrotize Schema 转换为 HBase Schema。
• avrotize a2neo4j - 将 Avrotize Schema 转换为 Neo4j Schema。
• avrotize a2dp - 将 Avrotize Schema 转换为 Datapackage Schema。
• avrotize a2csv - 将 Avrotize Schema 转换为 CSV Schema。
• avrotize a2graphql - 将 Avrotize Schema 转换为 GraphQL Schema。
• avrotize a2md - 将 Avrotize Schema 转换为 Markdown 文档。

JSON 结构之间的转换：

• avrotize j2s - 将 JSON Schema 转换为 JSON Structure。
• avrotize s2j - 将 JSON Structure 转换为 JSON Schema。
• avrotize s2p - 将 JSON Structure 转换为 Protocol Buffers（.proto 文件）。
• avrotize s2x - 将 JSON Structure 转换为 XML Schema（XSD）。
• avrotize s2asn - 将 JSON Structure Schema 转换为 ASN.1 schema。
• avrotize jtd2s - 将 JSON Type Definition（JTD）转换为 JSON Structure。
• avrotize s2jtd - 将 JSON Structure 转换为 JSON Type Definition（JTD）。
• avrotize cddl2s - 将 CDDL schema 转换为 JSON Structure。
• avrotize s2cddl - 将 JSON Structure 转换为 CDDL schema。
• avrotize oas2s - 将 OpenAPI 3.x 文档转换为 JSON Structure。
• avrotize cue2s - 将受支持的 CUE schema 子集转换为 JSON Structure。
• avrotize s2cue - 将 JSON Structure 转换为受支持的 CUE schema 子集。
• avrotize fbs2s - 将 FlatBuffers schema 转换为 JSON Structure。
• avrotize s2fbs - 将 JSON Structure 转换为 FlatBuffers schema。
• avrotize thrift2s - 将 Apache Thrift IDL 转换为 JSON Structure。
• avrotize s2thrift - 将 JSON Structure 转换为 Apache Thrift IDL。
• avrotize smithy2s - 将 Smithy 2.0 IDL 数据形状转换为 JSON Structure。
• avrotize s2smithy - 将 JSON Structure 转换为 Smithy 2.0 IDL 数据形状。
• avrotize capnp2s - 将 Cap'n Proto schema 转换为 JSON Structure。
• avrotize s2capnp - 将 JSON Structure 转换为 Cap'n Proto schema。
• avrotize raml2s - 将 RAML 1.0 数据类型转换为 JSON Structure。
• avrotize s2raml - 将 JSON Structure 转换为 RAML 1.0 数据类型。
• avrotize s2sql - 将 JSON Structure Schema 转换为 SQL 表定义。
• avrotize s2k - 将 JSON Structure Schema 转换为 Kusto 表定义。
• avrotize k2s - 将 Kusto 表定义转换为 JSON Structure。
• avrotize s2tsml - 将 JSON Structure 转换为 Tabular Model Scripting Language（TMSL）。
• avrotize s2pq - 将 JSON Structure 转换为 Parquet schema。
• avrotize s2ib - 将 JSON Structure 转换为 Iceberg schema。
• avrotize s2cassandra - 将 JSON Structure Schema 转换为 Cassandra schema。
• avrotize s2graphql - 将 JSON Structure schema 转换为 GraphQL schema。
• avrotize s2dp - 将 JSON Structure schema 转换为 Datapackage schema。
• avrotize s2csv - 将 JSON Structure schema 转换为 CSV schema。
• avrotize s2md - 将 JSON Structure schema 转换为 Markdown 文档。

从数据推断 schema：

• avrotize json2a - 从 JSON 文件推断 Avro 架构。
• avrotize json2s - 从 JSON 文件推断 JSON Structure 架构。
• avrotize xml2a - 从 XML 文件推断 Avro 架构。
• avrotize xml2s - 从 XML 文件推断 JSON Structure 架构。

从 Avrotize 架构生成代码：

• avrotize a2cs - 从 Avrotize 架构生成 C# 代码。
• avrotize a2java - 从 Avrotize 架构生成 Java 代码。
• avrotize a2py - 从 Avrotize 架构生成 Python 代码。
• avrotize a2ts - 从 Avrotize 架构生成 TypeScript 代码。
• avrotize a2js - 从 Avrotize 架构生成 JavaScript 代码。
• avrotize a2go - 从 Avrotize 架构生成 Go 代码。
• avrotize a2rust - 从 Avrotize 架构生成 Rust 代码。
• avrotize a2cpp - 从 Avrotize 架构生成 C++ 代码。

从 JSON Structure 生成代码：

• avrotize s2cs - 从 JSON Structure 架构生成 C# 代码。
• avrotize s2java - 从 JSON Structure 架构生成 Java 代码。
• avrotize s2py - 从 JSON Structure 架构生成 Python 代码。
• avrotize s2ts - 从 JSON Structure 架构生成 TypeScript 代码。
• avrotize s2js - 从 JSON Structure 架构生成 JavaScript 代码。
• avrotize s2go - 从 JSON Structure 架构生成 Go 代码。
• avrotize s2rust - 从 JSON Structure 架构生成 Rust 代码。
• avrotize s2cpp - 从 JSON Structure 架构生成 C++ 代码。

其他命令：

• avrotize validate - 根据 Avro 或 JSON Structure 架构验证 JSON 实例。
• avrotize mcp - 将 Avrotize 作为本地 MCP 服务运行，向 MCP 客户端提供转换工具。
• avrotize pcf - 创建 Avrotize 架构的解析规范形式（PCF）。
• avrotize validate-tmsl - 根据文档中定义的对象结构在本地验证 TMSL 脚本。

概览

MCP 服务

你可以通过 stdio 将 Avrotize 作为本地 MCP 服务运行：

avrotize mcp

其中包含可用于目录提交的元数据文件：

• 官方 MCP Registry 清单：server.json
• Microsoft/GitHub MCP 目录条目模板：catalogs/microsoft-github-mcp.md
• 通用跨目录清单（可选）：mcp-server.json
• VS Code + Copilot 使用快速入门：copilot-vscode-mcp-quickstart.md

要发布到官方 MCP Registry：

mcp-publisher validate server.json
mcp-publisher publish server.json

MCP 服务提供以下工具：

• 描述服务功能和路由指南（describe_capabilities）
• 列出可用的转换命令（list_conversions）
• 检查转换命令（get_conversion）
• 执行转换（run_conversion）

你可以使用 Avrotize 在 Avro/Avrotize Schema 与其他 Schema 格式之间进行转换，例如 JSON Schema、XML Schema（XSD）、Protocol Buffers（Protobuf）、ASN.1，以及 Kusto Data Table Definition（KQL）和 SQL Table Definition 等数据库 Schema 格式。这意味着你也可以通过 Avrotize Schema 将 JSON Schema 转换为 Protobuf。

你还可以根据 Avrotize Schema 文档生成 C#、Java、TypeScript、JavaScript 和 Python 代码。与原生 Avro 工具不同，Avrotize 可以生成不依赖 Avro 库的数据类，还可以选择添加用于 Jackson 或 System.Text.Json 等 JSON 序列化库的注解。

此工具不会转换数据（Schema 的实例），只转换数据结构定义。

请注意，此工具的主要目标是转换用于描述应用程序、数据库和消息系统中数据结构的 Schema。虽然项目的内部测试覆盖面很广，但将各种复杂文档 Schema（例如用于 DevOps 流水线或系统配置文件的 Schema）全部转换，并非此工具的首要目标。

为什么？

数据结构定义是数据交换、序列化和存储的重要组成部分。它们定义数据的形状和类型，是用于处理数据的工具和库的基础。几乎所有数据 Schema 语言都与特定的数据交换或存储格式相绑定，因此定义也被锁定在该格式中。

Avrotize 旨在作为一种工具，将数据定义从 JSON Schema 或 XML Schema 中“解锁”，使其能够用于其他场景。其目标还包括为数据格式之间的转码奠定基础，尽可能准确地将 Schema 定义转换为目标格式的 Schema 模型。数据本身的转码需要使用其他工具，不在本项目范围内。

这里有意使用“数据结构定义”而非“数据对象定义”这一术语。此工具关注的是可用于消息和事件载荷、数据序列化以及数据库表的数据结构，目标是让这些结构能够与常见编程语言类型进行清晰映射。

因此，Avrotize 有意忽略面向对象继承的常见建模方式。例如，从 JSON Schema 转换时，所有 allOf 表达式中的内容都会合并为单个记录类型，而不是尝试在 Avro 中建模继承树。

Avrotize Schema

Avrotize Schema 是一种模式模型，是广受欢迎的 Apache Avro Schema 模型的完整超集。Avrotize Schema 是此工具的“枢纽”。所有模式都会转换为 Avrotize Schema，或从 Avrotize Schema 转换而来。

由于 Avrotize Schema 是 Avro Schema 的超集，并使用了它的扩展功能，因此每个 Avrotize Schema 都是有效的 Avro Schema，反之亦然。

我们为什么选择 Avro Schema 作为基础模式模型？

Avro Schema……

• 提供了一种简单、清晰且简洁的方式来定义数据结构，非常易于理解和使用。
• 按照设计是自包含的，无需外部引用。Avro Schema 可以在单个文件中表达跨越多个命名空间边界的复杂数据结构层次，而 JSON Schema、XML Schema 和 Protobuf 都无法做到这一点。
• 可由代码生成器和其他工具“自顶向下”解析，因为它强制依赖项按顺序排列，不会出现前向引用。
• 起源于 Apache Hadoop 生态系统，广泛用于数据序列化与存储，以及系统间的数据交换。
• 支持原生类型和逻辑类型，能够满足许多业务和技术场景的需求。
• 能够很好地描述广受欢迎的 JSON 数据编码，并确保它始终可以干净地映射到多种编程语言和系统。相比之下，意外定义出难以映射为编程语言结构的 JSON Schema 并不困难。
• 本身以 JSON 表示，因此易于解析和生成；Protobuf 或 ASN.1 则需要专门的解析器。

需要指出的是，虽然 Avro Schema 非常适合定义数据结构，而且使用此工具或其他工具根据 Avro Schema 生成的数据类可以配合最流行的 JSON 序列化库使用，但 Apache Avro 项目自身的 JSON 编码与 JSON 的常见用法存在相当严重的互操作性问题。Avrotize 定义了另一种 JSON 编码

，见 avrojson.md。

Avro Schema 不支持 XML Schema 或 JSON Schema 的所有繁复功能，但这是优点而非缺陷，因为这样可以确保模式在不同系统和基础设施之间具有可移植性。具体来说，Avro Schema 不支持 JSON Schema 或 XML Schema 中的许多数据验证功能。Avro Schema 没有 pattern、format、minimum、maximum 或 required 关键字，也不支持条件验证。

在数据源自 XML 或 JSON，且由验证型 XML Schema 或 JSON Schema 描述的系统中，我们假设数据会先使用其原生模式语言进行验证，然后再使用 Avro Schema 进行转换、传输或存储。

为数据库表添加 CloudEvents 列

将 Avrotize Schema 转换为 Kusto 数据表定义（KQL）、SQL 表定义或 Parquet Schema 时，此工具可以添加用于表示 CloudEvents 属性的特殊列。CNCF CloudEvents 是一项用于以通用方式描述事件数据的规范。

为数据库表添加此类列的理由是：消息和事件通常会将事件元数据与负载数据分开，而将事件投影到数据库时，这些信息会合并。元数据通常包含事件的重要上下文信息，而这些信息并不包含在负载本身中。因此，构建事件存储时，此工具可以向数据库表添加这些列，以便轻松对齐消息上下文与负载。

将 Proto schema 转换为 Avrotize Schema

avrotize p2a <path_to_proto_file> [--out <path_to_avro_schema_file>]

参数：

• <path_to_proto_file>：要转换的 Protobuf schema 文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Avrotize Schema 文件路径。如果省略，则将输出发送到标准输出。

转换说明：

• 支持 Proto 2 和 Proto 3 语法。
• Proto 包名会映射为 Avro 命名空间。工具会解析导入，并将所有导入的类型合并到单个 Avrotize Schema 文件中。
• 工具会以 Avro 格式内嵌所有 Protobuf 3.0 的“众所周知”类型，并在导入相应类型时按需注入。只有 Timestamp 类型会映射为 Avro 逻辑类型 'timestamp-millis'。其余众所周知的 Protobuf 类型会保留为 Avro 记录类型，并使用相同的字段名称和类型。
• Protobuf 允许将任意标量类型用作 map 的键，而 Avro 不允许。从 Proto 转换为 Avro 时，映射键的类型信息会被忽略。
• 消息类型中的字段编号不会映射为 Avro 记录中的字段位置。Avro 中的字段按其在 Proto schema 中出现的顺序排列。因此，Avrotize Schema 也会忽略 Proto schema 中的 extensions 和 reserved 关键字。
• optional 关键字会使 Avro 字段可为空（与 null 类型构成联合类型），而 required 关键字会使字段不可为空。repeated 关键字会使 Avro 字段成为字段类型的数组。
• Proto 中的 oneof 关键字会映射为 Avro 联合类型。
• Proto schema 中的所有 options 均会被忽略。

将 Avrotize Schema 转换为 Proto schema

avrotize a2p <path_to_avro_schema_file> [--out <path_to_proto_directory>] [--naming <naming_mode>] [--allow-optional]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Protobuf schema 目录路径。如果省略，则将输出发送到标准输出。
• --naming：（可选）类型命名约定。可选值为 snake、camel、pascal。
• --allow-optional：（可选）启用对 'optional' 字段的支持。

转换说明：

• Avro 命名空间会解析为不同的 proto 包定义。工具会为 Avrotize Schema 中找到的每个命名空间创建一个新的 .proto 文件，其中包含包定义和一条 import 语句。
• Avro 类型联合 [] 会转换为 Proto 中的 oneof 表达式。Avro 允许在类型联合中使用映射和数组，而 Proto 只支持标量类型和消息类型引用。因此，在这类情况下，工具会生成仅包含一个数组或映射字段的消息类型，并将其添加到所属类型中，同时还会递归解析数组和映射值中的后续联合类型。
• 消息中的字段顺序遵循 Avro 记录中的字段顺序。需要将类型联合解析为 oneof 表达式时，必须为各个备选字段分配字段编号，这会导致后续字段的字段编号顺延。

将 CUE 架构子集转换为 Avrotize Schema

avrotize cue2a <path_to_cue_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>]

### Convert FlatBuffers schema to Avrotize Schema

```bash
avrotize fbs2a <path_to_fbs_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>]

### Convert Apache Thrift IDL to Avrotize Schema

```bash
avrotize thrift2a <path_to_thrift_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>]

### Convert Smithy IDL data shapes to Avrotize Schema

```bash
avrotize smithy2a <path_to_smithy_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>]

### Convert Cap'n Proto schema to Avrotize Schema

```bash
avrotize capnp2a <path_to_capnp_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>]

### Convert RAML Data Types to Avrotize Schema

```bash
avrotize raml2a <path_to_raml_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>]

参数：

• <path_to_cue_file>：要转换的 CUE 文件路径。省略时，将从 stdin 读取文件。
• --out：要写入的 Avrotize Schema 文件路径。省略时，输出将写入 stdout。
• --namespace：（可选）生成的 Avrotize Schema 记录的命名空间。省略时，将使用简单的 CUE package 名称作为命名空间。

支持的子集 / 限制：

• 支持：架构风格的定义 #Name: { ... }、作为生成记录的顶层字段、必填字段 name: T、可选字段 name?: T、基本类型 string、int、float、number、bool、bytes 和 null（int 映射为 Avro long；number 映射为 Avro double）。
• 支持：将嵌套结构体转换为记录、将开放列表 [...]T 转换为数组、将开放结构体 { [string]: T } 转换为映射、对其他定义的引用（#Other）、将析取转换为 Avro 联合类型、可空析取（如 *null | T 或 T | null）、将字符串字面量析取转换为使用净化后符号的 Avro 枚举，以及简单默认值，如 name: T | *default。
• 不在支持范围内：完整的 CUE 约束求解、简单 package 声明以外的导入、复杂约束和推导式、计算表达式或统一表达式、边界和正则表达式约束（>0、=~"..."）、插值，以及 package/module 解析。不支持的结构会被跳过或映射为宽泛的字符串类型，并附带转换说明，而不会导致程序崩溃。

示例：

package demo

#Person: {
  name: string
  age?: int
  tags: [...string]
  status: "new" | "active"
}

将 Avrotize Schema 转换为 CUE 架构子集

avrotize a2cue <path_to_avro_schema_file> [--out <path_to_cue_file>] [--namespace <cue_package_hint>]

转换说明：

• Avro 记录会转换为 CUE 定义（#Name: { ... }），字段会转换为 name: Type，可空联合类型会尽可能转换为可选字段，枚举会转换为字符串析取，数组会转换为 [...T]，映射会转换为 { [string]: T }。
• Avro int 和 long 都会输出为 CUE int；float 输出为 float；double 输出为 number。Avro 命名空间会简化为 CUE package 名称，取命名空间的最后一段。
• 转换器输出与 cue2a 接受的实用架构子集相同；它不会尝试还原 CUE 约束、导入、推导式或计算表达式。

将 CUE 架构子集转换为 JSON Structure

avrotize cue2s <path_to_cue_file> [--out <path_to_structure_file>] [--namespace <namespace>]

cue2s 通过中间 Avrotize Schema 文件进行转换，因此采用与 cue2a 相同的 CUE 支持子集和限制。

将 JSON 结构转换为 CUE 架构子集

avrotize s2cue <path_to_structure_file> [--out <path_to_cue_file>] [--namespace <cue_package_hint>]

s2cue 通过 Avrotize Schema 中间文件转换，并输出与 a2cue 相同的实用 CUE 架构子集。

• <path_to_fbs_file>：要转换的 FlatBuffers .fbs 架构文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Avrotize Schema 文件路径。如果省略，则将输出发送到标准输出。
• --namespace：（可选）覆盖 Avrotize Schema 的 FlatBuffers 命名空间。

转换说明和限制：

• FlatBuffers namespace 声明会映射为 Avro 命名空间。table 和 struct 声明会映射为 Avro 记录；FlatBuffers struct 带有固定的内联布局语义，而 Avro 无法表示这一点，因此生成的记录会对此进行说明。
• FlatBuffers 枚举会映射为 Avro 枚举。整数枚举值会保留在非标准的 Avrotize ordinals 注释中；仅了解 Avro 枚举符号的使用方可以忽略这些整数值。
• FlatBuffers 联合会映射为由其成员记录类型组成的 Avro 联合。
• 标量映射：有符号 8/16/32 位整数映射为 Avro int；无符号 32 位整数和所有 64 位整数映射为 Avro long；超出有符号 64 位范围的 uint64/ulong 值无法通过 Avro long 精确表示；float 和 double 分别映射为 Avro float 和 double；string 映射为 Avro string。
• 向量会映射为 Avro 数组，但 [ubyte]/[uint8] 会映射为 Avro bytes。
• 不带 (required) 的表字段会输出为可空的 Avro 字段，并将默认值设为 null。对于可空字段，FlatBuffers 字段默认值会保留为 Avrotize fbsDefault 注释。
• root_type 会保留为记录级别的 root_type 注释。

将 Avrotize Schema 转换为 FlatBuffers 架构

avrotize a2fbs <path_to_avro_schema_file> [--out <path_to_fbs_file>] [--namespace <flatbuffers_namespace>]

- `<path_to_thrift_file>`: The path to the Apache Thrift IDL file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the Avrotize Schema file to write the conversion result to. If omitted, the output is directed to stdout.
- `--namespace`: (optional) Override the Avro namespace. Without an override, `namespace *` is used, then the first language-specific namespace.

Conversion notes and limitations:

- `struct`, `exception`, and `union` declarations are emitted as Avro records. Thrift unions are modeled as records whose fields are all nullable; Avro does not enforce the Thrift rule that at most one field is set.
- `enum` declarations are emitted as Avro enums. Ordinals are preserved in an `ordinals` annotation. Symbols and names that are not valid Avro names are sanitized.
- `typedef` aliases are resolved to their target type. `const` declarations and `service` definitions are skipped because they do not describe persistent data structures.
- `set<T>` is emitted as an Avro array and does not preserve uniqueness semantics. `map<string,V>` is emitted as an Avro map; maps with non-string keys are emitted as arrays of `{ key, value }` records.
- `include` statements are recorded by the parser but are not recursively resolved by the converter. Convert included IDL files separately or pre-expand them before conversion.

### Convert Avrotize Schema to Apache Thrift IDL

```bash
avrotize a2thrift <path_to_avro_schema_file> [--out <path_to_thrift_file>] [--namespace <thrift_namespace>]

- `<path_to_smithy_file>`: The path to the Smithy 2.0 IDL file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the Avrotize Schema file to write the conversion result to. If omitted, the output is directed to stdout.
- `--namespace`: (optional) Override the Smithy `namespace` for the emitted Avro namespace.

Conversion notes:

- Phase 1 supports Smithy data shapes only: `structure`, `union`, `enum`, `intEnum`, `list`, `map`, and scalar shape references. `service`, `operation`, `resource`, HTTP/protocol traits, mixins beyond simple parsing, and `apply` statements are explicitly out of scope and are skipped without failing conversion.
- Smithy `namespace` maps to Avro `namespace`. `@documentation` maps to Avro `doc`; `@required` makes a field non-nullable; non-required fields are nullable and default to `null`; `@default` maps to the Avro field default where Avro permits it. `@deprecated` and `@tags` are carried into `doc` text.
- Smithy `union` shapes are represented as Avro records whose alternatives are nullable fields, preserving member names while keeping the Avro schema valid. Avro field unions convert back to Smithy `union` shapes.
- Smithy `intEnum` converts to an Avro enum with an `ordinals` annotation; Avro itself stores enum symbols, so integer values are metadata for round-tripping.
- Smithy `list` and `map` members map to Avro arrays and maps. Avro maps are string-keyed, so Smithy map keys should be `String`; other key declarations are noted but cannot be represented as Avro map keys.
- Scalar mappings include `Blob`→`bytes`, `Boolean`→`boolean`, `String`→`string`, integer widths→`int`/`long`, floats→`float`/`double`, `Timestamp`→valid Avro `long` with `timestamp-millis`, `BigInteger`→`string`, `BigDecimal`→`double`, and `Document`→`string`.

### Convert Avrotize Schema to Smithy IDL data shapes

```bash
avrotize a2smithy <path_to_avro_schema_file> [--out <path_to_smithy_file>] [--namespace <smithy_namespace>]

- `<path_to_capnp_file>`: The path to the Cap'n Proto `.capnp` schema file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the Avrotize Schema file to write the conversion result to. If omitted, the output is directed to stdout.
- `--namespace`: Optional Avro namespace. If omitted, the input file name is used.

Conversion notes and limitations:

- Structs map to Avro records, enums map to Avro enums, and field ordinals are stored as `capnpOrdinal` metadata. Enum ordinals are stored as `capnpOrdinals`.
- Cap'n Proto fields are pointer-default/zero-default optional in practice; Avrotize emits nullable Avro fields (`["null", T]`) with `default: null` for non-`Void` fields.
- Primitive mapping: `Bool`→`boolean`; `Int8`/`Int16`/`Int32`→`int`; `Int64`→`long`; unsigned integers including `UInt64`→`long` (range checks are not represented); `Float32`→`float`; `Float64`→`double`; `Text`→`string`; `Data`→`bytes`; `Void`→`null`; `List(T)`→Avro array. No invalid Avro logical types are emitted.
- Anonymous and named Cap'n Proto unions are represented as nullable fields tagged with `capnpUnion` metadata rather than as exclusive Avro unions; exclusivity constraints are not enforced by Avro.
- Groups are represented as inline nested Avro records. Nested structs and enums are emitted as named Avro types in derived nested namespaces.
- The file id is accepted but not used as an Avro namespace seed. `interface`, `const`, `annotation`, imports, and using declarations are skipped.

### Convert Avrotize Schema to Cap'n Proto schema

```bash
avrotize a2capnp <path_to_avro_schema_file> [--out <path_to_capnp_file>] [--namespace <namespace_note>]

- `<path_to_raml_file>`: The path to the RAML 1.0 file or library. If omitted, the file is read from stdin.
- `--out`: The path to the Avrotize Schema file to write. If omitted, the output is directed to stdout.
- `--namespace`: (optional) Namespace for generated Avro named types.

Conversion notes:

- Phase 1 supports RAML 1.0 **Data Types** in the `types:` section only. API resources, methods, traits, resourceTypes, securitySchemes, annotations, and external `!include` expansion are explicitly out of scope and are ignored or left as inert YAML values.
- Object types with `properties:` become Avro records. Optional properties (`name?` or `required: false`) become nullable Avro fields with `null` first and default `null`.
- Scalar mappings are `string`→`string`, `number`→`double`, `integer`→`long`, `boolean`→`boolean`, `file`→`bytes`, and `nil`→`null`.
- RAML date/time precision is normalized to valid Avro logical types: `date-only`→`int`/`date`, `time-only`→`int`/`time-millis`, and `datetime-only`/`datetime`→`long`/`timestamp-millis`.
- Arrays use `T[]` or `type: array` with `items`. Unions use `A | B`; nullable `T?` is treated as `nil | T`.
- Maps use the documented RAML convention `properties: { "//": T }` or `additionalProperties: T` and become Avro maps.
- RAML enums become Avro enums; symbols are sanitized to Avro identifiers. Non-string enum base types are emitted as Avro enum symbols, so literal value typing is not preserved.

### Convert Avrotize Schema to RAML Data Types

```bash
avrotize a2raml <path_to_avro_schema_file> [--out <path_to_raml_file>] [--namespace <namespace_to_strip>]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 FlatBuffers .fbs 文件路径。如果省略，则将输出发送到标准输出。
• --namespace：（可选）覆盖 FlatBuffers 命名空间。

转换说明和限制：

• Avro 记录会输出为 FlatBuffers 表，Avro 枚举会输出为 FlatBuffers 枚举，数组会输出为向量，Avro bytes 会输出为 [ubyte]。
• 可空的 Avro 联合（["null", T]）会转换为可选的 FlatBuffers 字段。由多个命名类型分支组成的 Avro 联合会输出为 FlatBuffers union 声明。
• Avro 命名空间会映射为 FlatBuffers 命名空间。顶层记录或带有 root_type 注释的记录会输出为 root_type。
• Avro 映射、逻辑类型、固定类型、别名、验证注释以及任意自定义注释都没有直接对应的 FlatBuffers 类型，因此会被简化为兼容的字段类型，或直接省略。

将 Avrotize Schema 转换为 ASN.1 schema

avrotize a2asn <path_to_avro_schema_file> [--out <path_to_asn1_file>] [--module <asn1_module_name>]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 ASN.1 模块文件路径。如果省略，则将输出写入标准输出。如果未指定 --module，则根据输出文件名推导 ASN.1 模块名。
• --module：（可选）覆盖 ASN.1 模块名。

转换说明和限制：

• 输出的模块使用 DEFINITIONS AUTOMATIC TAGS，让 ASN.1 编译器自动消除 OPTIONAL 和 CHOICE 标签的歧义。
• Avro 记录映射为 SEQUENCE，Avro 枚举映射为 ENUMERATED，数组映射为 SEQUENCE OF，fixed 映射为 OCTET STRING (SIZE(n))。
• Avro 映射为 SEQUENCE OF SEQUENCE { key UTF8String, value ... }。
• 可空联合（["null", T]）会变为 OPTIONAL 成员；多分支联合会变为 ASN.1 CHOICE。
• 逻辑类型映射为 ASN.1 有用类型：date → DATE，time-millis/time-micros → TIME-OF-DAY，timestamp-* → DATE-TIME；由于 ASN.1 没有完全对应的类型，decimal、uuid 和 duration 会表示为 REAL/UTF8String。
• 标识符会经过处理以符合严格的 X.680 规范（用连字符代替下划线）；该模块会通过使用 asn1tools 编译器进行往返转换来验证。

将 JSON Structure schema 转换为 ASN.1 schema

avrotize s2asn <path_to_structure_schema_file> [--out <path_to_asn1_file>] [--module <asn1_module_name>]

参数：

• <path_to_structure_schema_file>：要转换的 JSON Structure schema 文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 ASN.1 模块文件路径。如果省略，则将输出写入标准输出。如果未指定 --module，则根据输出文件名推导 ASN.1 模块名。
• --module：（可选）覆盖 ASN.1 模块名。

转换说明和限制：

• 这是直接的 JSON Structure → ASN.1 映射；不会通过 Avrotize Schema 转换，因此可以保留更丰富的 JSON Structure 类型系统。
• 有大小范围的整数类型映射为 INTEGER，并保留准确的范围约束（例如，int8 → INTEGER (-128..127)，uint32 → INTEGER (0..4294967295)）。
• object 映射为 SEQUENCE，array 映射为 SEQUENCE OF，set 映射为 SET OF，map 映射为 SEQUENCE OF SEQUENCE { key UTF8String, value ... }，tuple 映射为位置型 SEQUENCE，choice 映射为 CHOICE。
• 字符串 enum/const 值映射为 ENUMERATED（保留符号标签及其序号）；整数 enum/const 值映射为 INTEGER (v1 | v2 | ...) 值约束（保留精确值）。
• $extends 会将基对象的属性合并到派生的 SEQUENCE 中；规范形式的 {"type": {"$ref": ...}} 引用、独立的 {"$ref": ...} 引用以及嵌套定义命名空间都会得到解析。
• 非必需或可空成员会变为 OPTIONAL。没有完全对应 ASN.1 类型的类型（uuid、uri、duration、jsonpointer）会表示为 UTF8String；any 映射为 ASN.1 开放类型 ANY。

将 FlatBuffers schema 转换为 JSON Structure

avrotize fbs2s <path_to_fbs_file> [--out <path_to_json_structure_file>] [--namespace <avro_schema_namespace>]

参数：

• <path_to_fbs_file>：要转换的 FlatBuffers .fbs schema 文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 JSON Structure 文件路径。如果省略，则将输出写入标准输出。
• --namespace：（可选）覆盖 Avrotize Schema 桥接过程中使用的命名空间。

转换说明：

• 此转换通过 Avrotize Schema 进行桥接（依次执行 fbs2a 和 a2s），因此具有上述 FlatBuffers 到 Avro 映射中列出的限制。
• 如果存在 FlatBuffers root_type 记录，则将其用作 JSON Structure 根类型。

将 JSON Structure 转换为 FlatBuffers schema

avrotize s2fbs <path_to_json_structure_file> [--out <path_to_fbs_file>] [--namespace <flatbuffers_namespace>]

参数：

• <path_to_json_structure_file>：要转换的 JSON Structure schema 文件的路径。如果省略，则从 stdin 读取文件。
• --out：用于写入转换结果的 FlatBuffers .fbs 文件的路径。如果省略，则将输出发送到 stdout。
• --namespace：（可选）覆盖 FlatBuffers 命名空间。

转换说明：

• 此转换通过 Avrotize Schema 进行桥接（依次执行 s2a 和 a2fbs），因此适用上文列出的 Avro 到 FlatBuffers 映射限制。

• 无法通过 Avrotize Schema 桥接保留的 JSON Structure 约束和元数据不会体现在生成的 FlatBuffers schema 中。

• --out：用于写入 Thrift IDL 文件的路径。如果省略，则将输出发送到 stdout。

• --namespace：（可选）覆盖输出的 namespace * 值。

转换说明和限制：

• Avro 记录会输出为带有连续字段 ID 的 Thrift struct 定义。Avro 枚举会输出为 Thrift 枚举。
• 可空的 Avro 联合（["null", T]）会输出为 optional 字段；其他多分支 Avro 联合会近似为 string。
• Avro 数组会输出为 list<T>，Avro 映射会输出为 map<string,V>。无法从 Avro 中恢复 Thrift set 和非字符串映射键语义。
• Avro 逻辑类型和自定义注释不会体现在 Thrift IDL 中。

将 Apache Thrift IDL 转换为 JSON Structure

avrotize thrift2s <path_to_thrift_file> [--out <path_to_structure_file>] [--namespace <avro_schema_namespace>]

先将 Thrift IDL 转换为 Avrotize Schema，再转换为 JSON Structure。因此，以上 Thrift 到 Avro 的限制同样适用。

将 JSON Structure 转换为 Apache Thrift IDL

avrotize s2thrift <path_to_structure_file> [--out <path_to_thrift_file>] [--namespace <thrift_namespace>]

先将 JSON Structure 转换为 Avrotize Schema，再转换为 Thrift IDL。因此，以上 Avro 到 Thrift 的限制同样适用。

• --out：用于写入 Smithy IDL 文件的路径。如果省略，则将输出发送到 stdout。
• --namespace：（可选）覆盖要输出的 Smithy 命名空间。

转换说明：

• Avro 记录会转换为 Smithy structure shape；可空联合会转换为可选成员；非空字段会以 @required 输出。

• Avro 枚举会转换为 Smithy enum shape；存在 ordinals 注释时，则转换为 intEnum。Avro 数组和映射会转换为 Smithy list 和 map shape。包含多个非空选项的 Avro 联合会转换为 Smithy union shape。

• 服务和操作建模明确不在第 1 阶段的范围内；此命令仅输出 Smithy 数据 shape。

• --out：用于写入 Cap'n Proto schema 文件的路径。如果省略，则将输出发送到 stdout。

• --namespace：可选命名空间说明，将作为注释写入生成的文件。

转换说明和限制：

• Avro 记录映射为 struct，枚举映射为 enum，数组映射为 List(T)，字符串映射为 Text，字节/定长数据映射为 Data，可空联合映射为非空的 Cap'n Proto 字段类型。
• 字段会使用确定性的连续序号（@0、@1、……）输出。生成的文件会带有稳定的文件 ID；如果 schema 需要使用项目自有的 Cap'n Proto ID，请替换该 ID。
• 多分支 Avro 联合会输出为嵌套选择结构体；存在 capnpUnion 元数据时，则输出为 union 块。Avro 映射会表示为生成的键/值条目结构体列表，因为 Cap'n Proto 没有直接的映射基本类型。

将 Cap'n Proto schema 转换为 JSON Structure

avrotize capnp2s <path_to_capnp_file> [--out <path_to_json_structure_file>] [--namespace <avro_schema_namespace>] [--naming <naming_mode>] [--avro-encoding]

此转换通过中间 Avrotize Schema 进行桥接，因此适用 capnp2a 文档中说明的 Cap'n Proto 限制。

将 JSON 结构转换为 Cap'n Proto 架构

avrotize s2capnp <path_to_json_structure_file> [--out <path_to_capnp_file>] [--namespace <namespace_note>]

此转换通过中间格式 Avrotize Schema 完成，因此适用 a2capnp 文档中说明的 Avro 到 Cap'n Proto 转换限制。

• <path_to_avro_schema_file>：Avrotize Schema 文件的路径。如果省略，则从标准输入读取文件。
• --out：要写入的 RAML 文件路径。如果省略，则将输出写入标准输出。
• --namespace：（可选）从生成的 RAML 类型引用中剥离的命名空间。

转换说明：

• 转换器会生成包含 types: 映射的 #%RAML 1.0 Library。完整的 RAML API 资源／方法转换明确不在范围内。
• Avro 记录会转换为 RAML object 类型；可空字段会以 name? 可选属性形式输出；枚举转换为 enum:；数组转换为 T[]；映射使用 properties: { "//": T }；联合类型转换为 A | B。
• Avro 逻辑类型会反向映射为 RAML date-only、time-only 或 datetime。反向转换时，无法区分 datetime-only 和 Avro 时间戳逻辑类型。

将 JSON 架构转换为 Avrotize Schema

avrotize j2a <path_to_json_schema_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>] [--split-top-level-records]

参数：

• <path_to_json_schema_file>：要转换的 JSON 架构文件路径。如果省略，则从标准输入读取文件。
• --out：要写入转换结果的 Avrotize Schema 文件路径。如果省略，则将输出写入标准输出。
• --namespace：（可选）如果 JSON 架构未定义命名空间，则在 Avrotize Schema 中使用的命名空间。
• --split-top-level-records：（可选）将顶层记录拆分到单独的文件中。

转换说明：

• Avrotize 中的 JSON Schema 处理

将 Avrotize Schema 转换为 JSON 架构

avrotize a2j <path_to_avro_schema_file> [--out <path_to_json_schema_file>] [--naming <naming_mode>]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从标准输入读取文件。
• --out：要写入转换结果的 JSON 架构文件路径。如果省略，则将输出写入标准输出。
• --naming：（可选）类型命名约定。可选值为 snake、camel、pascal、default。

转换说明：

• Avrotize 中的 JSON Schema 处理

将 XML 架构（XSD）转换为 Avrotize Schema

avrotize x2a <path_to_xsd_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>]

参数：

• <path_to_xsd_file>：要转换的 XML 架构文件路径。如果省略，则从标准输入读取文件。
• --out：要写入转换结果的 Avrotize Schema 文件路径。如果省略，则将输出写入标准输出。
• --namespace：（可选）如果 XML 架构未定义命名空间，则在 Avrotize Schema 中使用的命名空间。

转换说明：

• 所有 XML 架构结构都会映射为带字段的 Avro 记录类型，其中元素和属性都会成为记录中的字段。因此，XML 会被扁平化为字段，这一结构特征不会保留。
• Avro 不支持 xsd:any，因为 Avro 不支持任意类型，并且必须始终使用命名类型。该工具会将 xsd:any 映射为一个名为 any 的字段，其类型为联合类型，允许标量值或两层数组和／或映射嵌套。
• 定义枚举的 simpleType 声明会映射为 Avro enum 类型。其他所有 facet 都会被忽略，简单类型会映射为相应的 Avro 类型。
• 具有简单内容且在基础类型上扩展了属性的 complexType 声明会映射为 Avro 记录类型。复杂类型上定义的其他 facet 都会被忽略。
• 如果架构定义了单个根元素，该工具会输出单个 Avro 记录类型。如果架构定义了多个根元素，该工具会输出记录类型的联合类型，每个类型对应一个根元素。
• 生成的 Avrotize Schema 中的所有字段都会带有 xmlkind 扩展属性，用于标示该字段在 XML 架构中是 element 还是 attribute。

将 Avrotize Schema 转换为 XML schema

avrotize a2x <path_to_avro_schema_file> [--out <path_to_xsd_schema_file>] [--namespace <target_namespace>]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从 stdin 读取文件。
• --out：用于写入转换结果的 XML schema 文件路径。如果省略，则将输出发送到 stdout。
• --namespace：（可选）XSD schema 的目标命名空间。

转换说明：

• Avro record 类型会映射为包含元素的 XML Schema 复杂类型。
• Avro enum 类型会映射为带限制的 XML Schema 简单类型。
• 在需要时，Avro 逻辑类型会映射为带限制的 XML Schema 简单类型。
• 如果所有联合类型都是基本类型，则 Avro union 会映射为带 union 限制的独立 XSD 简单类型定义。
• 包含复杂类型的 Avro union 会解析为每个选项各自的类型，然后

再通过 choice 将它们组合起来。

将 JSON Structure 转换为 XML Schema（XSD）

avrotize s2x <path_to_structure_file> [--out <path_to_xsd_schema_file>] [--namespace <target_namespace>]

参数：

• <path_to_structure_file>：要转换的 JSON Structure schema 文件路径。如果省略，则从 stdin 读取文件。
• --out：用于写入转换结果的 XML schema 文件路径。如果省略，则将输出发送到 stdout。
• --namespace：（可选）XSD schema 的目标命名空间。

转换说明：

• JSON Structure 对象类型会映射为包含元素的 XML Schema 复杂类型。
• JSON Structure 基本类型（string、int8-128、uint8-128、float/double、boolean 等）会映射为相应的 XSD 简单类型。
• 扩展基本类型映射如下：
  • binary/bytes → xs:base64Binary
  • date → xs:date
  • time → xs:time
  • datetime/timestamp → xs:dateTime
  • duration → xs:duration
  • uuid → xs:string
  • uri → xs:anyURI
  • decimal → xs:decimal
• 集合类型：
  • array 和 set → 包含条目序列的复杂类型
  • map → 包含键和值的条目元素的复杂类型
  • tuple → 包含固定序列、且条目具有类型的复杂类型
• 联合类型（choice 或 ["string", "null"] 这类类型数组）：
  • 带标记的联合（含判别符）→ xs:choice 元素
  • 内联联合 → 抽象基类型及其具体扩展类型
  • 可空类型 → 带有 minOccurs="0" 的元素
• 类型引用（$ref）会解析为命名的 XSD 类型
• 类型扩展（$extends）会映射为使用 xs:complexContent 的 XSD 复杂类型扩展
• 抽象类型在 XSD 中标记为 abstract="true"
• 验证约束（minLength、maxLength、pattern、minimum、maximum）会转换为 XSD 限制/方面
• 必需属性会成为带有 minOccurs="1" 的元素，可选属性的 minOccurs="0"

将 ASN.1 架构转换为 Avrotize 架构

avrotize asn2a <path_to_asn1_schema_file>[,<path_to_asn1_schema_file>,...] [--out <path_to_avro_schema_file>]

参数：

• <path_to_asn1_schema_file>：要转换的 ASN.1 架构文件的路径。工具支持以逗号分隔的多个文件列表。如果省略，则从 stdin 读取文件。
• --out：用于写入转换结果的 Avrotize 架构文件路径。如果省略，则将输出发送到 stdout。

转换说明：

• 所有 ASN.1 类型都会映射为 Avro record 类型、枚举和联合类型。Avro 不支持与 ASN.1 相同级别的类型嵌套，工具会将类型映射为最合适的类型。
• 工具会将以下 ASN.1 类型映射为 Avro 类型：
  • SEQUENCE 和 SET 映射为 Avro record 类型。
  • CHOICE 映射为所有字段均为可选的 Avro record 类型。虽然 CHOICE 类型在技术上对应 Avro 联合类型，但 ASN.1 类型的每个选项都有不同的命名字段，而 Avro 联合类型不支持此特性。
  • OBJECT IDENTIFIER 映射为 Avro string 类型。
  • ENUMERATED 映射为 Avro enum 类型。
  • SEQUENCE OF 和 SET OF 映射为 Avro array 类型。
  • BIT STRING 映射为 Avro bytes 类型。
  • OCTET STRING 映射为 Avro bytes 类型。
  • INTEGER 映射为 Avro long 类型。
  • REAL 映射为 Avro double 类型。
  • BOOLEAN 映射为 Avro boolean 类型。
  • NULL 映射为 Avro null 类型。
  • UTF8String、PrintableString、IA5String、BMPString、NumericString、TeletexString、VideotexString、GraphicString、VisibleString、GeneralString、UniversalString、CharacterString、T61String 均映射为 Avro string 类型。
  • 所有其他 ASN.1 类型均映射为 Avro string 类型。
• 解析 ASN.1 架构文件的能力有限，工具可能无法解析所有 ASN.1 文件。该工具基于 Python asn1tools 包，其能力也受该包的限制。

将 Kusto 表定义转换为 Avrotize Schema

avrotize k2a --kusto-uri <kusto_cluster_uri> --kusto-database <kusto_database> [--out <path_to_avro_schema_file>] [--emit-cloudevents-xregistry]

参数：

• --kusto-uri：要连接的 Kusto 群集的 URI。
• --kusto-database：要从中读取表定义的 Kusto 数据库名称。
• --out：用于写入转换结果的 Avrotize Schema 文件路径。如果省略，则将输出发送到标准输出。
• --emit-cloudevents-xregistry：（可选）请参阅下文的说明。

转换说明：

• 该工具会直接连接到 Kusto 群集，并从指定数据库读取表定义。该工具会将数据库中的所有表转换为 Avro record 类型，并在顶层类型联合中返回。
• 连接到 Kusto 群集时，会使用与 Azure CLI 相同的身份验证机制。如果已安装并完成身份验证，该工具会使用与 Azure CLI 相同的身份验证上下文。
• 该工具会将 Kusto 列类型映射为以下 Avro 类型：
  • bool 映射为 Avro boolean 类型。
  • datetime 映射为带有逻辑类型 timestamp-millis 的 Avro long 类型。
  • decimal 映射为逻辑 Avro 类型，其 logicalType 设置为 decimal，precision 和 scale 设置为 Kusto 中 decimal 类型对应的值。
  • guid 映射为 Avro string 类型。
  • int 映射为 Avro int 类型。
  • long 映射为 Avro long 类型。
  • real 映射为 Avro double 类型。
  • string 映射为 Avro string 类型。
  • timespan 映射为逻辑 Avro 类型，其 logicalType 设置为 duration。
• 对于 dynamic 列，该工具会对表中的数据进行抽样，以确定动态列的结构。该工具会将动态列映射为 Avro record 类型，其字段对应于动态列中发现的字段。如果动态列包含嵌套的动态列，该工具会递归地将其映射为 Avro record 类型。如果在动态列中发现结构冲突的记录，该工具会为动态列生成 record 类型联合。
• 如果设置了 --emit-cloudevents-xregistry 选项，该工具会生成一个 xRegistry 注册表清单文件，其中为 Kusto 数据库中的每个表定义一个 CloudEvent 消息，并在嵌入式 Schema 注册表中为每个表生成单独的 Avro Schema。如果发现一个或多个表包含 CloudEvent 数据（由 CloudEvents 属性列的存在来表明），该工具会检查 type（或 __type 或 __type）列的内容，以确定表中存储了哪些 CloudEvent 类型，并为每个唯一类型生成 CloudEvent 定义和 Schema。

将 Kusto 表定义转换为 JSON Structure

avrotize k2s [<path_to_kusto_file>] [--out <path_to_structure_file>] [--kusto-uri <kusto_cluster_uri>] [--kusto-database <kusto_database>] [--table-name <table_name>]

该命令接受 Kusto 定义文件，或实时 Kusto 群集和数据库。它可以对 dynamic 列进行抽样，以推断嵌套结构、选项和枚举。使用 --emit-cloudevents 可添加 CloudEvents 声明，或使用 --emit-xregistry 生成 xRegistry 清单，而不是单个 JSON Structure Schema。

将 SQL 数据库架构转换为 Avrotize Schema

avrotize sql2a --connection-string <connection_string> [--username <user>] [--password <pass>] [--dialect <dialect>] [--database <database>] [--table-name <table>] [--out <path_to_avro_schema_file>] [--namespace <namespace>] [--infer-json] [--infer-xml] [--sample-size <n>] [--emit-cloudevents] [--emit-xregistry]

参数：

• --connection-string：数据库连接字符串。支持 SSL/TLS 和集成身份验证选项（请参阅下方示例）。
• --username：（可选）数据库用户名。覆盖连接字符串中的用户名。使用此参数可避免凭据出现在命令历史记录中。
• --password：（可选）数据库密码。覆盖连接字符串中的密码。使用此参数可避免凭据出现在命令历史记录中。
• --dialect：（可选）SQL 方言：postgres（默认）、mysql、sqlserver、oracle 或 sqlite。
• --database：（可选）如果连接字符串中未指定，则填写数据库名称。
• --table-name：（可选）要转换的特定表。如果省略，则转换所有表。
• --out：Avrotize Schema 文件的路径。如果省略，则将输出写入标准输出。
• --namespace：（可选）生成架构的 Avro 命名空间。
• --infer-json：（可选，默认值：true）通过采样数据推断 JSON/JSONB 列的架构。
• --infer-xml：（可选，默认值：true）通过采样数据推断 XML 列的架构。
• --sample-size：（可选，默认值：100）用于推断 JSON/XML 架构的采样行数。
• --emit-cloudevents：（可选）检测 CloudEvents 表并生成 CloudEvents 声明。
• --emit-xregistry：（可选）生成 xRegistry 清单，而不是单个架构文件。

连接字符串示例：

# PostgreSQL with separate credentials (preferred for security)
avrotize sql2a --connection-string "postgresql://host:5432/mydb?sslmode=require" --username myuser --password mypass --out schema.avsc

# PostgreSQL with SSL (credentials in URL)
avrotize sql2a --connection-string "postgresql://user:pass@host:5432/mydb?sslmode=require" --out schema.avsc

# MySQL with SSL
avrotize sql2a --connection-string "mysql://user:pass@host:3306/mydb?ssl=true" --dialect mysql --out schema.avsc

# SQL Server with Windows Authentication (omit user/password)
avrotize sql2a --connection-string "mssql://@host:1433/mydb" --dialect sqlserver --out schema.avsc

# SQL Server with TLS encryption
avrotize sql2a --connection-string "mssql://user:pass@host:1433/mydb?encrypt=true" --dialect sqlserver --out schema.avsc

# SQLite file
avrotize sql2a --connection-string "/path/to/database.db" --dialect sqlite --out schema.avsc

转换说明：

• 该工具会连接到实时数据库，并从信息架构或系统目录中读取架构。
• 各方言的类型映射：
  • PostgreSQL：所有标准类型，包括 uuid、jsonb、xml、数组和自定义类型。
  • MySQL：标准类型，包括 json、enum、set 和空间类型。
  • SQL Server：标准类型，包括 uniqueidentifier、xml、money 和 hierarchyid。
  • Oracle：标准类型，包括 number、clob、blob 和 Oracle 专有类型。
  • SQLite：根据声明的类型亲和性映射动态类型。
• 对于 JSON/JSONB 列（PostgreSQL、MySQL）和 XML 列，该工具会采样数据以推断结构。只出现在部分记录中的字段会合并处理。如果不同记录中的字段类型冲突，该工具会生成记录类型的联合。
• 对于键无法作为有效 Avro 标识符的列（UUID、URL、特殊字符），该工具会生成 map<string, T> 类型，而不是记录类型。
• 如果存在表和列注释，会将其保留为 Avro doc 属性。
• 主键列会在架构的 unique 属性中标记。

将 SurrealQL Schema 转换为 Avrotize Schema

avrotize surreal2a <path_to_surrealql_schema_file> [--out <path_to_avro_schema_file>] [--namespace <namespace>]

参数：

• <path_to_surrealql_schema_file>：包含 DEFINE TABLE 和 DEFINE FIELD 语句的 SurrealQL 架构文件。
• --out：Avrotize Schema 文件的路径。如果省略，则将输出写入标准输出。
• --namespace：（可选）生成记录的 Avro 命名空间。

转换说明：

• DEFINE TABLE <name> SCHEMAFULL|SCHEMALESS 会转换为名为 <name> 的 Avro 记录。
• address.city 等带点号的 SurrealDB 字段路径会转换为嵌套 Avro 记录；phones[*].number 等数组项路径会转换为嵌套记录数组。
• SurrealDB 标量类型映射如下：string -> Avro string，int -> long，float/number -> double，bool -> boolean，bytes -> bytes，datetime -> 携带 timestamp-millis 的 long，uuid -> 携带 uuid 的 string，decimal -> 携带 Avro decimal（precision 为 38，scale 为 9）的 bytes。
• option<T> 会转换为可空 Avro 联合类型 ['null', T]，默认值为 null。
• array<T> 和 set<T> 会转换为 Avro 数组。Avro 没有原生的集合语义，因此不会表示唯一性。
• duration 和 geometry 会表示为字符串。
• record<T> 引用会表示为字符串记录 ID，因为 Avro 记录引用用于建模嵌入式架构，而不是 SurrealDB 记录 ID 链接。

从 JSON 文件推断 Avro 架构

avrotize json2a <json_files...> [--out <path>] [--type-name <name>] [--namespace <namespace>] [--sample-size <n>] [--infer-choices] [--choice-depth <n>]

参数：

• <json_files...>：一个或多个要分析的 JSON 文件。支持 JSON 数组、单个对象和 JSONL（JSON Lines）格式。使用 @filelist.txt 从响应文件读取文件路径。
• --out：Avro 架构文件的路径。如果省略，则输出到标准输出。
• --type-name：（可选）根类型的名称（默认值："Document"）。
• --namespace：（可选）生成类型的 Avro 命名空间。
• --sample-size：（可选）要采样的最大记录数（0 = 全部，默认值：0）。
• --infer-choices：（可选）检测判别联合，并将其输出为带有判别字段默认值的 Avro 联合类型。
• --choice-depth：（可选）推断 choice 的最大嵌套深度（1 = 仅根级，2+ = 嵌套对象，默认值：1）。

示例：

# Infer schema from multiple JSON files
avrotize json2a data1.json data2.json --out schema.avsc --type-name Event --namespace com.example

# Infer schema from JSONL file with discriminated union detection
avrotize json2a events.jsonl --out events.avsc --type-name LogEntry --infer-choices

# Use response file for many input files
avrotize json2a @file_list.txt --out schema.avsc --infer-choices --choice-depth 2

从 JSON 文件推断 JSON Structure 架构

avrotize json2s <json_files...> [--out <path>] [--type-name <name>] [--base-id <uri>] [--sample-size <n>] [--infer-choices] [--choice-depth <n>] [--infer-enums]

参数：

• <json_files...>：一个或多个要分析的 JSON 文件。使用 @filelist.txt 从响应文件读取文件路径。
• --out：JSON Structure 架构文件的路径。如果省略，则输出到标准输出。
• --type-name：（可选）根类型的名称（默认值："Document"）。
• --base-id：（可选）生成 $id 的基础 URI（默认值："https://example.com/"）。
• --sample-size：（可选）要采样的最大记录数（0 = 全部，默认值：0）。
• --infer-choices：（可选）检测判别联合，并将其输出为带有判别字段默认值的 choice 类型。
• --choice-depth：（可选）推断 choice 的最大嵌套深度（1 = 仅根级，2+ = 嵌套对象，默认值：1）。
• --infer-enums：（可选）根据低基数的重复字符串值检测枚举类型。

推断器还会自动检测：

• 日期时间模式：ISO 8601 时间戳、日期和时间会分别标记为 datetime、date 或 time。
• 必填与可选字段：所有记录中都存在的字段会标记为必填；稀疏字段为可选。

示例：

# Basic inference
avrotize json2s data.json --out schema.jstruct.json --type-name Person --base-id https://myapi.example.com/schemas/

# Full inference with choices and enums
avrotize json2s events/*.json --out events.jstruct.json --type-name Event --infer-choices --choice-depth 2 --infer-enums

# Process many files via response file
avrotize json2s @file_list.txt --out schema.jstruct.json --infer-choices --infer-enums

从 XML 文件推断 Avro 架构

avrotize xml2a <xml_files...> [--out <path>] [--type-name <name>] [--namespace <namespace>] [--sample-size <n>]

参数：

• <xml_files...>：一个或多个要分析的 XML 文件。使用 @filelist.txt 从响应文件读取文件路径。
• --out：Avro 架构文件的路径。如果省略，则输出到标准输出。
• --type-name：（可选）根类型的名称（默认值："Document"）。
• --namespace：（可选）生成类型的 Avro 命名空间。
• --sample-size：（可选）要采样的最大文档数（0 = 全部，默认值：0）。

示例：

avrotize xml2a config.xml --out config.avsc --type-name Configuration --namespace com.example.config

从 XML 文件推断 JSON Structure 架构

avrotize xml2s <xml_files...> [--out <path>] [--type-name <name>] [--base-id <uri>] [--sample-size <n>]

参数：

• <xml_files...>：一个或多个要分析的 XML 文件。使用 @filelist.txt 从响应文件读取文件路径。
• --out：JSON Structure 架构文件的路径。如果省略，则输出到标准输出。
• --type-name：（可选）根类型的名称（默认值："Document"）。
• --base-id：（可选）生成 $id 的基础 URI（默认值："https://example.com/"）。
• --sample-size：（可选）要采样的最大文档数（0 = 全部，默认值：0）。

转换说明（适用于所有推断命令）：

• XML 属性会转换为以 @ 为前缀的字段（并规范化为有效标识符）。
• 混合内容元素中的文本内容会成为 #text 字段。
• 重复元素会推断为数组。
• 结构不同的多个文件会合并为统一架构。
• 稀疏数据（仅在部分记录中出现的字段）会合并到单一类型中。

将 Avrotize Schema 转换为 Kusto 表声明

avrotize a2k <path_to_avro_schema_file> [--out <path_to_kusto_kql_file>] [--record-type <record_type>] [--emit-cloudevents-columns] [--emit-cloudevents-dispatch]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Kusto KQL 文件路径。如果省略，则将输出写入标准输出。
• --record-type：（可选）要转换为 Kusto 表的 Avro 记录类型名称。
• --emit-cloudevents-columns：（可选）如果设置此选项，工具会向表中添加 CloudEvents 属性列：___id、___source、___subject、___type 和 ___time。
• --emit-cloudevents-dispatch：（可选）如果设置此选项，工具会在脚本或数据库中添加名为 _cloudevents_dispatch 的表，用作 CloudEvents 的数据摄取和分发表。该表包含 CloudEvents 核心属性列，以及用于存放 CloudEvents 数据的 data 列。对于 Avrotize Schema 中的每个表，工具都会创建一项更新策略，将 type 属性与 Avro 类型名称匹配的事件映射到相应的表。

转换说明：

• 只有 Avro record 类型可以映射为 Kusto 表。如果 Avrotize Schema 包含其他类型（如 enum 或 array），工具会忽略它们。
• Avrotize Schema 中只有第一个 record 类型会转换为 Kusto 表。如果 Avrotize Schema 包含其他 record 类型，工具会忽略它们。可以使用 --record-type 选项指定要转换的 record 类型。
• 记录的字段会映射为 Kusto 表中的列。记录、数组或映射类型的字段会映射为 Kusto 表中 dynamic 类型的列。

将 JSON Structure Schema 转换为 Kusto 表声明

avrotize s2k <path_to_structure_schema_file> [--out <path_to_kusto_kql_file>] [--record-type <record_type>] [--emit-cloudevents-columns] [--emit-cloudevents-dispatch]

参数：

• <path_to_structure_schema_file>：要转换的 JSON Structure Schema 文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Kusto KQL 文件路径。如果省略，则将输出写入标准输出。
• --record-type：（可选）要转换为 Kusto 表的记录类型名称。
• --emit-cloudevents-columns：（可选）如果设置此选项，工具会向表中添加 CloudEvents 属性列：___id、___source、___subject、___type 和 ___time。
• --emit-cloudevents-dispatch：（可选）如果设置此选项，工具会在脚本或数据库中添加名为 _cloudevents_dispatch 的表，用作 CloudEvents 的数据摄取和分发表。该表包含 CloudEvents 核心属性列，以及用于存放 CloudEvents 数据的 data 列。对于 JSON Structure Schema 中的每个表，工具都会创建一项更新策略，将 type 属性与类型名称匹配的事件映射到相应的表。

转换说明：

• 只有 JSON Structure object 类型可以映射为 Kusto 表。其他类型（如 enum、array、choice）无法直接转换为表。
• 工具会转换 Schema 中找到的第一个 object 类型，或使用通过 --record-type 指定的类型。
• 对象属性会映射为 Kusto 表中的列。复杂类型（对象、数组、映射、集合、元组、选择类型）会映射为 dynamic 类型的列。
• JSON Structure 基本类型会映射为相应的 Kusto 标量类型：
  • string、uri、jsonpointer → string
  • boolean → bool
  • integer、int8、uint8、int16、uint16、int32 → int
  • uint32、int64、uint64 → long
  • int128、uint128、decimal → decimal
  • number、float、double、float8、binary32、binary64 → real
  • date、datetime、timestamp → datetime
  • time、duration → timespan
  • uuid → guid
  • binary → dynamic

将 Avrotize Schema 转换为表格模型脚本语言（TMSL）

avrotize a2tsml <path_to_avro_schema_file> [--out <path_to_tmsl_file>] [--record-type <record_type>] [--database-name <database_name>] [--compatibility-level <level>] [--emit-cloudevents-columns]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件的路径。如果省略，则从 stdin 读取文件。
• --out：TMSL JSON 文件的路径。如果省略，则将输出定向到 stdout。
• --record-type：（可选）按简单名称或完全限定名称选择记录。如果省略，则将所有顶层记录作为表输出。
• --database-name：（可选）设置表格模型数据库名称。默认使用第一个选定的记录名称。
• --compatibility-level：（可选）设置表格模型兼容性级别。默认值为 1605。
• --emit-cloudevents-columns：（可选）向每个表添加可空的 ___type、___source、___id、___time 和 ___subject 列。

转换说明：

• 每个顶层 Avro 记录都会转换为一个 TMSL 表，每个字段都会转换为一列。
• Avro unique 元数据会将匹配的 TMSL 列标记为键。Avro foreignKeys 元数据会在引用的记录存在时转换为 TMSL 模型关系。
• 基本数值、布尔、字符串、二进制、十进制和时间类型会映射到相应的 TMSL 数据类型。记录、数组、映射和一般联合类型会映射为 variant。
• 结果是一个包含数据库和模型定义的 TMSL createOrReplace 命令。它定义语义模型结构，但不会创建数据源分区或加载数据。

将 JSON Structure 转换为表格模型脚本语言（TMSL）

avrotize s2tsml <path_to_structure_schema_file> [--out <path_to_tmsl_file>] [--record-type <record_type>] [--database-name <database_name>] [--compatibility-level <level>] [--emit-cloudevents-columns]

参数：

• <path_to_structure_schema_file>：要转换的 JSON Structure 架构文件的路径。如果省略，则从 stdin 读取文件。
• --out：TMSL JSON 文件的路径。如果省略，则将输出定向到 stdout。
• --record-type：（可选）选择要输出的对象类型。如果省略，则将所有转换后的顶层记录作为表输出。
• --database-name：（可选）设置表格模型数据库名称。默认使用第一个选定的类型名称。
• --compatibility-level：（可选）设置表格模型兼容性级别。默认值为 1605。
• --emit-cloudevents-columns：（可选）向每个表添加可空的 ___type、___source、___id、___time 和 ___subject 列。

转换说明：

• 转换器会先将 JSON Structure 映射为 Avrotize Schema，然后应用与 a2tsml 相同的表、列、键、关系和类型映射。
• 没有直接对应表格模型元素的 JSON Structure 功能（包括嵌套对象、集合和选项）会表示为 variant 列。
• 结果是一个包含数据库和模型定义的 TMSL createOrReplace 命令。它定义语义模型结构，但不会创建数据源分区或加载数据。

将 Avrotize Schema 转换为 SQL 架构

avrotize a2sql [input] --out <path_to_sql_script> --dialect <dialect>

参数：

• input：要转换的 Avrotize 架构文件的路径（如果省略，则从 stdin 读取）。
• --out：用于写入转换结果的 SQL 脚本文件路径。
• --dialect：要使用的 SQL 方言（数据库类型）。支持的方言包括：
  • mysql、mariadb、postgres、sqlserver、oracle、sqlite、bigquery、snowflake、redshift、db2
• --emit-cloudevents-columns：（可选）向 SQL 表添加 CloudEvents 列。

有关各 SQL 方言的详细转换规则和类型映射，请参阅 SQL 转换说明 文档。

将 Avrotize Schema 转换为 SurrealQL Schema

avrotize a2surreal <path_to_avro_schema_file> [--out <path_to_surrealql_schema_file>] [--record-type <record_type>]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件。
• --out：SurrealQL Schema 文件的路径。若省略，输出将写入标准输出。
• --record-type：（可选）仅转换指定的 Avro record。

转换说明：

• 每个 Avro record 都会转换为 DEFINE TABLE <name> SCHEMAFULL。
• 嵌套 Avro record 会以带点号的 SurrealDB 字段路径形式输出。
• Avro 数组会转换为 array<T>；record 数组会使用 [*] 项字段定义输出。
• 由 null 和一种类型组成的可空 Avro union 会转换为 option<T>。
• Avro 的 timestamp-millis、uuid 和 decimal 逻辑类型会分别转换为 datetime、uuid 和 decimal。

将 JSON Structure Schema 转换为 SQL Schema

avrotize s2sql [input] --out <path_to_sql_script> --dialect <dialect> [--emit-cloudevents-columns]

参数：

• input：要转换的 JSON Structure Schema 文件路径（若省略，则从标准输入读取）。
• --out：用于写入转换结果的 SQL 脚本文件路径。
• --dialect：目标 SQL 方言（数据库类型）。支持的方言包括：
  • mysql、mariadb、postgres、sqlserver、oracle、sqlite、bigquery、snowflake、redshift、db2
• --emit-cloudevents-columns：（可选）向 SQL 表添加 CloudEvents 列。

转换说明：

• 此工具会将 JSON Structure Schema 转换为适用于各种数据库方言的 SQL DDL 语句。
• JSON Structure 原始类型（string、int8-128、uint8-128、float、double、decimal、binary、date、datetime、uuid 等）会映射为各方言对应的 SQL 类型。
• 复合类型（array、set、map、object、choice、tuple）通常会映射为目标数据库中的 JSON/JSONB 列或等效类型。
• JSON Structure Schema 中的必需属性会转换为非空列，并用于主键。
• JSON Structure Schema 中的 namespace 和 name 属性用于构造表名。
• maxLength、precision 和 scale 等类型注解会保留在列注释中。

有关从 JSON Structure 转换时各 SQL 方言的详细转换规则和类型映射，请参阅 SQL 转换说明 文档。

将 Avrotize Schema 转换为 MongoDB Schema

avrotize a2mongo <path_to_avro_schema_file> [--out <path_to_mongodb_schema>] [--emit-cloudevents-columns]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。若省略，则从标准输入读取文件。
• --out：用于写入转换结果的 MongoDB Schema 文件路径。
• --emit-cloudevents-columns：（可选）如果设置此项，工具会向 MongoDB Schema 添加 CloudEvents 属性列。

转换说明：

• Avro record 类型的字段会映射为 MongoDB Schema 中的字段。record、数组或 map 类型的字段会映射为 object 类型的字段。
• 输出的 MongoDB Schema 文件为 JSON 文件，可与 MongoDB 的 mongoimport 工具配合使用，以创建具有指定 Schema 的集合。

以下是新增命令的“转换……”部分：

将 Avrotize Schema 转换为 Cassandra Schema

avrotize a2cassandra [input] --out <output_directory> [--emit-cloudevents-columns]

• input：Avrotize Schema 文件的路径（若省略，则从标准输入读取）。
• --out：Cassandra Schema 的输出路径（必需）。
• --emit-cloudevents-columns：向 Cassandra Schema 添加 CloudEvents 列（可选，默认值：false）。

有关 Cassandra 的详细转换说明，请参阅 NoSQL 转换说明。

将 JSON Structure Schema 转换为 Cassandra Schema

avrotize s2cassandra [input] --out <output_file> [--emit-cloudevents-columns]

参数：

• input：JSON Structure Schema 文件的路径（如果省略，则从 stdin 读取）。
• --out：Cassandra CQL Schema 文件的输出路径（必需）。
• --emit-cloudevents-columns：向 Cassandra Schema 添加 CloudEvents 列（可选，默认值：false）。

转换说明：

• 此工具会将 JSON Structure Schema 转换为 Cassandra CQL DDL 语句。
• JSON Structure 基本类型会映射为相应的 Cassandra 类型（int32 → int、string → text、uuid → uuid 等）。
• 必需属性用于构建表的 PRIMARY KEY。
• 复杂类型（array、map、object）会在 Cassandra 中存储为 text 列。

有关 Cassandra 的详细转换说明，请参阅 NoSQL 转换说明。

将 Avrotize Schema 转换为 DynamoDB Schema

avrotize a2dynamodb [input] --out <output_directory> [--emit-cloudevents-columns]

• input：Avrotize Schema 文件的路径（如果省略，则从 stdin 读取）。
• --out：DynamoDB Schema 的输出路径（必需）。
• --emit-cloudevents-columns：向 DynamoDB Schema 添加 CloudEvents 列（可选，默认值：false）。

有关 DynamoDB 的详细转换说明，请参阅 NoSQL 转换说明。

将 Avrotize Schema 转换为 Elasticsearch Schema

avrotize a2es [input] --out <output_directory> [--emit-cloudevents-columns]

• input：Avrotize Schema 文件的路径（如果省略，则从 stdin 读取）。
• --out：Elasticsearch Schema 的输出路径（必需）。
• --emit-cloudevents-columns：向 Elasticsearch Schema 添加 CloudEvents 列（可选，默认值：false）。

有关 Elasticsearch 的详细转换说明，请参阅 NoSQL 转换说明。

将 Avrotize Schema 转换为 CouchDB Schema

avrotize a2couchdb [input] --out <output_directory> [--emit-cloudevents-columns]

• input：Avrotize Schema 文件的路径（如果省略，则从 stdin 读取）。
• --out：CouchDB Schema 的输出路径（必需）。
• --emit-cloudevents-columns：向 CouchDB Schema 添加 CloudEvents 列（可选，默认值：false）。

有关 CouchDB 的详细转换说明，请参阅 NoSQL 转换说明。

将 Avrotize Schema 转换为 Neo4j Schema

avrotize a2neo4j [input] --out <output_directory> [--emit-cloudevents-columns]

• input：Avrotize Schema 文件的路径（如果省略，则从 stdin 读取）。
• --out：Neo4j Schema 的输出路径（必需）。
• --emit-cloudevents-columns：向 Neo4j Schema 添加 CloudEvents 列（可选，默认值：false）。

有关 Neo4j 的详细转换说明，请参阅 NoSQL 转换说明。

将 Avrotize Schema 转换为 Firebase Schema

avrotize a2firebase [input] --out <output_directory> [--emit-cloudevents-columns]

• input：Avrotize Schema 文件的路径（如果省略，则从 stdin 读取）。
• --out：Firebase Schema 的输出路径（必需）。
• --emit-cloudevents-columns：向 Firebase Schema 添加 CloudEvents 列（可选，默认值：false）。

有关 Firebase 的详细转换说明，请参阅 NoSQL 转换说明。

将 Avrotize Schema 转换为 CosmosDB Schema

avrotize a2cosmos [input] --out <output_directory> [--emit-cloudevents-columns]

• input：Avrotize Schema 文件的路径（如果省略，则从 stdin 读取）。
• --out：CosmosDB Schema 的输出路径（必需）。
• --emit-cloudevents-columns：向 CosmosDB Schema 添加 CloudEvents 列（可选，默认值：false）。

有关 CosmosDB 的详细转换说明，请参阅 NoSQL 转换说明。

将 Avrotize Schema 转换为 HBase Schema

avrotize a2hbase [input] --out <output_directory> [--emit-cloudevents-columns]

• input：Avrotize Schema 文件的路径（如果省略，则从 stdin 读取）。
• --out：HBase Schema 的输出路径（必需）。
• --emit-cloudevents-columns：向 HBase Schema 添加 CloudEvents 列（可选，默认值：false）。

有关 HBase 的详细转换说明，请参阅 NoSQL 转换说明。

将 Avrotize Schema 转换为空 Parquet 文件

avrotize a2pq <path_to_avro_schema_file> [--out <path_to_parquet_schema_file>] [--record-type <record-type-from-avro>] [--emit-cloudevents-columns]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Parquet schema 文件路径。如果省略，则将输出发送到标准输出。
• --record-type：（可选）要转换为 Parquet schema 的 Avro record 类型名称。
• --emit-cloudevents-columns：（可选）如果设置，工具会向 Parquet schema 添加 CloudEvents 属性列：__id、__source、__subject、__type 和 __time。

转换说明：

• 生成的 Parquet 文件仅包含 schema，不含数据行。
• 该工具仅支持为描述单个 record 类型的 Avrotize Schema 写入 Parquet 文件。如果 Avrotize Schema 包含顶层 union，则必须使用 --record-type 选项指定要生成的 record 类型。
• record 的字段会映射为 Parquet 文件中的列。数组和 record 字段会映射为 Parquet 嵌套类型。Avro 类型 union 会映射为结构，而不是 Parquet union，因为此处使用的 PyArrow 库不支持 Parquet union。

将 Avrotize Schema 转换为 Iceberg schema

avrotize a2ib <path_to_avro_schema_file> [--out <path_to_iceberg_schema_file>] [--record-type <record-type-from-avro>] [--emit-cloudevents-columns] [--format schema|arrow]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Iceberg schema 文件路径。如果省略，则将输出发送到标准输出。
• --record-type：（可选）要转换为 Iceberg schema 的 Avro record 类型名称。
• --emit-cloudevents-columns：（可选）如果设置，工具会向 Iceberg schema 添加 CloudEvents 属性列：__id、__source、__subject、__type 和 __time。
• --format：（可选）输出格式。schema（默认值）按照 Iceberg Table Spec Appendix C 输出 JSON。arrow 输出二进制 Arrow IPC 序列化 schema。

转换说明：

• 生成的 Iceberg 文件仅包含 schema，不含数据行。
• 该工具仅支持为描述单个 record 类型的 Avrotize Schema 写入 Iceberg 文件。如果 Avrotize Schema 包含顶层 union，则必须使用 --record-type 选项指定要生成的 record 类型。
• record 的字段会映射为 Iceberg 文件中的列。数组和 record 字段会映射为 Iceberg 嵌套类型。Avro 类型 union 会映射为结构，而不是 Iceberg union，因为此处使用的 PyArrow 库不支持 Iceberg union。

将 JSON Structure 转换为 Iceberg 架构

avrotize s2ib <path_to_structure_schema_file> [--out <path_to_iceberg_schema_file>] [--record-type <record-type-from-structure>] [--emit-cloudevents-columns] [--format schema|arrow]

参数：

• <path_to_structure_schema_file>：要转换的 JSON Structure 架构文件的路径。如果省略，则从 stdin 读取文件。
• --out：要写入转换结果的 Iceberg 架构文件的路径。如果省略，则将输出写入 stdout。
• --record-type：（可选）要转换为 Iceberg 架构的 definitions 中的记录类型名称。
• --emit-cloudevents-columns：（可选）如果设置，工具会将 CloudEvents 属性列添加到 Iceberg 架构中：___id、___source、___subject、___type 和 ___time。
• --format：（可选）输出格式。schema（默认值）根据 Iceberg 表规范附录 C 输出 JSON。arrow 输出二进制 Arrow IPC 序列化架构。

转换说明：

• 生成的 Iceberg 文件仅包含架构，不包含数据行。
• 该工具支持顶层类型为 type: "object" 的 JSON Structure 架构。如果架构包含 $ref，或记录类型位于 definitions 中，可以使用 --record-type 选项指定要生成的类型。
• JSON Structure 类型映射为 Iceberg 类型的方式如下：
  • 基本类型：string → StringType，boolean → BooleanType，数值类型（int8-128、uint8-128、float、double）→ 相应的 IntegerType/LongType/FloatType/DoubleType
  • 扩展类型：binary/bytes → BinaryType，date → DateType，time → TimeType，datetime/timestamp → TimestampType，duration → LongType（微秒），decimal → DecimalType（含精度/小数位数），uuid/uri/jsonpointer → StringType
  • 复合类型：object → StructType，array/set → ListType，map → MapType，tuple → 带索引字段的 StructType
  • 选择类型：映射为带有备选字段的 StructType（Iceberg 不支持原生联合类型）
• 适用时会保留 precision、scale 等类型注解和验证约束。
• 支持 $extends 特性——基类型的属性会包含在转换结果中。
• 必需和可选属性通过 Iceberg 的 required 字段标志处理。

将 JSON Structure 转换为空 Parquet 文件

avrotize s2pq <path_to_structure_schema_file> [--out <path_to_parquet_file>] [--record-type <record-type-from-structure>] [--emit-cloudevents-columns] [--format parquet|schema]

• <path_to_structure_schema_file>：要转换的 JSON Structure 架构文件的路径。若省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Parquet 文件路径。若省略，则将输出发送到标准输出。
• --record-type：（可选）要转换为 Parquet 架构的 definitions 中记录类型的名称。
• --emit-cloudevents-columns：（可选）若设置，工具会向 Parquet 架构添加 CloudEvents 属性列：___id、___source、___subject、___type 和 ___time。
• --format：（可选）输出格式。parquet（默认）会写入一个空 Parquet 文件，架构存储在文件尾部。schema 会将派生的架构以 JSON 格式写出，供检查。

说明：

• 生成的 Parquet 文件仅包含架构，不包含数据行。
• 该工具支持顶层 type: "object" 的 JSON Structure 架构。如果架构包含 $ref，或记录类型位于 definitions 中，可使用 --record-type 选项指定要生成的类型。
• JSON Structure 类型按以下方式映射为 Parquet（PyArrow）类型：
  • 原始类型：string → string，boolean → bool，定长整数类型（int8…int64、uint8…uint64）→ 对应的 PyArrow 整数类型，float/float32 → float32，double/float64 → float64，decimal → decimal128，并遵循 precision/scale，bytes/binary → binary，uuid/uri/jsonpointer → string。
  • 时间类型：date → date32，time → time64[us]，datetime/timestamp → timestamp[us]，duration → int64（微秒）。
  • 复合类型：object → struct，array/set → list，map → map，tuple → 带索引字段的 struct。没有属性的（开放式）object 会变为 map<string, string>。
  • 选择类型：映射为由可选分支组成的 struct（Parquet 没有原生联合类型）。
• 支持 $extends 功能；转换时会包含基类型的属性。
• 必需属性会生成为不可为空的列；其他属性均可为空。

将 JSON Type Definition（JTD）转换为 Avrotize Schema

avrotize jtd2a <path_to_jtd_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>]

参数：

• <path_to_jtd_file>：要转换的 JSON Type Definition 文件的路径。若省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Avrotize Schema 文件路径。若省略，则将输出发送到标准输出。
• --namespace：（可选）生成的 Avro 记录和枚举的命名空间。

转换说明：

• JTD type 形式映射为 Avro 原始类型；timestamp 编码为带有 logicalType: "timestamp-millis" 的 Avro long。
• 必要时，会将 JTD enum 符号转换为符合 Avro 规范的名称。原始 JTD 符号会保留在 jtdEnumSymbols 元数据中，以便往返转换。
• JTD properties 会变为必需的 Avro 记录字段。optionalProperties 会变为可空的 Avro 字段，并设为 default: null。
• JTD elements 和 values 会映射为 Avro 数组和映射。definitions/ref 会映射为具名 Avro 类型。
• JTD discriminator/mapping 会映射为由记录组成的 Avro 联合类型。每个分支都带有一个仅含单个符号的枚举字段作为判别符，并携带 jtdDiscriminator/jtdMappingKey 元数据以便往返转换。
• Avro 没有与 JTD additionalProperties 直接对应的类型；该设置会保留在 jtdAdditionalProperties 元数据中，但 Avro 不会对其进行强制约束。

将 Avrotize Schema 转换为 JSON Type Definition（JTD）

avrotize a2jtd <path_to_avro_schema_file> [--out <path_to_jtd_file>] [--record-type <record-type-from-avro>]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 JSON Type Definition 文件路径。如果省略，则将输出定向到标准输出。
• --record-type：（可选）当文件包含多个命名类型时，用作 JTD 根的 Avro 记录类型名称。

转换说明：

• Avro 基本类型会映射到最接近的 JTD type；存在 jtdType 等转换器元数据时，会用于还原范围更窄的 JTD 整数和浮点类型。
• 带有 logicalType: "timestamp-millis" 的 Avro long 会映射为 JTD timestamp。
• 可空的 Avro 联合类型会映射为 nullable: true；默认值为 null 的可空字段会映射为 JTD optionalProperties。
• 通用 Avro 联合类型没有原生的 JTD 等效项。只有由 jtd2a 输出的判别式联合类型可以往返转换为 JTD discriminator/mapping；其他联合类型会作为元数据保留。

将 JSON Type Definition（JTD）转换为 JSON Structure

avrotize jtd2s <path_to_jtd_file> [--out <path_to_structure_file>] [--namespace <avro_schema_namespace>]

参数：

• <path_to_jtd_file>：要转换的 JSON Type Definition 文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 JSON Structure 文件路径。如果省略，则将输出定向到标准输出。
• --namespace：（可选）为生成的中间 Avro 记录和枚举指定命名空间。

转换说明：

• 转换通过 Avrotize Schema 完成，因此也受 JTD 到 Avro 的限制影响。

将 JSON Structure 转换为 JSON Type Definition（JTD）

avrotize s2jtd <path_to_structure_file> [--out <path_to_jtd_file>] [--record-type <record-type-from-structure>]

参数：

• <path_to_structure_file>：要转换的 JSON Structure 文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 JSON Type Definition 文件路径。如果省略，则将输出定向到标准输出。
• --record-type：（可选）用作 JTD 根的 Structure/Avro 记录类型名称。

转换说明：

• 转换通过 Avrotize Schema 完成，因此没有 JTD 等效项的 JSON Structure 特性可能会被简化或作为元数据输出。

将 Parquet 架构转换为 Avrotize Schema

avrotize pq2a <path_to_parquet_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>]

参数：

• <path_to_parquet_file>：要转换的 Parquet 文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Avrotize Schema 文件路径。如果省略，则将输出定向到标准输出。
• --namespace：（可选）如果 Parquet 文件未定义命名空间，则为 Avrotize Schema 指定命名空间。

转换说明：

• 工具会从 Parquet 文件中读取架构并将其转换为 Avrotize Schema。Parquet 文件中的数据不会被读取或转换。
• Parquet 架构中的字段会映射为 Avrotize Schema 中的字段。嵌套字段会映射为 Avrotize Schema 中的嵌套记录。

将 CSV 文件转换为 Avrotize Schema

avrotize csv2a <path_to_csv_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>]

参数：

• <path_to_csv_file>：要转换的 CSV 文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Avrotize Schema 文件路径。如果省略，则将输出定向到标准输出。
• --namespace：（可选）如果 CSV 文件未定义命名空间，则为 Avrotize Schema 指定命名空间。

转换说明：

• 工具会读取 CSV 文件并将其转换为 Avrotize Schema。CSV 文件的第一行视为标题行，其中包含字段名称。
• CSV 文件中的字段会映射为 Avrotize Schema 中的字段。工具会根据 CSV 文件中的数据推断字段类型。

将 Kafka Connect Schema 转换为 Avrotize Schema

avrotize kstruct2a [input] --out <path_to_avro_schema_file>

参数：

• input：要转换的 Kafka Struct 文件路径（如果省略，则从标准输入读取）。
• --out：用于写入转换结果的 Avrotize Schema 文件路径。
• --kstruct：已弃用：Kafka Struct 文件路径（用于向后兼容）。

转换说明：

• 此工具会将 Kafka Struct 定义转换为 Avrotize Schema，并将 Kafka 数据类型映射为对应的 Avro 类型。
• Kafka Struct 通常用于定义 Kafka Connect 和其他基于 Kafka 的应用程序的数据结构。此命令可将这些定义转换为 Avro，便于与各种序列化和 Schema Registry 工具配合使用，从而实现互操作性。

将 Avrotize Schema 转换为 C# 类

avrotize a2cs <path_to_avro_schema_file> [--out <path_to_csharp_dir>] [--namespace <csharp_namespace>] [--avro-annotation] [--system_text_json_annotation] [--newtonsoft-json-annotation] [--pascal-properties] [--target-framework <tfm>]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入 C# 类的目录路径。必需。
• --namespace：（可选）C# 类使用的命名空间。
• --avro-annotation：（可选）使用 Avro 注解。
• --system_text_json_annotation：（可选）使用 System.Text.Json 注解。
• --newtonsoft-json-annotation：（可选）使用 Newtonsoft.Json 注解。
• --pascal-properties：（可选）使用 PascalCase 属性。
• --target-framework：（可选）生成的 .csproj 的目标框架（例如 net8.0，或用于多目标的 net8.0;net10.0）。默认为 net10.0。

转换说明：

• 此工具会根据 Avrotize Schema 生成 C# 类。Avrotize Schema 中的每种记录类型都会转换为一个 C# 类。
• 记录的字段会映射为 C# 类中的属性。嵌套记录会映射为 C# 类中的嵌套类。
• 此工具支持为 C# 类中的属性添加注解。--avro-annotation 选项会添加 Avro 注解，--system_text_json_annotation 选项会添加 System.Text.Json 注解，--newtonsoft-json-annotation 选项会添加 Newtonsoft.Json 注解。
• --pascal-properties 选项会将属性的命名约定改为 PascalCase。

将 Avrotize Schema 转换为 Java 类

avrotize a2java <path_to_avro_schema_file> [--out <path_to_java_dir>] [--package <java_package>] [--avro-annotation] [--jackson-annotation] [--pascal-properties]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入 Java 类的目录路径。必需。
• --package：（可选）Java 类使用的包。
• --avro-annotation：（可选）使用 Avro 注解。
• --jackson-annotation：（可选）使用 Jackson 注解。
• --pascal-properties：（可选）使用 PascalCase 属性。

转换说明：

• 此工具会根据 Avrotize Schema 生成 Java 类。Avrotize Schema 中的每种记录类型都会转换为一个 Java 类。
• 记录的字段会映射为 Java 类中的属性。嵌套记录会映射为 Java 类中的嵌套类。
• 此工具支持为 Java 类中的属性添加注解。--avro-annotation 选项会添加 Avro 注解，--jackson-annotation 选项会添加 Jackson 注解。
• --pascal-properties 选项会将属性的命名约定改为 PascalCase。

将 Avrotize Schema 转换为 Python 类

avrotize a2py <path_to_avro_schema_file> [--out <path_to_python_dir>] [--package <python_package>] [--dataclasses-json-annotation] [--avro-annotation]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从 stdin 读取文件。
• --out：用于写入 Python 类的目录路径。必需。
• --package：（可选）Python 类使用的包。
• --dataclasses-json-annotation：（可选）使用 dataclasses-json 注解。
• --avro-annotation：（可选）使用 Avro 注解。

转换说明：

• 此工具根据 Avrotize Schema 生成 Python 类。Avrotize Schema 中的每种记录类型都会转换为一个 Python 类。
• 记录的字段会映射为 Python 类中的属性。嵌套记录会映射为 Python 类中的嵌套类。
• 此工具支持为 Python 类中的属性添加注解。--dataclasses-json-annotation 选项会添加 dataclasses-json 注解，--avro-annotation 选项会添加 Avro 注解。

将 Avrotize Schema 转换为 TypeScript 类

avrotize a2ts <path_to_avro_schema_file> [--out <path_to_typescript_dir>] [--package <typescript_package>] [--avro-annotation] [--typedjson-annotation]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从 stdin 读取文件。
• --out：用于写入 TypeScript 类的目录路径。必需。
• --package：（可选）TypeScript 类使用的包。
• --avro-annotation：（可选）使用 Avro 注解。
• --typedjson-annotation：（可选）使用 TypedJSON 注解。

转换说明：

• 此工具根据 Avrotize Schema 生成 TypeScript 类。Avrotize Schema 中的每种记录类型都会转换为一个 TypeScript 类。
• 记录的字段会映射为 TypeScript 类中的属性。嵌套记录会映射为 TypeScript 类中的嵌套类。
• TypeScript 上下文关键字（如 type、namespace、module 和 readonly）用作字段名时会保留。
• 此工具支持为 TypeScript 类中的属性添加注解。--avro-annotation 选项会添加 Avro 注解，--typedjson-annotation 选项会添加 TypedJSON 注解。

将 JSON Structure 结构转换为 TypeScript 类

avrotize s2ts <path_to_structure_schema_file> [--out <path_to_typescript_dir>] [--package <typescript_package>] [--typedjson-annotation] [--avro-annotation]

参数：

• <path_to_structure_schema_file>：要转换的 JSON Structure schema 文件路径。如果省略，则从标准输入读取文件。
• --out：写入 TypeScript 类的目录路径。必填。
• --package：（可选）生成项目的 TypeScript 包名称。
• --typedjson-annotation：（可选）使用 TypedJSON 注解支持 JSON 序列化。
• --avro-annotation：（可选）添加 Avro 二进制序列化支持，并嵌入 Structure schema。

转换说明：

• 该工具根据 JSON Structure schema 生成 TypeScript 类。JSON Structure schema 中的每种对象类型都会转换为一个 TypeScript 类。
• 支持所有 JSON Structure Core 类型，包括：
  • 基本类型：string、number、boolean、null
  • 扩展类型：binary、int8-128、uint8-128、float8/float/double、decimal、date、datetime、time、duration、uuid、uri、jsonpointer
  • 复合类型：object、array、set、map、tuple、any、choice（联合类型）
• 支持 JSON Structure 的以下功能：
  • $ref 引用：解析类型引用并将其生成为独立类
  • $extends 继承：将基类属性包含在派生类中
  • $offers/$uses 插件：将插件属性合并到使用它们的类中
  • 抽象类型：在 TypeScript 中使用 abstract 关键字标记
  • 必填/可选属性：必填属性为非空类型，可选属性为可空类型
  • Choice 类型：转换为 TypeScript 联合类型
• 生成的项目包括：
  • src/ 目录中的 TypeScript 源文件
  • 带有依赖项的 package.json
  • 用于 TypeScript 编译的 tsconfig.json
  • .gitignore 文件
  • 用于导出所有生成类型的 index.ts
• TypeScript 代码可以使用 npm run build 编译（需先运行 npm install）
• 有关处理 JSON Structure 的详细信息，请参阅 jsonstructure.md

将 Avrotize Schema 转换为 JavaScript 类

avrotize a2js <path_to_avro_schema_file> [--out <path_to_javascript_dir>] [--package <javascript_package>] [--avro-annotation]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从标准输入读取文件。
• --out：写入 JavaScript 类的目录路径。必填。
• --package：（可选）JavaScript 类使用的包。
• --avro-annotation：（可选）使用 Avro 注解。

转换说明：

• 该工具根据 Avrotize Schema 生成 JavaScript 类。Avrotize Schema 中的每种记录类型都会转换为一个 JavaScript 类。
• 记录的字段会映射为 JavaScript 类中的属性。嵌套记录会映射为 JavaScript 类中的嵌套类。
• 该工具支持为 JavaScript 类中的属性添加注解。--avro-annotation 选项会添加 Avro 注解。

将 Avrotize Schema 转换为 C++ 类

avrotize a2cpp <path_to_avro_schema_file> [--out <path_to_cpp_dir>] [--namespace <cpp_namespace>] [--avro-annotation] [--json-annotation]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从标准输入读取文件。
• --out：写入 C++ 类的目录路径。必填。
• --namespace：（可选）C++ 类使用的命名空间。
• --avro-annotation：（可选）使用 Avro 注解。
• --json-annotation：（可选）使用 JSON 注解。
• --xml-annotation：（可选）使用 encoding/xml 标签和 XML 序列化。

转换说明：

• 该工具根据 Avrotize Schema 生成 C++ 类。Avrotize Schema 中的每种记录类型都会转换为一个 C++ 类。

• 记录的字段会映射为 C++ 类中的属性。嵌套记录会映射为 C++ 类中的嵌套类。

• 该工具支持为 C++ 类中的属性添加注解。--avro-annotation 选项会添加 Avro 注解，--json-annotation 选项会添加 JSON 注解，--xml-annotation 选项会添加 XML 注解。

将 Avrotize Schema 转换为 Go 类

avrotize a2go <path_to_avro_schema_file> [--out <path_to_go_dir>] [--package <go_package>] [--avro-annotation] [--json-annotation] [--xml-annotation] [--package-site <go_package_site>] [--package-username <go_package_username>]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从标准输入读取文件。
• --out：写入 Go 类的目录路径。必填。
• --package：（可选）Go 类中使用的包。
• --package-site：（可选）Go 类中使用的包站点。
• --package-username：（可选）Go 类中使用的包用户名。
• --avro-annotation：（可选）使用 Avro 注解。
• --json-annotation：（可选）使用 JSON 注解。

转换说明：

• 该工具根据 Avrotize Schema 生成 Go 类。Avrotize Schema 中的每种记录类型都会转换为一个 Go 类。
• 记录的字段会映射为 Go 类中的属性。嵌套记录会映射为 Go 类中的嵌套类。
• 该工具支持为 Go 类的属性添加注解。--avro-annotation 选项会添加 Avro 注解，--json-annotation 选项会添加 JSON 注解。

将 Avrotize Schema 转换为 Rust 类

avrotize a2rust <path_to_avro_schema_file> [--out <path_to_rust_dir>] [--package <rust_package>] [--avro-annotation] [--serde-annotation]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件路径。如果省略，则从标准输入读取文件。
• --out：写入 Rust 类的目录路径。必填。
• --package：（可选）Rust 类中使用的包。
• --avro-annotation：（可选）使用 Avro 注解。
• --serde-annotation：（可选）使用 Serde 注解。

转换说明：

• 该工具根据 Avrotize Schema 生成 Rust 类。Avrotize Schema 中的每种记录类型都会转换为一个 Rust 类。
• 记录的字段会映射为 Rust 类中的属性。嵌套记录会映射为 Rust 类中的嵌套类。
• 该工具支持为 Rust 类的属性添加注解。--avro-annotation 选项会添加 Avro 注解，--serde-annotation 选项会添加 Serde 注解。

将 JSON Structure 转换为 C++ 类

avrotize s2cpp <path_to_structure_file> --out <path_to_cpp_dir> [--namespace <cpp_namespace>] [--json-annotation]

参数：

• <path_to_structure_file>：要转换的 JSON Structure 架构文件路径。如果省略，则从标准输入读取文件。
• --out：写入 C++ 类的目录路径。必填。
• --namespace：（可选）C++ 类中使用的命名空间。
• --json-annotation：（可选）包含 JSON 序列化支持（默认值：true）。

转换说明：

• 该工具根据 JSON Structure 架构生成 C++ 类。JSON Structure 架构中的每种对象类型都会转换为一个 C++ 类。
• 对象的字段会映射为 C++ 类中的属性。嵌套对象会映射为嵌套类。
• 该工具支持所有 JSON Structure Core 类型，包括原始类型（string、number、boolean）、扩展类型（int8-128、uint8-128、float、double、decimal、binary、date、datetime、time、duration、uuid、uri）和复合类型（object、array、set、map、tuple、choice）。
• 支持 JSON Structure 特有的功能，包括 $ref 类型引用、命名空间、定义和容器类型别名。
• 生成的代码包含 CMake 构建文件和 vcpkg 依赖管理，便于集成。

将 JSON Structure 结构转换为 Rust 类

avrotize s2rust <path_to_structure_schema_file> [--out <path_to_rust_dir>] [--package <rust_package>] [--json-annotation]

参数：

• <path_to_structure_schema_file>：要转换的 JSON Structure 架构文件的路径。如果省略，则从标准输入读取文件。
• --out：写入 Rust 类的目录路径。必填。
• --package：（可选）Rust 类使用的包名。
• --json-annotation：（可选）使用 Serde JSON 注解支持序列化。

转换说明：

• 此工具根据 JSON Structure 架构生成 Rust 结构体和枚举。JSON Structure 架构中的每种对象类型都会转换为 Rust 结构体。
• 对象的字段会映射为具有相应 Rust 类型的结构体字段。嵌套对象会映射为嵌套结构体。
• 支持所有 JSON Structure Core 类型：
  • 原始类型：string、number、boolean、null
  • 扩展类型：binary、int8-128、uint8-128、float8/float/double、decimal、date、datetime、time、duration、uuid、uri、jsonpointer
  • 复合类型：object、array、set、map、tuple、any、choice（带判别的联合类型）
• 支持 JSON Structure 特有的功能：
  • 命名空间和定义
  • 类型引用（$ref）
  • 必填和可选属性
  • 抽象类型
  • 扩展（$extends）
• --json-annotation 选项会添加 Serde derive 宏，以支持 JSON 序列化和反序列化。
• 生成的代码包含嵌入式单元测试，用于验证结构体创建和序列化（启用注解时）。

将 JSON Structure 结构转换为 Go 类

avrotize s2go <path_to_structure_file> --out <path_to_go_dir> [--package <go_package>] [--json-annotation] [--avro-annotation] [--xml-annotation] [--package-site <package_site>] [--package-username <username>]

参数：

• <path_to_structure_file>：要转换的 JSON Structure 架构文件的路径。如果省略，则从标准输入读取文件。
• --out：写入 Go 结构体的目录路径。必填。
• --package：（可选）Go 代码使用的包名。
• --json-annotation：（可选）为 encoding/json 添加 JSON 结构体标签。
• --xml-annotation：（可选）添加 encoding/xml 标签和 XML 序列化。
• --avro-annotation：（可选）添加 Avro 结构体标签。
• --package-site：（可选）Go 模块的包站点（例如，github.com）。
• --package-username：（可选）Go 模块的用户名/组织名。

转换说明：

• 此工具根据 JSON Structure 架构生成 Go 结构体。每种对象类型都会转换为 Go 结构体。
• JSON Structure 原始类型会映射为 Go 类型。date、time、datetime 等扩展类型会映射为 time.Time。
• 整数类型（int8、int16、int32、int64、uint8 等）会映射为相应的 Go 整数类型。
• Choice 类型会生成为 interface{} 类型，以提高灵活性。
• 此工具会生成完整的 Go 模块，包括 go.mod 文件、结构体定义、辅助函数和单元测试。
• 启用注解后，生成的代码会包含用于 JSON 序列化/反序列化的方法。

将 JSON Structure 转换为 Java 类

avrotize s2java <path_to_structure_schema_file> [--out <path_to_java_dir>] [--package <java_package>] [--jackson-annotation] [--pascal-properties]

参数：

• <path_to_structure_schema_file>：要转换的 JSON Structure 架构文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入 Java 类的目录路径。必填。
• --package：（可选）生成类的 Java 包名。
• --jackson-annotation：（可选）使用 Jackson 注解进行 JSON 序列化（默认值：true）。
• --pascal-properties：（可选）使用 PascalCase 作为属性名称。

转换说明：

• 该工具会根据 JSON Structure 架构生成 Java 类。每种对象类型都会转换为一个带有 getter/setter 方法的 Java 类。
• JSON Structure 基本类型会映射为 Java 类型。date、time、datetime 等扩展类型会映射为 LocalDate、LocalTime、Instant。
• 整数类型（int8-int64、uint8-uint64）会映射为对应的 Java 类型。uint64 使用 BigInteger 以支持完整取值范围。
• Choice 类型（带判别字段的联合类型）使用 Jackson 多态机制，并通过 @JsonTypeInfo 和 @JsonSubTypes 注解实现。
• Tuple 类型会使用 @JsonFormat(shape = Shape.ARRAY) 序列化为 JSON 数组。
• 该工具会生成一个包含 Jackson 依赖项的完整 Maven 项目，其中包括 pom.xml。
• 生成的类包含 equals() 和 hashCode() 实现。

将 JSON Structure 转换为 JavaScript 类

avrotize s2js <path_to_structure_schema_file> [--out <path_to_js_dir>] [--package <package_name>] [--avro-annotation]

参数：

• <path_to_structure_schema_file>：要转换的 JSON Structure 架构文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入 JavaScript 类的目录路径。必填。
• --package：（可选）生成类的包名。
• --avro-annotation：（可选）添加 Avro 二进制序列化支持。

转换说明：

• 该工具会根据 JSON Structure 架构生成支持完整类型的 JavaScript ES6 类。
• JSON Structure 基本类型会映射为 JavaScript 类型。date、time、datetime 等扩展类型会作为 Date 对象或字符串处理。
• 整数类型会根据大小映射为 JavaScript Number 或 BigInt。
• Choice 类型会生成为联合类型类，并提供工厂方法。
• Tuple 类型会生成为固定长度的数组。
• 该工具会生成一个包含 package.json 的完整 npm 包。
• 生成的类包含序列化/反序列化方法；启用 Avro 支持时，还会包含可选的 Avro 支持。

将 Avrotize 架构转换为 Datapackage 架构

avrotize a2dp <path_to_avro_schema_file> [--out <path_to_datapackage_file>] [--record-type <record-type-from-avro>]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize 架构文件路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Datapackage 架构文件路径。如果省略，则将输出写入标准输出。
• --record-type：（可选）要转换为 Datapackage 架构的 Avro 记录类型名称。

转换说明：

• 该工具会根据 Avrotize 架构生成 Datapackage 架构。Avrotize 架构中的每种记录类型都会转换为一个 Datapackage 资源。
• 记录的字段会映射为 Datapackage 资源中的字段。嵌套记录会映射为 Datapackage 中的嵌套资源。

将 JSON Structure 模式转换为 Datapackage 模式

avrotize s2dp <path_to_structure_schema_file> [--out <path_to_datapackage_file>] [--record-type <record-type-from-structure>]

参数：

• <path_to_structure_schema_file>：要转换的 JSON Structure 模式文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Datapackage 模式文件的路径。如果省略，则将输出写入标准输出。
• --record-type：（可选）要转换为 Datapackage 模式的 JSON Structure 记录类型名称。

转换说明：

• 该工具根据 JSON Structure 模式生成 Datapackage 模式。JSON Structure 模式中的每种对象类型都会转换为一个 Datapackage 资源。
• 对象的属性会映射为 Datapackage 资源模式中的字段。
• 支持所有 JSON Structure Core 类型，包括：
  • JSON 基本类型（string、number、boolean、null）
  • 扩展基本类型（int8-128、uint8-128、float/double、decimal、binary、date、datetime、time、duration、uuid、uri、jsonpointer）
  • 复合类型（object、array、set、map、tuple、choice/union）
• 保留 JSON Structure 特有功能：
  • 使用命名空间组织资源
  • 解析类型引用（$ref）
  • 将类型注解（maxLength、minLength、pattern、minimum、maximum、enum）转换为 Data Package 字段约束
  • 正确处理联合类型（可空字段）

将 Avrotize Schema 转换为 Markdown 文档

avrotize a2md <path_to_avro_schema_file> [--out <path_to_markdown_file>]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Markdown 文件的路径。如果省略，则将输出写入标准输出。

转换说明：

• 该工具根据 Avrotize Schema 生成 Markdown 文档。Avrotize Schema 中的每种记录类型都会转换为一个 Markdown 章节。
• 记录的字段会以表格形式记录在 Markdown 章节中。嵌套记录会在 Markdown 文件的嵌套章节中记录。

将 JSON Structure 模式转换为 Markdown 文档

avrotize s2md <path_to_structure_schema_file> [--out <path_to_markdown_file>]

参数：

• <path_to_structure_schema_file>：要转换的 JSON Structure 模式文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 Markdown 文件的路径。如果省略，则将输出写入标准输出。

转换说明：

• 该工具根据 JSON Structure Core 模式生成 Markdown 文档，遵循 Avrotize Schema 转 Markdown 转换器确立的模式。
• 支持所有 JSON Structure Core 类型，包括：
  • JSON 基本类型：string、number、boolean、null
  • 扩展基本类型：binary、int8-128、uint8-128、float8/float/double、decimal、date、datetime、time、duration、uuid、uri、jsonpointer
  • 复合类型：object、array、set、map、tuple、any、choice（包括带标签和内联联合类型）
• 支持 JSON Structure Core 功能：
  • 在单独的章节中记录命名空间和定义
  • 将类型引用（$ref）转换为 Markdown 链接
  • 清楚标记扩展（$extends）和抽象类型
  • 标明必需属性和可选属性
• 扩展功能（模式中存在时）：
  • 在属性旁记录验证约束（minLength、maxLength、minimum、maximum、pattern 等）
  • 记录类型专属注解（例如 decimal 的 precision、scale，以及数组的 minItems/maxItems 等）
• 模式中的每种对象类型都会转换为一个 Markdown 章节，并以结构化列表的形式记录其属性。
• choice 类型（联合类型）会记录其选择器（如有）和可用选项。
• 定义章节会记录所有可复用的类型定义。

将 JSON Structure 转换为 CSV Schema

avrotize s2csv <path_to_structure_schema_file> [--out <path_to_csv_schema_file>]

参数：

• <path_to_structure_schema_file>：要转换的 JSON Structure 架构文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 CSV 架构文件路径。如果省略，则将输出定向到标准输出。

转换说明：

• 该工具可将 JSON Structure 架构转换为 CSV Schema 格式。
• 支持所有 JSON Structure Core 类型，包括基本类型（string、number、boolean、null、integer）、扩展类型（int8-128、uint8-128、float/double、decimal、date、datetime、time、duration、uuid、uri、binary）和复合类型（object、array、set、map、tuple、choice）。
• 复合类型（数组、对象、映射）在 CSV 架构中表示为字符串，因为 CSV 格式不原生支持复杂的嵌套结构。
• 使用 nullable 标志保留必需/可选属性。
• 在 CSV 架构中保留验证约束（maxLength、minLength、pattern、minimum、maximum、precision、scale）。
• 支持并在输出中保留 enum 和 const 关键字。
• 转换过程中会解析 JSON Structure 特有的功能，例如 $ref、$extends、definitions 和 namespaces。

将 Avrotize 架构转换为 CSV Schema

avrotize a2csv <path_to_avro_schema_file> [--out <path_to_csv_schema_file>]

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize 架构文件的路径。如果省略，则从标准输入读取文件。
• --out：用于写入转换结果的 CSV 架构文件路径。如果省略，则将输出定向到标准输出。

转换说明：

• 该工具可将 Avrotize 架构转换为 CSV Schema 格式。
• Avro 基本类型（string、int、long、float、double、boolean、bytes）会映射为相应的 CSV 架构类型。
• 在输出中保留 Avro 逻辑类型（date、timestamp-millis、decimal、uuid）。
• 复杂类型（record、array、map）在 CSV 架构中表示为字符串，因为 CSV 格式不原生支持嵌套结构。
• 只能将单一 record 类型转换为 CSV 架构。

将 RAML 数据类型转换为 JSON Structure

avrotize raml2s <path_to_raml_file> [--out <path_to_json_structure_file>] [--namespace <avro_schema_namespace>]

通过 Avrotize Schema 桥接，将 RAML 1.0 数据类型转换为 JSON Structure。适用相同的 RAML 第一阶段限制：仅处理内联的 types: 数据类型；API 资源、方法、traits、resourceTypes、securitySchemes、annotations，以及外部 !include 展开均不在处理范围内。

将 JSON Structure 转换为 RAML 数据类型

avrotize s2raml <path_to_json_structure_file> [--out <path_to_raml_file>] [--namespace <namespace_to_strip>]

通过 Avrotize Schema 桥接，将 JSON Structure 转换为 RAML 1.0 库。输出仅包含 RAML 数据类型，不会生成 API 资源或方法。

将 JSON Structure 转换为 Protocol Buffers

avrotize s2p <path_to_json_structure_file> --out <path_to_proto_directory> [--naming-mode <naming_mode>] [--allow-optional]

参数：

• <path_to_json_structure_file>：要转换的 JSON Structure 架构文件的路径。如果省略，则从 stdin 读取文件。
• --out：用于写入转换结果的 Protocol Buffers 架构目录路径。此参数为必填项，因为 proto 文件必须写入目录。
• --naming-mode：（可选）类型命名约定。可选值为 snake、camel、pascal。默认为 pascal。
• --allow-optional：（可选）启用对可空字段使用 'optional' 关键字的支持（proto3）。

转换说明：

• 此工具可将 JSON Structure 架构直接转换为 Protocol Buffers .proto 文件，无需经过 Avrotize Schema。
• JSON Structure 的原始类型（string、number、boolean、null）和扩展类型（int8-128、uint8-128、float32/64、decimal、date、datetime、time、duration、uuid、uri）会映射为相应的 Protocol Buffers 类型。
• 复合类型（object、array、set、map、tuple、choice）会转换为 Protocol Buffers 消息、重复字段、映射字段和 oneof 结构。
• JSON Structure 命名空间会解析为不同的 proto 包定义。
• 类型引用（$ref）会解析并转换为相应的消息类型。
• Choice 类型（联合类型）会转换为 Protocol Buffers oneof 结构。
• 抽象类型和扩展（$extends）通过生成相应的消息层次结构来处理。

将 Smithy IDL 数据形状转换为 JSON Structure

avrotize smithy2s <path_to_smithy_file> [--out <path_to_json_structure_file>] [--namespace <avro_schema_namespace>]

此命令通过 Avrotize Schema 桥接，将 Smithy 2.0 IDL 数据形状转换为 JSON Structure。它的 Smithy 第一阶段范围和限制与 smithy2a 相同：服务、操作、资源和协议建模不在范围内，会被跳过。

将 JSON Structure 转换为 Smithy IDL 数据形状

avrotize s2smithy <path_to_json_structure_file> [--out <path_to_smithy_file>] [--namespace <smithy_namespace>]

此命令通过 Avrotize Schema 桥接，将 JSON Structure 转换为 Smithy 2.0 IDL 数据形状。它只输出数据形状；Smithy 服务和操作建模明确不属于第一阶段的范围。

将 OpenAPI 转换为 JSON Structure

avrotize oas2s <path_to_openapi_file> --out <path_to_json_structure_file> [--namespace <namespace>] [--preserve-composition] [--detect-discriminators] [--lift-inline-schemas]

参数：

• <path_to_openapi_file>：OpenAPI 3.x 文档（JSON 或 YAML）的路径。如果省略，则从 stdin 读取文件。
• --out：用于写入转换结果的 JSON Structure 架构文件路径。如果省略，则将结果写入 stdout。
• --namespace：（可选）JSON Structure 架构的命名空间。
• --preserve-composition：（可选）保留组合关键字（allOf、oneOf、anyOf）。默认为 true。
• --detect-discriminators：（可选）检测 OpenAPI 判别器模式并转换为 choice 类型。默认为 true。
• --lift-inline-schemas：（可选）将路径/操作中的内联架构提升为具名定义。默认为 false。

转换说明：

• 此工具会从 OpenAPI 文档的 components.schemas 中提取架构定义，并将其转换为 JSON Structure 格式。
• OpenAPI 专用关键字的处理方式如下：
  • nullable：转换为包含 null 的类型联合
  • readOnly、writeOnly、deprecated：映射为元数据注解
  • discriminator：用于创建带有适当判别器映射的 choice 类型
• OpenAPI $ref 引用（例如，#/components/schemas/Pet）会转换为 JSON Structure 引用（#/definitions/Pet）。
• JSON Schema 转换器支持的所有 JSON Schema 特性都会保留，包括：
  • 带有属性和必填字段的对象结构
  • 枚举
  • 数值和字符串约束（minimum、maximum、minLength、maxLength、pattern）
  • 数组和集合类型（含 uniqueItems）
  • 映射类型（由 additionalProperties 转换）
  • 组合（allOf、oneOf、anyOf）

示例：

# Convert an OpenAPI document to JSON Structure
avrotize oas2s petstore.yaml --out petstore.struct.json

# With namespace and inline schema lifting
avrotize oas2s api.json --out api.struct.json --namespace com.example.api --lift-inline-schemas

创建 Avrotize 架构的解析规范形式（PCF）

avrotize pcf <path_to_avro_schema_file>

参数：

• <path_to_avro_schema_file>：要转换的 Avrotize Schema 文件的路径。若省略，则从 stdin 读取文件。

转换说明：

• 此工具会生成 Avrotize Schema 的解析规范形式（PCF）。PCF 是架构的一种规范化形式，用于架构比较和兼容性检查。
• PCF 是写入 stdout 的 JSON 对象。

根据架构验证 JSON 实例

avrotize validate <json_files...> --schema <schema_file> [--schema-type <type>] [--quiet]

参数：

• <json_files...>：一个或多个要验证的 JSON 文件。支持单个 JSON 对象、JSON 数组和 JSONL（以换行符分隔的 JSON）格式。
• --schema <schema_file>：架构文件的路径（Avro 使用 .avsc，JSON Structure 使用 .jstruct.json）。
• --schema-type：（可选）架构类型：avro 或 jstruct。若省略，则根据文件扩展名自动检测。
• --quiet：（可选）禁止输出。所有实例均有效时，退出代码为 0；任一实例无效时，退出代码为 1。

验证说明：

• 根据 Avrotize Schema 规范验证 JSON 实例是否符合 Avro 架构。
• 支持所有 Avro 基本类型：null、boolean、int、long、float、double、bytes、string。
• 支持所有 Avro 复杂类型：record、enum、array、map、fixed。
• 支持采用原生编码和字符串编码的逻辑类型：decimal、uuid、date、time-millis、time-micros、timestamp-millis、timestamp-micros、duration。
• 支持使用字段 altnames 映射 JSON 字段名称。
• 支持使用枚举 altsymbols 映射 JSON 符号。
• 验证 JSON Structure 时，需要 json-structure 包。

示例：

# Validate JSON file against Avro schema
avrotize validate data.json --schema schema.avsc

# Validate multiple files
avrotize validate file1.json file2.json --schema schema.avsc

# Validate JSONL file against JSON Structure schema
avrotize validate events.jsonl --schema events.jstruct.json

# Quiet mode for CI/CD pipelines (exit code only)
avrotize validate data.json --schema schema.avsc --quiet

在本地验证 TMSL 脚本

avrotize validate-tmsl [input] [--quiet]

参数：

• [input]：TMSL JSON 文件的路径。若省略，则从 stdin 读取文件。
• --quiet：（可选）禁止输出。有效时退出代码为 0，无效时为 1。

验证说明：

• 根据 Microsoft TMSL 对象定义执行本地结构验证，兼容级别为 1200+。
• 验证 createOrReplace 命令负载是否符合数据库/模型/表/列路径的结构。
• 强制列 dataType 使用文档规定的枚举值（automatic、string、int64、double、dateTime、decimal、boolean、binary、unknown、variant）。
• 对已验证的子集严格检查对象属性（additionalProperties: false）。
• 这不是语义引擎验证；语义检查仍需在 XMLA 端点上执行。

示例：

# Validate a generated TMSL file
avrotize validate-tmsl model.tmsl.json

# CI mode with exit code only
avrotize validate-tmsl model.tmsl.json --quiet

将 JSON Structure 架构转换为 GraphQL 架构

avrotize s2graphql [input] --out <path_to_graphql_schema_file>

参数：

• [input]：JSON Structure 架构文件的路径。若省略，则从 stdin 读取文件。
• --out <path_to_graphql_schema_file>：输出 GraphQL 架构文件的路径。

转换说明：

• 将 JSON Structure Core 架构转换为 GraphQL 架构语言（SDL）
• 支持所有 JSON Structure Core 基本类型（string、number、boolean、null）
• 支持扩展基本类型（binary、int8-128、uint8-128、float/double、decimal、date、datetime、time、duration、uuid、uri、jsonpointer）
• 支持复合类型（object、array、set、map、tuple、any、choice）
• 解析类型引用（$ref），并保持正确的依赖顺序
• 将 JSON Structure 命名空间映射为使用简单名称的 GraphQL 类型
• 为专用类型生成自定义标量（Date、DateTime、UUID、URI、Decimal、Binary、JSON）
• 必需属性在 GraphQL 中标记为 !
• 数组和集合表示为 GraphQL 列表 [Type]
• 映射表示为使用 JSON 标量类型

示例：

# Convert a JSON Structure schema to GraphQL
avrotize s2graphql myschema.struct.json --out myschema.graphql

# Read from stdin and write to stdout
cat myschema.struct.json | avrotize s2graphql > myschema.graphql

将 Avrotize 架构转换为 GraphQL 架构

avrotize a2graphql [input] --out <path_to_graphql_schema_file>

参数：

• [input]：Avrotize 架构文件的路径。如果省略，则从标准输入读取文件。
• --out <path_to_graphql_schema_file>：输出 GraphQL 架构文件的路径。

转换说明：

• 将 Avrotize 架构转换为 GraphQL 架构语言（SDL）
• Avro 基本类型（string、int、long、float、double、boolean、bytes）映射为 GraphQL 标量类型
• Avro 逻辑类型（date、timestamp-millis、decimal、uuid）映射为自定义 GraphQL 标量
• Avro record 类型转换为 GraphQL 对象类型
• Avro 数组转换为 GraphQL 列表 [Type]
• Avro map 使用 JSON 标量类型表示
• Avro union 转换为 GraphQL union 类型
• Avro enum 转换为 GraphQL enum 类型

示例：

# Convert an Avrotize schema to GraphQL
avrotize a2graphql myschema.avsc --out myschema.graphql

# Read from stdin and write to stdout
cat myschema.avsc | avrotize a2graphql > myschema.graphql

参考文档

除了上述命令参考之外，仓库还包含针对特定格式和功能的深入配套文档：

架构模型与规范

• Avrotize 架构 — 正式规范 — 基于 Apache Avro 的架构模型，用作工具的中间表示。
• Apache Avro 架构 — 正式规范 — 底层 Avro 架构格式的参考。

JSON Schema 与 JSON Structure

• JSON Schema 处理 — Avrotize 如何解析和转换 JSON Schema 文档。
• JSON Structure 处理 — JSON Structure 支持和映射。
• JSON Schema → JSON Structure 转换 — 从 JSON Schema 转换为 JSON Structure 的规则。
• JSON Structure → JSON Schema 转换 — 从 JSON Structure 转换回 JSON Schema 的规则。

Avro 编码与其他数据格式

• Apache Avro 的“纯 JSON”编码 — Avrotize 使用的纯 JSON 编码。
• CDDL 处理 — CDDL（RFC 8610）到 JSON Structure 的转换（cddl2s）。

代码生成

• C# 代码生成 — C# 类型映射和生成代码选项。
• Java 代码生成 — Java 类型映射和生成代码选项。

SQL 与 NoSQL 数据库

• SQL 转换说明 — 各支持方言的 Avro → SQL 类型映射（a2sql）。
• SQL → Avro 类型映射 — 将实时 SQL 架构转换为 Avro 时使用的类型映射（sql2a）。
• NoSQL 转换说明 — Cassandra、DynamoDB、MongoDB 及其他 NoSQL 目标的类型映射。

MCP 服务

• VS Code + Copilot MCP 快速入门 — 在 VS Code 中通过 GitHub Copilot 使用 Avrotize MCP 服务。

项目治理与贡献

• 贡献 — 提交问题报告、想法和拉取请求的简要指南。
• 支持 — 了解在哪里提问，以及如何看待尽力提供的支持。
• 安全 — 私下报告漏洞。
• 治理 — 维护者权限、兼容性、审查和发布政策的详细说明。

本文档概述了 Avrotize 的用法和功能。如需了解更多详细信息，请参阅 Avrotize 架构文档和各命令的帮助信息。