Avrotize
Schema conversion and schema-driven code generation MCP server.
Open source Open in the app JSON README (API)
About
Schema conversion and schema-driven code generation MCP server.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- clemensv
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 3.4.3
- Stars
- 131
- Forks
- 14
- Open pull requests
- 11
- Last push
- 2026-09-07T21:24:41Z
- Repository state
- ativo
- Language
- Python
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:35
- Updated
- 2026-08-29 03:02:35
- Origin id
io.github.clemensv/avrotize
README
# Avrotize & Structurize
mcp-name: io.github.clemensv/avrotize
[](https://pypi.org/project/avrotize/)
[](https://pypi.org/project/avrotize/)
[](https://github.com/clemensv/avrotize/actions/workflows/build_deploy.yml)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/avrotize/)
**[📚 Documentation & Examples](https://clemensv.github.io/avrotize/)** | **[🎨 Conversion Gallery](https://clemensv.github.io/avrotize/gallery/)**
Avrotize is a ["Rosetta Stone"](https://en.wikipedia.org/wiki/Rosetta_Stone) for data structure definitions, allowing you to convert between numerous data and database schema formats and to generate code for different programming languages.
It is, for instance, a well-documented and predictable converter and code generator for data structures originally defined in JSON Schema (of arbitrary complexity).
The tool leans on the Apache Avro-derived [Avrotize Schema](specs/avrotize-schema.md) as its schema model.
- Programming languages: Python, C#, Java, TypeScript, JavaScript, Rust, Go, C++
- SQL Databases: MySQL, MariaDB, PostgreSQL, SQL Server, Oracle, SQLite, BigQuery, Snowflake, Redshift, DB2
- Other databases: KQL/Kusto, SurrealDB, MongoDB, Cassandra, Redis, Elasticsearch, DynamoDB, CosmosDB
- Data schema formats: Avro, JSON Schema, JSON Structure, XML Schema (XSD), Protocol Buffers 2 and 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, and OpenAPI 3.x
## Installation
You can install Avrotize from PyPI, [having installed Python 3.10 or later](https://www.python.org/downloads/):
```bash
pip install avrotize
```
For MCP server support (`avrotize mcp`), install with the MCP extra:
```bash
pip install "avrotize[mcp]"
```
For SQL database support (`sql2a` command), install the optional database drivers:
```bash
# PostgreSQL
pip install avrotize[postgres]
# MySQL
pip install avrotize[mysql]
# SQL Server
pip install avrotize[sqlserver]
# All SQL databases
pip install avrotize[all-sql]
```
## Usage
Avrotize provides several commands for converting schema formats via Avrotize Schema.
Converting to Avrotize Schema:
- [`avrotize s2a`](jsonstructure.md#conversion-from-json-structure-into-avro-schema) - Convert JSON Structure to Avrotize Schema.
- [`avrotize j2a`](#convert-json-schema-to-avrotize-schema) - Convert JSON schema to Avrotize Schema.
- [`avrotize p2a`](#convert-proto-schema-to-avrotize-schema) - Convert Protobuf (2 or 3) schema to Avrotize Schema.
- [`avrotize x2a`](#convert-xml-schema-xsd-to-avrotize-schema) - Convert XML schema to Avrotize Schema.
- [`avrotize asn2a`](#convert-asn1-schema-to-avrotize-schema) - Convert ASN.1 to Avrotize Schema.
- [`avrotize jtd2a`](#convert-json-type-definition-jtd-to-avrotize-schema) - Convert JSON Type Definition (JTD) to Avrotize Schema.
- [`avrotize cue2a`](#convert-cue-schema-subset-to-avrotize-schema) - Convert a supported CUE schema subset to Avrotize Schema.
- [`avrotize fbs2a`](#convert-flatbuffers-schema-to-avrotize-schema) - Convert FlatBuffers schema to Avrotize Schema.
- [`avrotize thrift2a`](#convert-apache-thrift-idl-to-avrotize-schema) - Convert Apache Thrift IDL to Avrotize Schema.
- [`avrotize smithy2a`](#convert-smithy-idl-data-shapes-to-avrotize-schema) - Convert Smithy 2.0 IDL data shapes to Avrotize Schema.
- [`avrotize capnp2a`](#convert-capn-proto-schema-to-avrotize-schema) - Convert Cap'n Proto schema to Avrotize Schema.
- [`avrotize raml2a`](#convert-raml-data-types-to-avrotize-schema) - Convert RAML 1.0 Data Types to Avrotize Schema.
- [`avrotize kstruct2a`](#convert-kafka-connect-schema-to-avrotize-schema) - Convert Kafka Connect Schema to Avrotize Schema.
- [`avrotize sql2a`](#convert-sql-database-schema-to-avrotize-schema) - Convert SQL database schema to Avrotize Schema.
- [`avrotize k2a`](#convert-kusto-table-definition-to-avrotize-schema) - Convert Kusto table definitions to Avrotize Schema.
- [`avrotize surreal2a`](#convert-surrealql-schema-to-avrotize-schema) - Convert SurrealQL schema definitions to Avrotize Schema.
- [`avrotize pq2a`](#convert-parquet-schema-to-avrotize-schema) - Convert Parquet schema to Avrotize Schema.
- [`avrotize csv2a`](#convert-csv-file-to-avrotize-schema) - Convert CSV file to Avrotize Schema.
Converting from Avrotize Schema:
- [`avrotize a2s`](jsonstructure.md#conversion-of-avro-schema-into-json-structure) - Convert Avrotize Schema to JSON Structure.
- [`avrotize a2j`](#convert-avrotize-schema-to-json-schema) - Convert Avrotize Schema to JSON schema.
- [`avrotize a2p`](#convert-avrotize-schema-to-proto-schema) - Convert Avrotize Schema to Protobuf 3 schema.
- [`avrotize a2x`](#convert-avrotize-schema-to-xml-schema) - Convert Avrotize Schema to XML schema.
- [`avrotize a2asn`](#convert-avrotize-schema-to-asn1-schema) - Convert Avrotize Schema to ASN.1 schema.
- [`avrotize a2jtd`](#convert-avrotize-schema-to-json-type-definition-jtd) - Convert Avrotize Schema to JSON Type Definition (JTD).
- [`avrotize a2cue`](#convert-avrotize-schema-to-cue-schema-subset) - Convert Avrotize Schema to the supported CUE schema subset.
- [`avrotize a2fbs`](#convert-avrotize-schema-to-flatbuffers-schema) - Convert Avrotize Schema to FlatBuffers schema.
- [`avrotize a2thrift`](#convert-avrotize-schema-to-apache-thrift-idl) - Convert Avrotize Schema to Apache Thrift IDL.
- [`avrotize a2smithy`](#convert-avrotize-schema-to-smithy-idl-data-shapes) - Convert Avrotize Schema to Smithy 2.0 IDL data shapes.
- [`avrotize a2capnp`](#convert-avrotize-schema-to-capn-proto-schema) - Convert Avrotize Schema to Cap'n Proto schema.
- [`avrotize a2raml`](#convert-avrotize-schema-to-raml-data-types) - Convert Avrotize Schema to RAML 1.0 Data Types.
- [`avrotize a2sql`](#convert-avrotize-schema-to-sql-table-definition) - Convert Avrotize Schema to SQL table definition.
- [`avrotize a2k`](#convert-avrotize-schema-to-kusto-table-declaration) - Convert Avrotize Schema to Kusto table definition.
- [`avrotize a2tsml`](#convert-avrotize-schema-to-tabular-model-scripting-language-tmsl) - Convert Avrotize Schema to Tabular Model Scripting Language (TMSL).
- [`avrotize a2surreal`](#convert-avrotize-schema-to-surrealql-schema) - Convert Avrotize Schema to SurrealQL schema definitions.
- [`avrotize a2pq`](#convert-avrotize-schema-to-empty-parquet-file) - Convert Avrotize Schema to Parquet or Iceberg schema.
- [`avrotize a2ib`](#convert-avrotize-schema-to-iceberg-schema) - Convert Avrotize Schema to Iceberg schema.
- [`avrotize a2mongo`](#convert-avrotize-schema-to-mongodb-schema) - Convert Avrotize Schema to MongoDB schema.
- [`avrotize a2cassandra`](#convert-avrotize-schema-to-cassandra-schema) - Convert Avrotize Schema to Cassandra schema.
- [`avrotize a2es`](#convert-avrotize-schema-to-elasticsearch-schema) - Convert Avrotize Schema to Elasticsearch schema.
- [`avrotize a2dynamodb`](#convert-avrotize-schema-to-dynamodb-schema) - Convert Avrotize Schema to DynamoDB schema.
- [`avrotize a2cosmos`](#convert-avrotize-schema-to-cosmosdb-schema) - Convert Avrotize Schema to CosmosDB schema.
- [`avrotize a2couchdb`](#convert-avrotize-schema-to-couchdb-schema) - Convert Avrotize Schema to CouchDB schema.
- [`avrotize a2firebase`](#convert-avrotize-schema-to-firebase-schema) - Convert Avrotize Schema to Firebase schema.
- [`avrotize a2hbase`](#convert-avrotize-schema-to-hbase-schema) - Convert Avrotize Schema to HBase schema.
- [`avrotize a2neo4j`](#convert-avrotize-schema-to-neo4j-schema) - Convert Avrotize Schema to Neo4j schema.
- [`avrotize a2dp`](#convert-avrotize-schema-to-datapackage-schema) - Convert Avrotize Schema to Datapackage schema.
- [`avrotize a2csv`](#convert-avrotize-schema-to-csv-schema) - Convert Avrotize schema to CSV schema.
- [`avrotize a2graphql`](#convert-avrotize-schema-to-graphql-schema) - Convert Avrotize schema to GraphQL schema.
- [`avrotize a2md`](#convert-avrotize-schema-to-markdown-documentation) - Convert Avrotize Schema to Markdown documentation.
Converting to and from JSON Structure:
- [`avrotize j2s`](jsonschematostructure.md) - Convert JSON Schema to JSON Structure.
- [`avrotize s2j`](structuretojsonschema.md) - Convert JSON Structure to JSON Schema.
- [`avrotize s2p`](#convert-json-structure-to-protocol-buffers) - Convert JSON Structure to Protocol Buffers (.proto files).
- [`avrotize s2x`](#convert-json-structure-to-xml-schema-xsd) - Convert JSON Structure to XML Schema (XSD).
- [`avrotize s2asn`](#convert-json-structure-schema-to-asn1-schema) - Convert JSON Structure Schema to ASN.1 schema.
- [`avrotize jtd2s`](#convert-json-type-definition-jtd-to-json-structure) - Convert JSON Type Definition (JTD) to JSON Structure.
- [`avrotize s2jtd`](#convert-json-structure-to-json-type-definition-jtd) - Convert JSON Structure to JSON Type Definition (JTD).
- [`avrotize cddl2s`](cddl.md) - Convert CDDL schema to JSON Structure.
- [`avrotize s2cddl`](cddl.md) - Convert JSON Structure to CDDL schema.
- [`avrotize oas2s`](#convert-openapi-to-json-structure) - Convert OpenAPI 3.x document to JSON Structure.
- [`avrotize cue2s`](#convert-cue-schema-subset-to-json-structure) - Convert a supported CUE schema subset to JSON Structure.
- [`avrotize s2cue`](#convert-json-structure-to-cue-schema-subset) - Convert JSON Structure to the supported CUE schema subset.
- [`avrotize fbs2s`](#convert-flatbuffers-schema-to-json-structure) - Convert FlatBuffers schema to JSON Structure.
- [`avrotize s2fbs`](#convert-json-structure-to-flatbuffers-schema) - Convert JSON Structure to FlatBuffers schema.
- [`avrotize thrift2s`](#convert-apache-thrift-idl-to-json-structure) - Convert Apache Thrift IDL to JSON Structure.
- [`avrotize s2thrift`](#convert-json-structure-to-apache-thrift-idl) - Convert JSON Structure to Apache Thrift IDL.
- [`avrotize smithy2s`](#convert-smithy-idl-data-shapes-to-json-structure) - Convert Smithy 2.0 IDL data shapes to JSON Structure.
- [`avrotize s2smithy`](#convert-json-structure-to-smithy-idl-data-shapes) - Convert JSON Structure to Smithy 2.0 IDL data shapes.
- [`avrotize capnp2s`](#convert-capn-proto-schema-to-json-structure) - Convert Cap'n Proto schema to JSON Structure.
- [`avrotize s2capnp`](#convert-json-structure-to-capn-proto-schema) - Convert JSON Structure to Cap'n Proto schema.
- [`avrotize raml2s`](#convert-raml-data-types-to-json-structure) - Convert RAML 1.0 Data Types to JSON Structure.
- [`avrotize s2raml`](#convert-json-structure-to-raml-data-types) - Convert JSON Structure to RAML 1.0 Data Types.
- [`avrotize s2sql`](#convert-json-structure-schema-to-sql-schema) - Convert JSON Structure Schema to SQL table definition.
- [`avrotize s2k`](#convert-json-structure-schema-to-kusto-table-declaration) - Convert JSON Structure Schema to Kusto table definition.
- [`avrotize k2s`](#convert-kusto-table-definition-to-json-structure) - Convert Kusto table definitions to JSON Structure.
- [`avrotize s2tsml`](#convert-json-structure-to-tabular-model-scripting-language-tmsl) - Convert JSON Structure to Tabular Model Scripting Language (TMSL).
- [`avrotize s2pq`](#convert-json-structure-to-empty-parquet-file) - Convert JSON Structure to Parquet schema.
- [`avrotize s2ib`](#convert-json-structure-to-iceberg-schema) - Convert JSON Structure to Iceberg schema.
- [`avrotize s2cassandra`](#convert-json-structure-schema-to-cassandra-schema) - Convert JSON Structure Schema to Cassandra schema.
- [`avrotize s2graphql`](#convert-json-structure-schema-to-graphql-schema) - Convert JSON Structure schema to GraphQL schema.
- [`avrotize s2dp`](#convert-json-structure-schema-to-datapackage-schema) - Convert JSON Structure schema to Datapackage schema.
- [`avrotize s2csv`](#convert-json-structure-to-csv-schema) - Convert JSON Structure schema to CSV schema.
- [`avrotize s2md`](#convert-json-structure-schema-to-markdown-documentation) - Convert JSON Structure schema to Markdown documentation.
Inferring schemas from data:
- [`avrotize json2a`](#infer-avro-schema-from-json-files) - Infer Avro schema from JSON files.
- [`avrotize json2s`](#infer-json-structure-schema-from-json-files) - Infer JSON Structure schema from JSON files.
- [`avrotize xml2a`](#infer-avro-schema-from-xml-files) - Infer Avro schema from XML files.
- [`avrotize xml2s`](#infer-json-structure-schema-from-xml-files) - Infer JSON Structure schema from XML files.
Generate code from Avrotize Schema:
- [`avrotize a2cs`](#convert-avrotize-schema-to-c-classes) - Generate C# code from Avrotize Schema.
- [`avrotize a2java`](#convert-avrotize-schema-to-java-classes) - Generate Java code from Avrotize Schema.
- [`avrotize a2py`](#convert-avrotize-schema-to-python-classes) - Generate Python code from Avrotize Schema.
- [`avrotize a2ts`](#convert-avrotize-schema-to-typescript-classes) - Generate TypeScript code from Avrotize Schema.
- [`avrotize a2js`](#convert-avrotize-schema-to-javascript-classes) - Generate JavaScript code from Avrotize Schema.
- [`avrotize a2go`](#convert-avrotize-schema-to-go-classes) - Generate Go code from Avrotize Schema.
- [`avrotize a2rust`](#convert-avrotize-schema-to-rust-classes) - Generate Rust code from Avrotize Schema.
- [`avrotize a2cpp`](#convert-avrotize-schema-to-c-classes) - Generate C++ code from Avrotize Schema.
Generate code from JSON Structure:
- [`avrotize s2cs`](#convert-json-structure-to-c-classes) - Generate C# code from JSON Structure schema.
- [`avrotize s2java`](#convert-json-structure-to-java-classes) - Generate Java code from JSON Structure schema.
- [`avrotize s2py`](#convert-json-structure-to-python-classes) - Generate Python code from JSON Structure schema.
- [`avrotize s2ts`](#convert-json-structure-to-typescript-classes) - Generate TypeScript code from JSON Structure schema.
- [`avrotize s2js`](#convert-json-structure-to-javascript-classes) - Generate JavaScript code from JSON Structure schema.
- [`avrotize s2go`](#convert-json-structure-to-go-classes) - Generate Go code from JSON Structure schema.
- [`avrotize s2rust`](#convert-json-structure-to-rust-classes) - Generate Rust code from JSON Structure schema.
- [`avrotize s2cpp`](#convert-json-structure-to-c-classes) - Generate C++ code from JSON Structure schema.
Other commands:
- [`avrotize validate`](#validate-json-instances-against-schemas) - Validate JSON instances against Avro or JSON Structure schemas.
- `avrotize mcp` - Run Avrotize as a local MCP server exposing conversion tools to MCP clients.
- [`avrotize pcf`](#create-the-parsing-canonical-form-pcf-of-an-avrotize-schema) - Create the Parsing Canonical Form (PCF) of an Avrotize Schema.
- [`avrotize validate-tmsl`](#validate-tmsl-scripts-locally) - Validate TMSL scripts locally against documented object structure.
## Overview
## MCP server
You can run Avrotize as a local MCP server over stdio:
```bash
avrotize mcp
```
Catalog-ready metadata files are included:
- Official MCP Registry manifest: [server.json](server.json)
- Microsoft/GitHub MCP catalog listing template: [catalogs/microsoft-github-mcp.md](catalogs/microsoft-github-mcp.md)
- Generic cross-catalog manifest (optional): [mcp-server.json](mcp-server.json)
- VS Code + Copilot usage quickstart: [copilot-vscode-mcp-quickstart.md](copilot-vscode-mcp-quickstart.md)
To publish to the official MCP Registry:
```bash
mcp-publisher validate server.json
mcp-publisher publish server.json
```
The MCP server exposes tools to:
- describe server capabilities and routing guidance (`describe_capabilities`)
- list available conversion commands (`list_conversions`)
- inspect a conversion command (`get_conversion`)
- execute conversions (`run_conversion`)
You can use Avrotize to convert between Avro/Avrotize Schema and other schema formats like JSON Schema, XML Schema (XSD), Protocol Buffers (Protobuf), ASN.1, and database schema formats like Kusto Data Table Definition (KQL) and SQL Table Definition. That means you can also convert from JSON Schema to Protobuf going via Avrotize Schema.
You can also generate C#, Java, TypeScript, JavaScript, and Python code from Avrotize Schema documents. The difference to the native Avro tools is that Avrotize can emit data classes without Avro library dependencies and, optionally, with annotations for JSON serialization libraries like Jackson or System.Text.Json.
The tool does not convert data (instances of schemas), only the data structure definitions.
Mind that the primary objective of the tool is the conversion of schemas that describe data structures used in applications, databases, and message systems. While the project's internal tests do cover a lot of ground, it is nevertheless not a primary goal of the tool to convert every complex document schema like those used for devops pipeline or system configuration files.
## Why?
Data structure definitions are an essential part of data exchange, serialization, and storage. They define the shape and type of data, and they are foundational for tooling and libraries for working with the data. Nearly all data schema languages are coupled to a specific data exchange or storage format, locking the definitions to that format.
Avrotize is designed as a tool to "unlock" data definitions from JSON Schema or XML Schema and make them usable in other contexts. The intent is also to lay a foundation for transcoding data from one format to another, by translating the schema definitions as accurately as possible into the schema model of the target format's schema. The transcoding of the data itself requires separate tools that are beyond the scope of this project.
The use of the term "data structure definition" and not "data object definition" is quite intentional. The focus of the tool is on data structures that can be used for messaging and eventing payloads, for data serialization, and for database tables, with the goal that those structures can be mapped cleanly from and to common programming language types.
Therefore, Avrotize intentionally ignores common techniques to model object-oriented inheritance. For instance, when converting from JSON Schema, all content from `allOf` expressions is merged into a single record type rather than trying to model the inheritance tree in Avro.
## Avrotize Schema
Avrotize Schema is a schema model that is a full superset of the popular Apache Avro Schema model. Avrotize Schema is the "pivot point" for this tool. All schemas are converted from and to Avrotize Schema.
Since Avrotize Schema is a superset of Avro Schema and uses its extensibility features, every Avrotize Schema is also a valid Avro Schema and vice versa.
Why did we pick Avro Schema as the foundational schema model?
Avro Schema ...
- provides a simple, clean, and concise way to define data structures. It is quite easy to understand and use.
- is self-contained by design without having or requiring external references. Avro Schema can express complex data structure hierarchies spanning multiple namespace boundaries all in a single file, which neither JSON Schema nor XML Schema nor Protobuf can do.
- can be resolved by code generators and other tools "top-down" since it enforces dependencies to be ordered such that no forward-referencing occurs.
- emerged out of the Apache Hadoop ecosystem and is widely used for serialization and storage of data and for data exchange between systems.
- supports native and logical types that cover the needs of many business and technical use cases.
- can describe the popular JSON data encoding very well and in a way that always maps cleanly to a wide range of programming languages and systems. In contrast, it's quite easy to inadvertently define a JSON Schema that is very difficult to map to a programming language structure.
- is itself expressed as JSON. That makes it easy to parse and generate, which is not the case for Protobuf or ASN.1, which require bespoke parsers.
> It needs to be noted here that while Avro Schema is great for defining data structures, and data classes generated from Avro Schema using this tool or other tools can be used to with the most popular JSON serialization libraries, the Apache Avro project's own JSON encoding has fairly grave interoperability issues with common usage of JSON. Avrotize defines an alternate JSON encoding
in [`avrojson.md`](avrojson.md).
Avro Schema does not support all the bells and whistles of XML Schema or JSON Schema, but that is a feature, not a bug, as it ensures the portability of the schemas across different systems and infrastructures. Specifically, Avro Schema does not support many of the data validation features found in JSON Schema or XML Schema. There are no `pattern`, `format`, `minimum`, `maximum`, or `required` keywords in Avro Schema, and Avro does not support conditional validation.
In a system where data originates as XML or JSON described by a validating XML Schema or JSON Schema, the assumption we make here is that data will be validated using its native schema language first, and then the Avro Schema will be used for transformation or transfer or storage.
## Adding CloudEvents columns for database tables
When converting Avrotize Schema to Kusto Data Table Definition (KQL), SQL Table Definition, or Parquet Schema, the tool can add special columns for [CloudEvents](https://cloudevents.io) attributes. CNCF CloudEvents is a specification for describing event data in a common way.
The rationale for adding such columns to database tables is that messages and events commonly separate event metadata from the payload data, while that information is merged when events are projected into a database. The metadata often carries important context information about the event that is not contained in the payload itself. Therefore, the tool can add those columns to the database tables for easy alignment of the message context with the payload when building event stores.
### Convert Proto schema to Avrotize Schema
```bash
avrotize p2a <path_to_proto_file> [--out <path_to_avro_schema_file>]
```
Parameters:
- `<path_to_proto_file>`: The path to the Protobuf 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.
Conversion notes:
- Proto 2 and Proto 3 syntax are supported.
- Proto package names are mapped to Avro namespaces. The tool does resolve imports and consolidates all imported types into a single Avrotize Schema file.
- The tool embeds all 'well-known' Protobuf 3.0 types in Avro format and injects them as needed when the respective types are imported. Only the `Timestamp` type is mapped to the Avro logical type 'timestamp-millis'. The rest of the well-known Protobuf types are kept as Avro record types with the same field names and types.
- Protobuf allows any scalar type as key in a `map`, Avro does not. When converting from Proto to Avro, the type information for the map keys is ignored.
- The field numbers in message types are not mapped to the positions of the fields in Avro records. The fields in Avro are ordered as they appear in the Proto schema. Consequently, the Avrotize Schema also ignores the `extensions` and `reserved` keywords in the Proto schema.
- The `optional` keyword results in an Avro field being nullable (union with the `null` type), while the `required` keyword results in a non-nullable field. The `repeated` keyword results in an Avro field being an array of the field type.
- The `oneof` keyword in Proto is mapped to an Avro union type.
- All `options` in the Proto schema are ignored.
### Convert Avrotize Schema to Proto schema
```bash
avrotize a2p <path_to_avro_schema_file> [--out <path_to_proto_directory>] [--naming <naming_mode>] [--allow-optional]
```
Parameters:
- `<path_to_avro_schema_file>`: The path to the Avrotize Schema file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the Protobuf schema directory to write the conversion result to. If omitted, the output is directed to stdout.
- `--naming`: (optional) Type naming convention. Choices are `snake`, `camel`, `pascal`.
- `--allow-optional`: (optional) Enable support for 'optional' fields.
Conversion notes:
- Avro namespaces are resolved into distinct proto package definitions. The tool will create a new `.proto` file with the package definition and an `import` statement for each namespace found in the Avrotize Schema.
- Avro type unions `[]` are converted to `oneof` expressions in Proto. Avro allows for maps and arrays in the type union, whereas Proto only supports scalar types and message type references. The tool will therefore emit message types containing a single array or map field for any such case and add it to the containing type, and will also recursively resolve further unions in the array and map values.
- The sequence of fields in a message follows the sequence of fields in the Avro record. When type unions need to be resolved into `oneof` expressions, the alternative fields need to be assigned field numbers, which will shift the field numbers for any subsequent fields.
### Convert CUE schema subset to Avrotize Schema
```bash
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>]
```
Parameters:
- `<path_to_cue_file>`: The path to the CUE file to be converted. 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 Avrotize Schema records. If omitted, a simple CUE `package` name is used as the namespace.
Supported subset / limitations:
- Supported: schema-style definitions `#Name: { ... }`, top-level fields as a generated record, required fields `name: T`, optional fields `name?: T`, primitive types `string`, `int`, `float`, `number`, `bool`, `bytes`, and `null` (`int` maps to Avro `long`; `number` maps to Avro `double`).
- Supported: nested structs as records, open lists `[...T]` as arrays, open structs `{ [string]: T }` as maps, references to other definitions (`#Other`), disjunctions as Avro unions, nullable disjunctions such as `*null | T` or `T | null`, string-literal disjunctions as Avro enums with sanitized symbols, and simple defaults like `name: T | *default`.
- Out of scope: full CUE constraint solving, imports beyond a simple package declaration, complex constraints and comprehensions, computed or unified expressions, bounds and regex constraints (`>0`, `=~"..."`), interpolation, and package/module resolution. Unsupported constructs are skipped or mapped to a broad string type with a conversion note rather than causing a crash.
Example:
```cue
package demo
#Person: {
name: string
age?: int
tags: [...string]
status: "new" | "active"
}
```
### Convert Avrotize Schema to CUE schema subset
```bash
avrotize a2cue <path_to_avro_schema_file> [--out <path_to_cue_file>] [--namespace <cue_package_hint>]
```
Conversion notes:
- Avro records become CUE definitions (`#Name: { ... }`), fields become `name: Type`, nullable unions become optional fields where possible, enums become string disjunctions, arrays become `[...T]`, and maps become `{ [string]: T }`.
- Avro `int` and `long` both emit as CUE `int`; `float` emits as `float`; `double` emits as `number`. Avro namespaces are reduced to a simple CUE package name using the last namespace segment.
- The converter emits the same practical schema subset accepted by `cue2a`; it does not attempt to reconstruct CUE constraints, imports, comprehensions, or computed expressions.
### Convert CUE schema subset to JSON Structure
```bash
avrotize cue2s <path_to_cue_file> [--out <path_to_structure_file>] [--namespace <namespace>]
```
`cue2s` bridges through an intermediate Avrotize Schema file and therefore uses the same supported CUE subset and limitations as `cue2a`.
### Convert JSON Structure to CUE schema subset
```bash
avrotize s2cue <path_to_structure_file> [--out <path_to_cue_file>] [--namespace <cue_package_hint>]
```
`s2cue` bridges through an intermediate Avrotize Schema file and emits the same practical CUE schema subset as `a2cue`.
- `<path_to_fbs_file>`: The path to the FlatBuffers `.fbs` 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) Override the FlatBuffers namespace for the Avrotize Schema.
Conversion notes and limitations:
- FlatBuffers `namespace` declarations are mapped to Avro namespaces. `table` and `struct` declarations are mapped to Avro records; FlatBuffers structs carry fixed inline layout semantics that Avro does not represent, so this is documented on the generated record.
- FlatBuffers enums are mapped to Avro enums. Integer enum values are preserved in the non-standard Avrotize `ordinals` annotation; consumers that only understand Avro enum symbols may ignore those integer values.
- FlatBuffers unions are mapped to Avro unions of their member record types.
- Scalar mappings: signed 8/16/32-bit integers map to Avro `int`; unsigned 32-bit integers and all 64-bit integers map to Avro `long`; `uint64`/`ulong` values beyond signed 64-bit range cannot be represented exactly by Avro `long`; `float` and `double` map to Avro `float` and `double`; `string` maps to Avro `string`.
- Vectors map to Avro arrays, except `[ubyte]`/`[uint8]`, which maps to Avro `bytes`.
- Table fields without `(required)` are emitted as nullable Avro fields with `null` defaults. FlatBuffers field defaults are preserved as the Avrotize `fbsDefault` annotation for nullable fields.
- `root_type` is preserved as a record-level `root_type` annotation.
### Convert Avrotize Schema to FlatBuffers schema
```bash
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>]
```
Parameters:
- `<path_to_avro_schema_file>`: The path to the Avrotize Schema file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the FlatBuffers `.fbs` file to write the conversion result to. If omitted, the output is directed to stdout.
- `--namespace`: (optional) Override the FlatBuffers namespace.
Conversion notes and limitations:
- Avro records are emitted as FlatBuffers tables, Avro enums as FlatBuffers enums, arrays as vectors, and Avro `bytes` as `[ubyte]`.
- Nullable Avro unions (`["null", T]`) become optional FlatBuffers fields. Multi-branch Avro unions of named types are emitted as FlatBuffers `union` declarations.
- Avro namespaces map to FlatBuffers namespaces. The top record, or the record annotated with `root_type`, is emitted as `root_type`.
- Avro maps, logical types, fixed types, aliases, validation annotations, and arbitrary custom annotations have no direct FlatBuffers equivalent and are either simplified to compatible field types or omitted.
### Convert Avrotize Schema to ASN.1 schema
```bash
avrotize a2asn <path_to_avro_schema_file> [--out <path_to_asn1_file>] [--module <asn1_module_name>]
```
Parameters:
- `<path_to_avro_schema_file>`: The path to the Avrotize Schema file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the ASN.1 module file to write the conversion result to. If omitted, the output is directed to stdout. The ASN.1 module name is derived from the output file name when `--module` is not given.
- `--module`: (optional) Override the ASN.1 module name.
Conversion notes and limitations:
- The emitted module uses `DEFINITIONS AUTOMATIC TAGS`, which lets the ASN.1 compiler disambiguate `OPTIONAL` and `CHOICE` tags automatically.
- Avro records map to `SEQUENCE`, Avro enums to `ENUMERATED`, arrays to `SEQUENCE OF`, and `fixed` to `OCTET STRING (SIZE(n))`.
- Avro maps map to `SEQUENCE OF SEQUENCE { key UTF8String, value ... }`.
- Nullable unions (`["null", T]`) become `OPTIONAL` members; multi-branch unions become an ASN.1 `CHOICE`.
- Logical types map to ASN.1 useful types: `date` → `DATE`, `time-millis`/`time-micros` → `TIME-OF-DAY`, `timestamp-*` → `DATE-TIME`; `decimal`, `uuid`, and `duration` are represented as `REAL`/`UTF8String` because ASN.1 has no exact equivalents.
- Identifiers are sanitized to strict X.680 (hyphens instead of underscores); the module is validated by round-tripping through the `asn1tools` compiler.
### Convert JSON Structure Schema to ASN.1 schema
```bash
avrotize s2asn <path_to_structure_schema_file> [--out <path_to_asn1_file>] [--module <asn1_module_name>]
```
Parameters:
- `<path_to_structure_schema_file>`: The path to the JSON Structure schema file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the ASN.1 module file to write the conversion result to. If omitted, the output is directed to stdout. The ASN.1 module name is derived from the output file name when `--module` is not given.
- `--module`: (optional) Override the ASN.1 module name.
Conversion notes and limitations:
- This is a direct JSON Structure → ASN.1 mapping; it does **not** route through Avrotize Schema, so the richer JSON Structure type system is preserved.
- Sized integer types map to `INTEGER` with faithful range constraints (for example `int8` → `INTEGER (-128..127)`, `uint32` → `INTEGER (0..4294967295)`).
- `object` maps to `SEQUENCE`, `array` to `SEQUENCE OF`, `set` to `SET OF`, `map` to `SEQUENCE OF SEQUENCE { key UTF8String, value ... }`, `tuple` to a positional `SEQUENCE`, and `choice` to `CHOICE`.
- String `enum`/`const` values map to `ENUMERATED` (preserving the symbol labels and their ordinals); integer `enum`/`const` values map to an `INTEGER (v1 | v2 | ...)` value constraint (preserving the exact values).
- `$extends` merges the base object's properties into the derived `SEQUENCE`; canonical `{"type": {"$ref": ...}}` references, bare `{"$ref": ...}` references, and nested definition namespaces are all resolved.
- Non-required or nullable members become `OPTIONAL`. Types without an exact ASN.1 equivalent (`uuid`, `uri`, `duration`, `jsonpointer`) are represented as `UTF8String`; `any` maps to the ASN.1 open type `ANY`.
### Convert FlatBuffers schema to JSON Structure
```bash
avrotize fbs2s <path_to_fbs_file> [--out <path_to_json_structure_file>] [--namespace <avro_schema_namespace>]
```
Parameters:
- `<path_to_fbs_file>`: The path to the FlatBuffers `.fbs` schema file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the JSON Structure file to write the conversion result to. If omitted, the output is directed to stdout.
- `--namespace`: (optional) Override the namespace used by the Avrotize Schema bridge.
Conversion notes:
- This conversion bridges through Avrotize Schema (`fbs2a` followed by `a2s`) and therefore shares the FlatBuffers-to-Avro mapping limitations listed above.
- The FlatBuffers `root_type` record is used as the JSON Structure root when present.
### Convert JSON Structure to FlatBuffers schema
```bash
avrotize s2fbs <path_to_json_structure_file> [--out <path_to_fbs_file>] [--namespace <flatbuffers_namespace>]
```
Parameters:
- `<path_to_json_structure_file>`: The path to the JSON Structure schema file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the FlatBuffers `.fbs` file to write the conversion result to. If omitted, the output is directed to stdout.
- `--namespace`: (optional) Override the FlatBuffers namespace.
Conversion notes:
- This conversion bridges through Avrotize Schema (`s2a` followed by `a2fbs`) and therefore shares the Avro-to-FlatBuffers mapping limitations listed above.
- JSON Structure constraints and metadata that do not survive the Avrotize Schema bridge are not represented in the generated FlatBuffers schema.
- `--out`: The path to the Thrift IDL file to write. If omitted, the output is directed to stdout.
- `--namespace`: (optional) Override the emitted `namespace *` value.
Conversion notes and limitations:
- Avro records are emitted as Thrift `struct` definitions with sequential field ids. Avro enums are emitted as Thrift enums.
- Nullable Avro unions (`["null", T]`) are emitted as `optional` fields; other multi-branch Avro unions are approximated as `string`.
- Avro arrays are emitted as `list<T>` and Avro maps as `map<string,V>`. Thrift `set` and non-string map-key semantics cannot be recovered from Avro.
- Avro logical types and custom annotations are not represented in Thrift IDL.
### Convert Apache Thrift IDL to JSON Structure
```bash
avrotize thrift2s <path_to_thrift_file> [--out <path_to_structure_file>] [--namespace <avro_schema_namespace>]
```
Converts Thrift IDL to JSON Structure by first converting to Avrotize Schema. The Thrift-to-Avro limitations above therefore apply.
### Convert JSON Structure to Apache Thrift IDL
```bash
avrotize s2thrift <path_to_structure_file> [--out <path_to_thrift_file>] [--namespace <thrift_namespace>]
```
Converts JSON Structure to Thrift IDL by first converting to Avrotize Schema. The Avro-to-Thrift limitations above therefore apply.
- `--out`: The path to the Smithy IDL file to write. If omitted, the output is directed to stdout.
- `--namespace`: (optional) Override the Smithy namespace to emit.
Conversion notes:
- Avro records become Smithy `structure` shapes; nullable unions become optional members; non-null fields are emitted with `@required`.
- Avro enums become Smithy `enum` shapes, or `intEnum` when an `ordinals` annotation is present. Avro arrays and maps become Smithy `list` and `map` shapes. Avro unions with multiple non-null alternatives become Smithy `union` shapes.
- Service and operation modeling is explicitly out of phase-1 scope; this command emits Smithy data shapes only.
- `--out`: The path to the Cap'n Proto schema file to write. If omitted, the output is directed to stdout.
- `--namespace`: Optional namespace note included as a comment in the generated file.
Conversion notes and limitations:
- Avro records map to `struct`, enums to `enum`, arrays to `List(T)`, strings to `Text`, bytes/fixed to `Data`, and nullable unions to the non-null Cap'n Proto field type.
- Fields are emitted with deterministic sequential ordinals (`@0`, `@1`, ...). A stable generated file id is emitted; replace it if the schema needs a project-owned Cap'n Proto id.
- Multi-branch Avro unions are emitted as nested choice structs or `union` blocks when `capnpUnion` metadata is present. Avro maps are represented as lists of generated key/value entry structs because Cap'n Proto has no direct map primitive.
### Convert Cap'n Proto schema to JSON Structure
```bash
avrotize capnp2s <path_to_capnp_file> [--out <path_to_json_structure_file>] [--namespace <avro_schema_namespace>] [--naming <naming_mode>] [--avro-encoding]
```
This conversion bridges through an intermediate Avrotize Schema, so the Cap'n Proto limitations documented for `capnp2a` apply.
### Convert JSON Structure to Cap'n Proto schema
```bash
avrotize s2capnp <path_to_json_structure_file> [--out <path_to_capnp_file>] [--namespace <namespace_note>]
```
This conversion bridges through an intermediate Avrotize Schema, so the Avro-to-Cap'n Proto limitations documented for `a2capnp` apply.
- `<path_to_avro_schema_file>`: The path to the Avrotize Schema file. If omitted, the file is read from stdin.
- `--out`: The path to the RAML file to write. If omitted, the output is directed to stdout.
- `--namespace`: (optional) Namespace to strip from generated RAML type references.
Conversion notes:
- The converter emits a `#%RAML 1.0 Library` with a `types:` map. Full RAML API resource/method conversion is explicitly out of scope.
- Avro records become RAML `object` types, nullable fields are emitted with the `name?` optional-property form, enums become `enum:`, arrays become `T[]`, maps use `properties: { "//": T }`, and unions become `A | B`.
- Avro logical types map back to RAML `date-only`, `time-only`, or `datetime`. `datetime-only` cannot be distinguished from Avro timestamp logical types on reverse conversion.
### Convert JSON schema to Avrotize Schema
```bash
avrotize j2a <path_to_json_schema_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>] [--split-top-level-records]
```
Parameters:
- `<path_to_json_schema_file>`: The path to the JSON 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) The namespace to use in the Avrotize Schema if the JSON schema does not define a namespace.
- `--split-top-level-records`: (optional) Split top-level records into separate files.
Conversion notes:
- [JSON Schema Handling in Avrotize](jsonschema.md)
### Convert Avrotize Schema to JSON schema
```bash
avrotize a2j <path_to_avro_schema_file> [--out <path_to_json_schema_file>] [--naming <naming_mode>]
```
Parameters:
- `<path_to_avro_schema_file>`: The path to the Avrotize Schema file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the JSON schema file to write the conversion result to. If omitted, the output is directed to stdout.
- `--naming`: (optional) Type naming convention. Choices are `snake`, `camel`, `pascal`, `default`.
Conversion notes:
- [JSON Schema Handling in Avrotize](jsonschema.md)
### Convert XML Schema (XSD) to Avrotize Schema
```bash
avrotize x2a <path_to_xsd_file> [--out <path_to_avro_schema_file>] [--namespace <avro_schema_namespace>]
```
Parameters:
- `<path_to_xsd_file>`: The path to the XML 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) The namespace to use in the Avrotize Schema if the XML schema does not define a namespace.
Conversion notes:
- All XML Schema constructs are mapped to Avro record types with fields, whereby **both**, elements and attributes, become fields in the record. XML is therefore flattened into fields and this aspect of the structure is not preserved.
- Avro does not support `xsd:any` as Avro does not support arbitrary typing and must always use a named type. The tool will map `xsd:any` to a field `any` typed as a union that allows scalar values or two levels of array and/or map nesting.
- `simpleType` declarations that define enums are mapped to `enum` types in Avro. All other facets are ignored and simple types are mapped to the corresponding Avro type.
- `complexType` declarations that have simple content where a base type is augmented with attributes is mapped to a record type in Avro. Any other facets defined on the complex type are ignored.
- If the schema defines a single root element, the tool will emit a single Avro record type. If the schema defines multiple root elements, the tool will emit a union of record types, each corresponding to a root element.
- All fields in the resulting Avrotize Schema are annotated with an `xmlkind` extension attribute that indicates whether the field was an `element` or an `attribute` in the XML schema.
### Convert Avrotize Schema to XML schema
```bash
avrotize a2x <path_to_avro_schema_file> [--out <path_to_xsd_schema_file>] [--namespace <target_namespace>]
```
Parameters:
- `<path_to_avro_schema_file>`: The path to the Avrotize Schema file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the XML schema file to write the conversion result to. If omitted, the output is directed to stdout.
- `--namespace`: (optional) Target namespace for the XSD schema.
Conversion notes:
- Avro record types are mapped to XML Schema complex types with elements.
- Avro enum types are mapped to XML Schema simple types with restrictions.
- Avro logical types are mapped to XML Schema simple types with restrictions where required.
- Avro unions are mapped to standalone XSD simple type definitions with a union restriction if all union types are primitives.
- Avro unions with complex types are resolved into distinct types for each option that are
then joined with a choice.
### Convert JSON Structure to XML Schema (XSD)
```bash
avrotize s2x <path_to_structure_file> [--out <path_to_xsd_schema_file>] [--namespace <target_namespace>]
```
Parameters:
- `<path_to_structure_file>`: The path to the JSON Structure schema file to be converted. If omitted, the file is read from stdin.
- `--out`: The path to the XML schema file to write the conversion result to. If omitted, the output is directed to stdout.
- `--namespace`: (optional) Target namespace for the XSD schema.
Conversion notes:
- JSON Structure object types are mapped to XML Schema complex types with elements.
- JSON Structure primitive types (string, int8-128, uint8-128, float/double, boolean, etc.) are mapped to appropriate XSD simple types.
- Extended primitive types are mapped as follows:
- `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`
- Collection types:
- `array` and `set` → complex types with sequences of items
- `map` → complex type with entry elements containing key and value
- `tuple` → complex type with fixed sequence of typed items
- Union types (`choice` or type arrays like `["string", "null"]`):
- Tagged unions (with discriminator) → `xs:choice` elements
- Inline unions → abstract base types with concrete extensions
- Nullable types → elements with `minOccurs="0"`
- Type references (`$ref`) are resolved to named XSD types
- Type extensions (`$extends`) are mapped to XSD complex type extensions with `xs:complexContent`
- Abstract types are marked with `abstract="true"` in XSD
- Validation constraints (minLength, maxLength, pattern, minimum, maximum) are converted to XSD restrictions/facets
- Required properties become elements with `minOccurs="1"`, optional properties have `minOccurs="0"`
### Convert ASN.1 schema to Avrotize Schema
```bash
avrotize asn2a <path_to_asn1_schema_file>[,<path_to_asn1_schema_file>,...] [--out <path_to_avro_schema_file>]
```
Parameters:
- `<path_to_asn1_schema_file>`: The path to the ASN.1 schema file to be converted. The tool supports multiple files in a comma-separated list. 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.
Conversion notes:
- All ASN.1 types are mapped to Avro record types, enums, and unions. Avro does not support the same level of nesting of types as ASN.1, the tool will map the types to the best fit.
- The tool will map the following ASN.1 types to Avro types:
- `SEQUENCE` and `SET` are mapped to Avro record types.
- `CHOICE` is mapped to an Avro record types with all fields being optional. While the `CHOICE` type technically corresponds to an Avro union, the ASN.1 type has different named fields for each option, which is not a feature of Avro unions.
- `OBJECT IDENTIFIER` is mapped to an Avro string type.
- `ENUMERATED` is mapped to an Avro enum type.
- `SEQUENCE OF` and `SET OF` are mapped to Avro array type.
- `BIT STRING` is mapped to Avro bytes type.
- `OCTET STRING` is mapped to Avro bytes type.
- `INTEGER` is mapped to Avro long type.
- `REAL` is mapped to Avro double type.
- `BOOLEAN` is mapped to Avro boolean type.
- `NULL` is mapped to Avro null type.
- `UTF8String`, `PrintableString`, `IA5String`, `BMPString`, `NumericString`, `TeletexString`, `VideotexString`, `GraphicString`, `VisibleString`, `GeneralString`, `UniversalString`, `CharacterString`, `T61String` are all mapped to Avro string type.
- All other ASN.1 types are mapped to Avro string type.
- The ability to parse ASN.1 schema files is limited and the tool may not be able to parse all ASN.1 files. The tool is based on the Python asn1tools package and is limited to that package's capabilities.
### Convert Kusto table definition to Avrotize Schema
```bash
avrotize k2a --kusto-uri <kusto_cluster_uri> --kusto-database <kusto_database> [--out <path_to_avro_schema_file>] [--emit-cloudevents-xregistry]
```
Parameters:
- `--kusto-uri`: The URI of the Kusto cluster to connect to.
- `--kusto-database`: The name of the Kusto database to read the table definitions from.
- `--out`: The path to the Avrotize Schema file to write the conversion result to. If omitted, the output is directed to stdout.
- `--emit-cloudevents-xregistry`: (optional) See discussion below.
Conversion notes:
- The tool directly connects to the Kusto cluster and reads the table definitions from the specified database. The tool will convert all tables in the database to Avro record types, returned in a top-level type union.
- Connecting to the Kusto cluster leans on the same authentication mechanisms as the Azure CLI. The tool will use the same authentication context as the Azure CLI if it is installed and authenticated.
- The tool will map the Kusto column types to Avro types as follows:
- `bool` is mapped to Avro boolean type.
- `datetime` is mapped to Avro long type with logical type `timestamp-millis`.
- `decimal` is mapped to a logical Avro type with the `logicalType` set to `decimal` and the `precision` and `scale` set to the values of the `decimal` type in Kusto.
- `guid` is mapped to Avro string type.
- `int` is mapped to Avro int type.
- `long` is mapped to Avro long type.
- `real` is mapped to Avro double type.
- `string` is mapped to Avro string type.
- `timespan` is mapped to a logical Avro type with the `logicalType` set to `duration`.
- For `dynamic` columns, the tool will sample the data in the table to determine the structure of the dynamic column. The tool will map the dynamic column to an Avro record type with fields that correspond to the fields found in the dynamic column. If the dynamic column contains nested dynamic columns, the tool will recursively map those to Avro record types. If records with conflicting structures are found in the dynamic column, the tool will emit a union of record types for the dynamic column.
- If the `--emit-cloudevents-xregistry` option is set, the tool will emit an [xRegistry](http://xregistry.io) registry manifest file with a CloudEvent message definition for each table in the Kusto database and a separate Avro Schema for each table in the embedded schema registry. If one or more tables are found to contain CloudEvent data (as indicated by the presence of the CloudEvents attribute columns), the tool will inspect the content of the `type` (or `__type` or `__type`) columns to determine which CloudEvent types have been stored in the table and will emit a CloudEvent definition and schema for each unique type.
### Convert Kusto table definition to JSON Structure
```bash
avrotize k2s [<path_to_kusto_file>] [--out <path_to_structure_file>] [--kusto-uri <kusto_cluster_uri>] [--kusto-database <kusto_database>] [--table-name <table_name>]
```
The command accepts either a Kusto definition file or a live Kusto cluster and database. It can sample `dynamic` columns to infer nested structures, choices, and enums. Use `--emit-cloudevents` to add CloudEvents declarations or `--emit-xregistry` to emit an xRegistry manifest instead of a single JSON Structure schema.
### Convert SQL database schema to Avrotize Schema
```bash
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]
```
Parameters:
- `--connection-