Supported formats

Every format Apiome reads or writes, generated from the running registries — the import-source registry, the emitter registry, and the source-format capability registry. It is regenerated by one command and drift-checked in CI, so this page cannot quietly fall behind the code the way a hand-maintained list does.

• 51 formats can be imported.
• 44 formats can be exported.
• 44 round-trip — import and export.
• 5 can introspect a live endpoint rather than reading a file.

The same answer is machine-readable at GET /v1/formats/matrix and printed by apiome formats (--json, --paradigm, --direction). This page is rendered from that response, so the documentation, the API and the CLI cannot disagree: there is one traversal of the registries behind all three.

Which importer handles which format

Apiome has two importers, and which one a format uses is decided by the server (app.import_routing), not by where you started:

• OpenAPI and Swagger become a publishable Project. They normalize onto the editable class/path model, so they can be versioned, linted and published. This is the Projects importer, and its four format keys (openapi-3.0, openapi-3.1, openapi-3.2, swagger-2.0) are the set the older documentation described as the whole of Apiome's format support.
• The other 50 formats become a catalog item. Protobuf, GraphQL, AsyncAPI, Thrift, EDI X12, COBOL copybooks, FHIR, HL7 v2 and the rest are imported by the Catalog importer and stored with their own structure intact rather than being forced into the OpenAPI shape. Catalog items are searchable, diffable and convertible; they are not publishable until converted.

The Direction column below says whether a format can be imported, exported, or both. The Publishable column says which of the two importers claims it.

Reading the table

Column	Meaning
Key	The stable registry key. This is the source_kind the REST API and CLI take.
Direction	Whether the format can be imported, exported, or both.
Publishable	Project mints a publishable project; Catalog stores a catalog item. Routing branches on the format a document normalizes to, not the tool that read it — so a format that converts to OpenAPI first (TypeSpec, say) produces a Project on that path.
Input kinds	How a document can reach the adapter: uploaded file, url, pasted paste, live discovery, or a multi-file fileset (an archive or repository).
Live discovery	The adapter can introspect a running endpoint instead of reading a document.
Format keys	Every format string the adapter declares, so a specific version can be requested. A mix of version keys and detection aliases — see Version coverage for which of them are versions.
File extensions	What the file pickers offer for this format. Advisory: content sniffing decides, so an unlisted extension is still accepted.
Analysis	Format-native keeps the format's own vocabulary (an X12 envelope stays an envelope); Generic uses the format-blind walk. Reviewed entries link to their boundary notes.
Runtime	Ready, or the toolchain this deployment is missing. An unavailable format is still supported — this deployment just cannot run it.

REST

Format	Key	Direction	Publishable	Input kinds	Live discovery	Format keys	File extensions	Analysis	Runtime
API Blueprint	apiblueprint	Import + export	Catalog	file, url, paste, fileset	—	apiblueprint, api-blueprint, apib, blueprint	.apib, .md, .zip, .tar.gz, .tgz, .tar	Generic	Ready
Arazzo	arazzo	Import + export	Catalog	file, url, paste, fileset	—	arazzo	.arazzo.yaml, .arazzo.yml, .arazzo.json, .yaml, .yml, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready
FHIR	fhir	Import + export	Catalog	file, url, paste, fileset	—	fhir, fhirr4, structuredefinition	.fhir.json, .structuredefinition.json, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready
Gateway API HTTPRoute	gateway-api	Import + export	Catalog	file, url, paste, fileset	—	gateway-api, httproute	.yaml, .yml, .zip, .tar.gz, .tgz, .tar	Generic	Ready
Google API Discovery	discovery	Import only	Catalog	file, url, paste, discovery, fileset	Yes	discovery	.discovery.json, .discovery, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready
HTTP Request File	http-file	Import + export	Catalog	file, paste, fileset	—	http-file, http, rest	.http, .rest, .zip, .tar.gz, .tgz, .tar	Generic	Ready
Kong Declarative Config	kong	Import + export	Catalog	file, url, paste, fileset	—	kong, kong-declarative	.yaml, .yml, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready
OData	odata	Import + export	Catalog	file, url, paste, fileset	—	odata, odata-v2, odata-v3, edmx	.edmx, .xml, .zip, .tar.gz, .tgz, .tar	Generic	Ready
OpenAPI / Swagger	openapi	Import + export	Project	file, url, paste, fileset	—	openapi-3.0, openapi-3.1, openapi-3.2, swagger-2.0, swagger-1.2	.yaml, .yml, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready
Postman	postman	Import + export	Catalog	file, url, paste, fileset	—	postman, postmancollection, postman-2.0	.postman_collection.json, .postman.json, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready
RAML	raml	Import + export	Catalog	file, url, paste, fileset	—	raml	.raml, .zip, .tar.gz, .tgz, .tar	Generic	Ready
TypeSpec	typespec	Import + export	Catalog	file, url, paste, fileset	—	typespec, tsp, cadl	.tsp, .cadl, .zip, .tar.gz, .tgz, .tar	Generic	Ready
WADL	wadl	Import + export	Catalog	file, url, paste, fileset	—	wadl, restdescription	.wadl, .xml, .zip, .tar.gz, .tgz, .tar	Generic	Ready
WSDL	wsdl	Import + export	Catalog	file, url, paste, fileset	—	wsdl, wsdl-2.0, soap	.wsdl, .xml, .zip, .tar.gz, .tgz, .tar	Generic	Ready
z/OS Connect	zosconnect	Import + export	Catalog	file, url, paste, fileset	—	zosconnect, zos, zos-connect	.zosconnect.json, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready

RPC

Format	Key	Direction	Publishable	Input kinds	Live discovery	Format keys	File extensions	Analysis	Runtime
Cap'n Proto	capnproto	Import + export	Catalog	file, url, paste, fileset	—	capnproto, capnp	.capnp, .zip, .tar.gz, .tgz, .tar	Generic	Ready
Connect RPC	connectrpc	Import + export	Catalog	file, url, paste, discovery, fileset	Yes	connectrpc	.proto, .zip, .tar.gz, .tgz, .tar	Generic	Needs toolchain — Requires the buf toolchain, which is not available in this runtime.
CORBA IDL	corbaidl	Import + export	Catalog	file, url, paste, fileset	—	corbaidl, corba, idl	.idl, .zip, .tar.gz, .tgz, .tar	Generic	Ready
gRPC / Protobuf	grpc	Import + export	Catalog	file, url, paste, discovery, fileset	Yes	protobuf, protobuf-editions	.proto, .binpb, .desc, .protoset, .zip, .tar.gz, .tgz, .tar	Generic (reviewed)	Needs toolchain — Requires the buf toolchain, which is not available in this runtime.
ONC RPC	oncrpc	Import + export	Catalog	file, url, paste, fileset	—	oncrpc, sunrpc, rpcgen, xdr	.x, .zip, .tar.gz, .tgz, .tar	Generic	Ready
OpenRPC	openrpc	Import + export	Catalog	file, url, paste, fileset	—	openrpc, jsonrpc	.openrpc.json, .openrpc, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready
Smithy	smithy	Import + export	Catalog	file, url, paste, fileset	—	smithy	.smithy, .zip, .tar.gz, .tgz, .tar	Generic	Ready
Thrift	thrift	Import + export	Catalog	file, url, paste, fileset	—	thrift	.thrift, .zip, .tar.gz, .tgz, .tar	Generic	Ready
WIT (WebAssembly)	wit	Import + export	Catalog	file, url, paste, fileset	—	wit	.wit, .zip, .tar.gz, .tgz, .tar	Generic	Ready
XML-RPC	xmlrpc	Import + export	Catalog	file, url, paste, fileset	—	xmlrpc, xml-rpc	.xmlrpc, .xml, .zip, .tar.gz, .tgz, .tar	Generic	Ready

Event

Format	Key	Direction	Publishable	Input kinds	Live discovery	Format keys	File extensions	Analysis	Runtime
AsyncAPI	asyncapi	Import + export	Catalog	file, url, paste, fileset	—	asyncapi-2, asyncapi-3	.asyncapi.yaml, .asyncapi.yml, .asyncapi.json, .yaml, .yml, .json, .zip, .tar.gz, .tgz, .tar	Generic	Needs toolchain — Requires the asyncapi-parser toolchain, which is not available in this runtime.
CloudEvents	cloudevents	Import + export	Catalog	file, url, paste, fileset	—	cloudevents, cloud-events	.cloudevents.json, .cloudevent.json, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready

Graph

Format	Key	Direction	Publishable	Input kinds	Live discovery	Format keys	File extensions	Analysis	Runtime
GraphQL	graphql	Import + export	Catalog	file, url, paste, discovery, fileset	Yes	graphql	.graphql, .gql, .graphqls, .zip, .tar.gz, .tgz, .tar	Generic	Ready

Data schema

Format	Key	Direction	Publishable	Input kinds	Live discovery	Format keys	File extensions	Analysis	Runtime
Apache Arrow	arrow	Import only	Catalog	file, url, paste, discovery, fileset	Yes	arrow	.arrow, .arrows, .ipc, .feather, .arrow.json, .flight.json, .json, .zip, .tar.gz, .tgz, .tar	Generic (reviewed)	Ready
ASN.1	asn1	Import + export	Catalog	file, url, paste, fileset	—	asn1, asn	.asn1, .asn, .zip, .tar.gz, .tgz, .tar	Generic	Ready
Avro	avro	Import + export	Catalog	file, url, paste, fileset	—	avro, avsc, avro-idl	.avsc, .avro, .avdl, .zip, .tar.gz, .tgz, .tar	Generic	Ready
CDDL	cddl	Import + export	Catalog	file, url, paste, fileset	—	cddl	.cddl, .cdl, .zip, .tar.gz, .tgz, .tar	Generic (reviewed)	Ready
COBOL Copybook	cobolcopybook	Import + export	Catalog	file, url, paste, fileset	—	cobolcopybook, copybook, cobol, cobol-copybook	.cpy, .cbl, .copybook, .zip, .tar.gz, .tgz, .tar	Format-native (reviewed)	Ready
dbt Project	dbt	Import only	Catalog	file, url, paste, fileset	—	dbt	.yml, .yaml, .json, .sql, .zip, .tar.gz, .tgz, .tar	Generic (reviewed)	Ready
DTD	dtd	Import only	Catalog	file, url, paste, fileset	—	dtd	.dtd, .ent, .mod, .zip, .tar.gz, .tgz, .tar	Generic (reviewed)	Ready
EDI X12	edix12	Import + export	Catalog	file, url, paste, fileset	—	edix12, x12, edi	.edi, .x12, .zip, .tar.gz, .tgz, .tar	Format-native (reviewed)	Ready
FIX	fix	Import + export	Catalog	file, url, paste, fileset	—	fix, fixprotocol	.fix, .zip, .tar.gz, .tgz, .tar	Generic	Ready
FlatBuffers	flatbuffers	Import + export	Catalog	file, url, paste, fileset	—	flatbuffers, fbs	.fbs, .zip, .tar.gz, .tgz, .tar	Generic	Ready
HL7 v2	hl7v2	Import + export	Catalog	file, url, paste, fileset	—	hl7v2, hl7, hl7v2x	.hl7, .zip, .tar.gz, .tgz, .tar	Generic	Ready
ISO 20022	iso20022	Import + export	Catalog	file, url, paste, fileset	—	iso20022	.xml, .zip, .tar.gz, .tgz, .tar	Generic	Ready
ISO 8583	iso8583	Import + export	Catalog	file, url, paste, fileset	—	iso8583	.iso8583.json, .8583.json, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready
JSON Schema	json-schema	Import + export	Catalog	file, url, paste	—	json-schema, jsonschema, json-schema-2020-12	.schema.json, .json	Generic	Ready
JSON Type Definition	jtd	Import + export	Catalog	file, url, paste	—	jtd, jsontypedefinition, rfc8927	.jtd.json, .json	Generic	Ready
Kafka Connect Schema	kafka-connect	Import + export	Catalog	file, url, paste, fileset	—	kafka-connect	.connect.json, .connect-schema.json, .json, .zip, .tar.gz, .tgz, .tar	Generic (reviewed)	Ready
Kubernetes CRD	k8s-crd	Import + export	Catalog	file, url, paste, fileset	—	k8s-crd	.crd.yaml, .crd.yml, .yaml, .yml, .zip, .tar.gz, .tgz, .tar	Generic	Ready
ODCS Data Contract	odcs	Import + export	Catalog	file, url, paste, fileset	—	odcs	.odcs.yaml, .odcs.yml, .yaml, .yml, .json, .zip, .tar.gz, .tgz, .tar	Generic (reviewed)	Ready
RELAX NG	relaxng	Import only	Catalog	file, url, paste, fileset	—	relaxng, relaxng-compact	.rng, .rnc, .zip, .tar.gz, .tgz, .tar	Generic (reviewed)	Ready
SQL DDL	sql-ddl	Import only	Catalog	file, url, paste, fileset	—	sql-ddl	.sql, .ddl, .psql, .mysql, .tsql, .pgsql, .zip, .tar.gz, .tgz, .tar	Generic (reviewed)	Ready
XSD	xsd	Import + export	Catalog	file, url, paste, fileset	—	xsd, xmlschema	.xsd, .zip, .tar.gz, .tgz, .tar	Generic	Ready

Agent

Format	Key	Direction	Publishable	Input kinds	Live discovery	Format keys	File extensions	Analysis	Runtime
LLM Tools	llm-tools	Import + export	Catalog	file, url, paste, fileset	—	llm-tools	.tools.json, .llm-tools.json, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready
MCP Server Manifest	mcp	Import only	Catalog	file, url, paste, fileset	—	mcp	.mcp.json, .json, .zip, .tar.gz, .tgz, .tar	Generic	Ready

Version coverage

Which versions of each format Apiome reads and writes, from the source-format capability registry (GET /v1/import/format-capabilities → version_coverage, also on every matrix row under capability.version_coverage).

This table is evidence, not intent: a conformance suite requires a corpus example that detects at every listed read version and a round-trip matrix row for every listed write version, so a version cannot be claimed here without a fixture that demonstrates it.

A version marked * is qualified — reached through a projection or a downgrade, or not gated on a version marker at all because the format carries none. Every qualified version's reason is listed under the table. How completely a format's constructs are modelled is a different question, answered by Format boundaries below.

Format	Key	Reads	Writes	Default export
Apache Arrow	arrow	Arrow columnar format 1.x (IPC metadata V4/V5)*	—	—
API Blueprint	apiblueprint	1A	1A	1A
Arazzo	arazzo	1.1.x, 1.0.x	1.1.0*, 1.0.1	1.0.1
ASN.1	asn1	X.680 module syntax*	X.680 module syntax*	X.680 module syntax
AsyncAPI	asyncapi	3.1.0, 3.0.0, 2.6.0	3.1.0, 2.6.0*	3.1.0
Avro	avro	Avro schema declaration (.avsc), Avro IDL (.avdl)	Avro schema declaration (.avsc)*	Avro schema declaration (.avsc)
Cap'n Proto	capnproto	Cap'n Proto schema language*	Cap'n Proto schema language*	Cap'n Proto schema language
CDDL	cddl	RFC 8610 (with RFC 9165 control operators)*	RFC 8610 (with RFC 9165 control operators)*	RFC 8610 (with RFC 9165 control operators)
CloudEvents	cloudevents	1.0	1.0	1.0
COBOL Copybook	cobolcopybook	COBOL data-division record layout*	COBOL data-division record layout*	COBOL data-division record layout
Connect RPC	connectrpc	proto2 / proto3 (.proto)*	proto3 (.proto)*	proto3 (.proto)
CORBA IDL	corbaidl	OMG IDL*	OMG IDL*	OMG IDL
dbt Project	dbt	dbt properties version: 2, dbt manifest v7-v12 (dbt 1.0 - 1.9)	—	—
DTD	dtd	XML 1.0 DTD*	—	—
EDI X12	edix12	X12 interchange (004010, 005010, …)*	X12 interchange (004010, 005010, …)*	X12 interchange (004010, 005010, …)
FHIR	fhir	R4	R4	R4
FIX	fix	tag=value message (any BeginString)*	tag=value message (any BeginString)*	tag=value message (any BeginString)
FlatBuffers	flatbuffers	FlatBuffers schema (.fbs)*	FlatBuffers schema (.fbs)*	FlatBuffers schema (.fbs)
Gateway API HTTPRoute	gateway-api	v1, v1beta1	v1, v1beta1*	v1
Google API Discovery	discovery	Discovery Document v1 (rest)	—	—
GraphQL	graphql	SDL (October 2021)*	SDL (October 2021)*	SDL (October 2021)
gRPC / Protobuf	grpc	Editions 2023 / 2024, proto2 / proto3 (.proto)	proto3 (.proto)	proto3 (.proto)
HL7 v2	hl7v2	2.x message (any MSH-12)*	2.x message (any MSH-12)*	2.x message (any MSH-12)
HTTP Request File	http-file	.http / .rest request file and cURL snippet*	.http / .rest request file and cURL snippet*	.http / .rest request file and cURL snippet
ISO 20022	iso20022	message XML (any message definition)*	message XML (any message definition)*	message XML (any message definition)
ISO 8583	iso8583	MTI + data-element field map (any release)*	MTI + data-element field map (any release)*	MTI + data-element field map (any release)
JSON Schema	json-schema	2020-12, other $schema dialects (draft-07, 2019-09, …)*	2020-12	2020-12
JSON Type Definition	jtd	RFC 8927	RFC 8927	RFC 8927
Kafka Connect Schema	kafka-connect	Kafka Connect schema form*	Kafka Connect schema form*	Kafka Connect schema form
Kong Declarative Config	kong	deck _format_version 3.0, deck _format_version 2.1, deck _format_version 1.1	deck _format_version 3.0, deck _format_version 2.1*, deck _format_version 1.1*	deck _format_version 3.0
Kubernetes CRD	k8s-crd	apiextensions.k8s.io/v1, apiextensions.k8s.io/v1beta1*	apiextensions.k8s.io/v1	apiextensions.k8s.io/v1
LLM Tools	llm-tools	OpenAI / Anthropic / bare tool array*	OpenAI / Anthropic / bare tool array*	OpenAI / Anthropic / bare tool array
MCP Server Manifest	mcp	server manifest (any protocolVersion)*	—	—
OData	odata	4.0, 3.0*, 2.0*	4.0	4.0
ODCS Data Contract	odcs	ODCS v3.x (v3.0, v3.1)	ODCS v3.1.0, ODCS v3.0.2	ODCS v3.1.0
ONC RPC	oncrpc	rpcgen (RPCL) definition*	rpcgen (RPCL) definition*	rpcgen (RPCL) definition
OpenAPI / Swagger	openapi	3.2, 3.1, 3.0, 2.0, 1.2*	3.1.0, 3.0.3*, 2.0*	3.1.0
OpenRPC	openrpc	1.x*	1.x*	1.x
Postman	postman	Collection v2.1, Collection v2.0	Collection v2.1	Collection v2.1
RAML	raml	1.0	1.0	1.0
RELAX NG	relaxng	RELAX NG XML syntax (.rng), RELAX NG compact syntax (.rnc)	—	—
Smithy	smithy	2.0	2.0	2.0
SQL DDL	sql-ddl	SQL DDL (ANSI plus PostgreSQL, MySQL, SQL Server, Oracle)*	—	—
Thrift	thrift	Thrift IDL*	Thrift IDL*	Thrift IDL
TypeSpec	typespec	TypeSpec (.tsp)*	TypeSpec (.tsp)*	TypeSpec (.tsp)
WADL	wadl	2009-02-09	2009-02-09	2009-02-09
WIT (WebAssembly)	wit	Component Model WIT (0.2 surface)	Component Model WIT (0.2 surface)	Component Model WIT (0.2 surface)
WSDL	wsdl	1.1, 2.0	1.1	1.1
XML-RPC	xmlrpc	1.0	1.0	1.0
XSD	xsd	1.0 / 1.1*	1.0	1.0
z/OS Connect	zosconnect	API requester / provider descriptor*	API requester / provider descriptor*	API requester / provider descriptor

Where support is qualified (*)

Apache Arrow

• Reads Arrow columnar format 1.x (IPC metadata V4/V5) (ungated) — An Arrow schema carries no version the reader branches on. The columnar format's releases add types, not a schema dialect — a field naming a type this reader does not know is rejected as a semantic error rather than routed to a second grammar — and the IPC metadata version is resolved inside the Flatbuffer reader. The JSON integration form, a binary IPC stream or file, and a Flight GetSchema reply are three serializations of one schema, not three versions of it.

Arazzo

• Writes 1.1.0 (partial) — Written only when the model carries an asynchronous source description, which 1.0 cannot express; every other model is written as 1.0.1.

ASN.1

• Reads X.680 module syntax (ungated) — An ASN.1 module states no standard edition, so one module grammar is read and no X.680 revision is branched on.
• Writes X.680 module syntax (ungated) — The written module states no standard edition either, for the same reason.

AsyncAPI

• Writes 2.6.0 (partial) — Written by downgrading the 3.1 document (asyncapi_version='2.6'); 2.6 is the last and most capable 2.x minor, so it is the only 2.x target offered.

Avro

• Reads Avro schema declaration (.avsc) (ungated) — An Avro schema declaration carries no Avro release marker, so one grammar is read for every release.
• Reads Avro IDL (.avdl) (ungated) — The IDL surface carries no version marker either; both surfaces build the same AST, so a protocol reads identically in either spelling.
• Writes Avro schema declaration (.avsc) (ungated) — The .avdl spelling is produced by the same writer through the output_syntax emit option, so the two cannot disagree about meaning.

Cap'n Proto

• Reads Cap'n Proto schema language (ungated) — A .capnp schema declares no language version, so one grammar is read.
• Writes Cap'n Proto schema language (ungated) — The written schema declares no language version either.

CDDL

• Reads RFC 8610 (with RFC 9165 control operators) (ungated) — A CDDL grammar states no version of its own — RFC 8610 has had one grammar since 2019 and RFC 9165 only added control operators to it — so one reader covers every document, and a grammar that uses .lt/.ne reads identically to one that does not.
• Writes RFC 8610 (with RFC 9165 control operators) (ungated) — The written grammar states no version either, for the same reason; an RFC 9165 operator is written only when the source used one.

COBOL Copybook

• Reads COBOL data-division record layout (ungated) — A copybook names no COBOL standard, so level numbers, PICTURE and USAGE are read without branching on a dialect.
• Writes COBOL data-division record layout (ungated) — The written layout names no COBOL standard either.

Connect RPC

• Reads proto2 / proto3 (.proto) (ungated) — Connect reuses the Protocol Buffers contract, so the readable surface is the .proto grammar rather than a Connect protocol version.
• Writes proto3 (.proto) (ungated) — Written as a standard proto3 bundle labelled for Connect; the Connect protocol version is a runtime concern the contract does not state.

CORBA IDL

• Reads OMG IDL (ungated) — An .idl file declares no OMG IDL revision, so one grammar is read.
• Writes OMG IDL (ungated) — The written definition declares no OMG IDL revision either.

DTD

• Reads XML 1.0 DTD (ungated) — A DTD carries no version marker of its own — it is part of the XML 1.0 grammar, and XML 1.1 did not change it — so one reader covers every document. An external subset, an internal subset and a modular set composed through parameter entities are three placements of one grammar, not three versions of it.

EDI X12

• Reads X12 interchange (004010, 005010, …) (ungated) — The control version the interchange declares (ISA12, GS08) is recorded, but the segment grammar read is the same for every release and no implementation-guide conformance is evaluated.
• Writes X12 interchange (004010, 005010, …) (ungated) — The written interchange carries whatever control version the model records; the emitter does not target a release of its own.

FIX

• Reads tag=value message (any BeginString) (ungated) — The session version the message declares (tag 8, FIX.4.4…) is recorded, but the tag=value grammar read is the same for every version and no data dictionary is applied.
• Writes tag=value message (any BeginString) (ungated) — The written message carries whatever BeginString the model records.

FlatBuffers

• Reads FlatBuffers schema (.fbs) (ungated) — An .fbs schema declares no language version, so one grammar is read.
• Writes FlatBuffers schema (.fbs) (ungated) — The written schema declares no language version either.

Gateway API HTTPRoute

• Writes v1beta1 (partial) — Targeted with the api_version emit option; the document is otherwise identical to the v1 output, since HTTPRoute is unchanged between the two.

GraphQL

• Reads SDL (October 2021) (ungated) — A GraphQL document carries no specification-edition marker; schemas written against earlier editions parse identically.
• Writes SDL (October 2021) (ungated) — The written SDL carries no specification-edition marker either.

HL7 v2

• Reads 2.x message (any MSH-12) (ungated) — The version the message declares (MSH-12) is recorded, but the segment / field grammar read is the same for every 2.x release and no message-profile conformance is evaluated.
• Writes 2.x message (any MSH-12) (ungated) — The written message carries whatever version the model records.

HTTP Request File

• Reads .http / .rest request file and cURL snippet (ungated) — Neither the VS Code nor the JetBrains request-file dialect is versioned; both are read by one grammar and every construct is recorded as inferred.
• Writes .http / .rest request file and cURL snippet (ungated) — The dialect emit option chooses the VS Code or JetBrains spelling and output='curl' writes a shell script instead; none of the three is a version.

ISO 20022

• Reads message XML (any message definition) (ungated) — The message-definition identifier the document declares (pain.001.001.09) is recorded, but the reader does not branch on it and no message-definition schema is applied.
• Writes message XML (any message definition) (ungated) — The written message carries whatever message-definition identifier the model records.

ISO 8583

• Reads MTI + data-element field map (any release) (ungated) — The release an MTI implies (1987, 1993, 2003) is not branched on; one field-map grammar is read and no institution's dialect is applied.
• Writes MTI + data-element field map (any release) (ungated) — The written field map carries whatever MTI the model records.

JSON Schema

• Reads other $schema dialects (draft-07, 2019-09, …) (partial) — Accepted and kept verbatim for later conversion; the canonical projection reads $defs/definitions and the root schema, so dialect-specific keywords survive in the retained source and nowhere else.

Kafka Connect Schema

• Reads Kafka Connect schema form (ungated) — Connect's schema form carries no dialect version the reader branches on — a schema's integer version is the revision a registry assigned to that subject, not a spelling of the format — so one grammar is read for every Connect release. The {schema, payload} converter envelope and a pipeline file set are two packagings of the same schema, not two versions of it.
• Writes Kafka Connect schema form (ungated) — The writer produces the same one grammar the reader accepts, and every emitted document is read back through that reader before it leaves the emitter.

Kong Declarative Config

• Writes deck _format_version 2.1 (partial) — Targeted with the format_version emit option; only the declared _format_version changes, since deck's document shape is the same across the three.
• Writes deck _format_version 1.1 (partial) — Targeted with the format_version emit option, on the same terms as 2.1.

Kubernetes CRD

• Reads apiextensions.k8s.io/v1beta1 (partial) — Claimed by detection — every apiextensions.k8s.io/* group version is — and read through the v1 structural-schema path, which the deprecated v1beta1 validation block does not populate.

LLM Tools

• Reads OpenAI / Anthropic / bare tool array (ungated) — A tool array carries no version; the dialect is detected per tool and a mixed array is accepted, each tool recording the dialect it was read as.
• Writes OpenAI / Anthropic / bare tool array (ungated) — The mode emit option chooses the openai, anthropic or bare spelling; none of the three is a version.

MCP Server Manifest

• Reads server manifest (any protocolVersion) (ungated) — The protocol version the manifest declares is recorded, but detection and normalization do not branch on it; the conformance pack states which specification revision its rules were written against.

OData

• Reads 3.0 (partial) — Read by projecting the v3 CSDL onto the v4 model (FMT-3.4): associations become navigation properties, and constructs v4 dropped survive only in the retained source.
• Reads 2.0 (partial) — Read by projecting the v2 CSDL onto the v4 model, on the same terms as v3.

ONC RPC

• Reads rpcgen (RPCL) definition (ungated) — A .x file declares no RPCL revision, so one grammar is read; the program and procedure version numbers it declares are data, not a format version.
• Writes rpcgen (RPCL) definition (ungated) — The written definition declares no RPCL revision either.

OpenAPI / Swagger

• Reads 1.2 (partial) — Read by projecting the resource listing and its API declarations onto the 2.0 path (FMT-3.6). Swagger 1.0 and 1.1 share the swaggerVersion marker but not the grammar, and are rejected as FORMAT_VERSION_UNSUPPORTED rather than mis-read as 1.2.
• Writes 3.0.3 (partial) — Written by downgrading the 3.1 document (openapi_version='3.0'); what the 3.0 dialect cannot carry is reported as a loss rather than dropped silently.
• Writes 2.0 (partial) — Swagger 2.0, written by downgrading the 3.1 document (openapi_version='2.0'), on the same terms as 3.0.

OpenRPC

• Reads 1.x (ungated) — The openrpc version marker is recorded and re-emitted, but detection and normalization read one document grammar and do not branch on the minor.
• Writes 1.x (ungated) — The written document declares the version the model records, defaulting to 1.2.6 when it records none.

RELAX NG

• Reads RELAX NG XML syntax (.rng) (ungated) — RELAX NG has had one specification since 2001 and a grammar carries no release marker, so one reader covers every document.
• Reads RELAX NG compact syntax (.rnc) (ungated) — The compact syntax is a second spelling of the same language, read by a second front-end onto the same pattern algebra, so a grammar reads identically in either spelling.

SQL DDL

• Reads SQL DDL (ANSI plus PostgreSQL, MySQL, SQL Server, Oracle) (ungated) — A DDL script carries no version marker of its own. It does not declare which SQL it is written in, and the ISO revisions (SQL:1999 through SQL:2023) add syntax without renumbering anything a CREATE TABLE says, so there is no version for a reader to branch on. What a script does carry is a vendor accent, and that is resolved instead: the dialect is detected from the script's own markers, recorded in provenance beside the markers that decided it, and forced by the sql_dialect import option when a user knows better. A script with no vendor marker is read as ANSI. The vendor constructs one dialect has and the others do not are construct-level boundaries, so they are declared in the capability registry's unsupported_constructs, not here.

Thrift

• Reads Thrift IDL (ungated) — A .thrift file declares no compiler release, so one grammar is read.
• Writes Thrift IDL (ungated) — The written document declares no compiler release either.

TypeSpec

• Reads TypeSpec (.tsp) (ungated) — A .tsp file declares no language version, so one grammar is read and no compiler release is targeted.
• Writes TypeSpec (.tsp) (ungated) — The written definition declares no language version either.

XSD

• Reads 1.0 / 1.1 (ungated) — Both XSD versions share one namespace and no vc:minVersion gate is read, so a 1.1 document is accepted; its 1.1-only constructs (assertions, conditional type assignment) are not modelled.

z/OS Connect

• Reads API requester / provider descriptor (ungated) — A z/OS Connect descriptor states no product version, so one document shape is read for both the requester and the provider flavour.
• Writes API requester / provider descriptor (ungated) — The written descriptor states no product version either.

Format boundaries

What these formats knowingly do not model, from the source-format capability registry (GET /v1/import/format-capabilities). Only reviewed entries appear: every other format's entry is derived from its adapter's own declarations, which is not a reviewed claim about boundaries and is not presented as one here.

Apache Arrow

• The three surfaces are one reader. The JSON integration form, a binary IPC stream or file, and a Flight GetSchema reply all parse into the same document type before anything is normalized, so an IPC schema and its JSON twin produce the same canonical model — the same types, the same keys, the same fingerprint — rather than two models that resemble each other.
• The model's identity is derived from the document, never from the filename: a Flight descriptor's path names the dataset, a name in the schema metadata names it otherwise, and a schema that names itself nothing is called Schema. That is what lets the same table imported from two serializations be one API.
• Schema and field metadata are carried verbatim, and the conventional documentation keys (description, comment, doc) become descriptions. Arrow defines no documentation construct, so a schema whose columns are undocumented imports undocumented — the absence is the format's, not the reader's.
• A live Flight endpoint is vetted against the SSRF policy before a client is constructed, and its credentials come from the shared credential vault as call headers. Nothing else is fetched: a schema names no external references.
• Arrow output is not implemented here (#4317 files the Parquet/Arrow emitter), so a schema imported through this adapter is exported through another target's emitter and is not written back as Arrow.

CDDL

• CDDL is read and written. The reader records each construct's source spelling — which prelude type a leaf used, a tag, an unmapped control operator, whether a record came from a map or an array — in extras, and the emitter writes every one of them back, so a grammar imported and re-exported is the grammar that arrived rather than a re-derivation of it.
• Sockets, plugs and generics are composition, and are resolved before normalization: a type socket's /= plugs become a choice, a group socket's //= plugs become a group choice, and a generic rule is instantiated once per distinct argument list. Instantiation is bounded and refuses to re-enter an identical instantiation, so a self-instantiating generic fails rather than running.
• CDDL has no include directive, so a grammar split across files composes as a fileset: the members are loaded together into one namespace. A reference that resolves in no member fails the import naming the missing rule, rather than being read as an open type — which would silently produce a smaller grammar than the author wrote.
• The ; comment is CDDL's only documentation construct and binds to nothing. A comment block written directly above a rule becomes that rule's description, the same block separated by a blank line becomes the document's, and a comment sharing a line with a member becomes that member's. Anything else is left unattached rather than guessed at.

COBOL Copybook

• Byte offsets and lengths are computed from PICTURE and USAGE under assumptions the copybook does not state — a single-byte encoding, packed decimal at two digits per byte plus a sign nibble, the common binary width table, an overpunched rather than separate sign, and no SYNCHRONIZED slack. Every record names them, so a length is read as conditional rather than observed.
• An item whose PICTURE cannot be sized has no length, and nothing after it has an offset. An item after a variable-length table has a range of offsets rather than an offset, and carries none — a minimum presented as the offset would be worse than no answer.
• Level-66 RENAMES and COPY ... REPLACING are not read by the parser. They are detected by scanning the source, and each one found makes the record partial with a stated reason rather than presenting a partial layout as a complete one.

dbt Project

• Both of dbt's descriptions of a project read into one model: a hand-written schema.yml properties file and the manifest.json dbt compiles from it. A manifest hoists every test into a node of its own, and this reader re-attaches each one to the column it constrains, so the two surfaces produce comparable canonical models rather than two shapes.
• A dbt project is a directory, so a file set is the format's ordinary shape rather than an include mechanism: dbt_project.yml names the project, every properties file contributes to one resource namespace, and each model's .sql contributes the ref()/source() calls in it as that model's lineage. The SQL is read for those calls only — it is never compiled, executed, or otherwise interpreted.
• Lineage is recorded, not traversed. A relationships test and a foreign_key constraint are the two edges this reader writes down, so one that names a model the import does not contain is refused as INPUT_REFERENCE_UNRESOLVED rather than silently dropped. Every other ref() — a semantic model's model:, an exposure's depends_on, a call in a member's SQL — is recorded as unresolved and carried, because an import is one file or one file set and a project's upstream commonly lives outside it.
• A project that describes no data is refused rather than imported: a properties file with a version: 2 marker and no models, sources, seeds, snapshots or semantic models would produce an empty catalog entry, which reads as 'this project has no tables' rather than as 'this document did not say'.
• dbt output is not implemented, and is not planned. dbt owns its own project files, they are under version control, and writing one back would put a second author on a directory that already has one. A project imported here is exported through another target's emitter.

DTD

• A DTD is not XML and is not read by an XML parser: <!ELEMENT>/<!ATTLIST> are markup declarations, and the shared hardened XML reader refuses a DOCTYPE outright. The reader is a scanner with its own byte, nesting and entity-expansion ceilings, and it reads an external subset, an internal subset, and a modular set composed through parameter entities by the same path.
• Entity expansion is bounded in three dimensions at once — how many references are expanded, how many bytes they produce, and how deep the expansion nests — and every reference is charged against one budget, so a document cannot move work between the parameter-entity and general-entity mechanisms to spend past a guard. An entity that re-enters its own expansion chain is refused as an unsafe construct rather than unrolled until a budget stops it.
• Nothing external is fetched. A relative system identifier resolves against the uploaded set; an absolute one is vetted against the SSRF policy — a file:/data: identifier, or one carrying credentials, fails the import — and a policy-legal http(s) identifier is recorded as a declared limit whose declarations are absent. This is the XXE and blind-XXE shape, and it fails closed.
• A DTD has no documentation construct: comments are not attached to the declarations they precede, so imported types and members carry no description and the absence is the format's, not the reader's.
• DTD output is not implemented, so a DTD imported here is exported through another target's emitter and is not written back as a DTD.

EDI X12

• An element position the source wrote and left empty is recorded as present with a zero length; a position the source never wrote is not recorded at all. The two are different facts about the payload and are never rendered as one.
• HL loops are described as the segments they are, not as the hierarchy they encode. Where the interchange declares a repetition separator (ISA11 at 00501 and later, never at 00401) a repeated element carries its occurrences and states how many.
• Control totals declared by the SE, GE and IEA trailers are recorded beside the counts actually observed, so an interchange that disagrees with itself can be seen to. The trailer segments themselves are not tree nodes, and TA1 acknowledgements are removed by the parser before the analysis runs.
• No 4010/5010 implementation-guide conformance is evaluated — a structurally valid interchange is not claimed to be a conformant one, and an ST03 implementation convention reference is recorded as the sender's claim rather than as a checked fact.

gRPC / Protobuf

• The compiled descriptor set is the artifact of record, not the .proto text: imports, option inheritance and Editions feature resolution are the compiler's answers, never a re-parse here. A document that does not compile has no analysis at all, which is reported as a compile failure rather than as an empty source.
• Editions feature resolution is ours, not the compiler's: buf build writes each scope's raw features override into the descriptor and leaves the merge to the reader, so the resolved values reported here are computed from the edition's own defaults table as published in descriptor.proto.
• A type a target file references but an import declares (google.protobuf.Timestamp, a sibling module's message) is carried as a reference with no local definition. That is the shape a protobuf import has, not a resolution failure.
• Custom options and extension declarations are preserved in the descriptor set and in the retained source, and only there — the canonical model has no vocabulary for a user-defined option, so it is neither named nor counted.

Kafka Connect Schema

• Connect's schema form is neither Avro nor JSON Schema, and telling it from Avro is the reader's first job: Connect names a struct member with field, Avro with name. An Avro schema routed to this adapter is refused without a taxonomy code so the pipeline reports it as a wrong-format upload on the strength of the Avro adapter claiming it, rather than as a malformed Connect document.
• A logical type this reader does not decode is still recognized as a logical type. The field keeps its base type's canonical scalar and the name is carried verbatim, so a connector-specific semantic is never silently reduced to its wire representation — what is lost is the canonical constraint the name would imply, and that loss is counted.
• A connector configuration is operational, not structural. It states how a pipeline runs — connector.class, converters, transforms, sink settings — and is carried verbatim; the key and value schemas beside it in the file set are what becomes structure. Imported on its own it is refused, because it describes no record.
• Kafka Connect output is implemented (FMT-5.3). The Connect spellings the reader carried are written back verbatim — an int8 returns as int8 and a logical type returns with its parameters — so a schema imported and re-exported is canonically identical. A model from any other format is projected instead: its canonical scalars pick Connect primitives, a canonical format picks a bundled logical type where Connect has one, and what Connect cannot carry is reported as a loss.
• Connect validates nothing — a schema states a type, not a value range — so every canonical constraint other than the two a logical type implies is dropped on export and reported. Connect also has no union and no enumeration type, and this emitter does not invent a connector-specific logical type to fake one.

ODCS Data Contract

• The reader covers the ODCS v3.x line, and only that line. A v2.2.x contract declares the same apiVersion/kind pair but spells a dataset as quantumName with dataset[].columns[], so it is claimed by detection and then rejected by version, with the v2 -> v3 renames named in the message — never parsed into an empty contract.
• A contract that describes no structure is refused rather than imported: a schema[] object with no properties would produce an empty catalog type, which reads as 'this dataset has no columns' rather than as 'this document did not say'.
• authoritativeDefinitions URLs are recorded and never fetched during import. A relative URL naming a member of the same imported file set is additionally recorded as resolved, but its content is not expanded — a JSON Schema a contract delegates its payload shape to stays a reference, not a set of canonical types.
• Quality rules are carried, never executed and never translated into constraints. A sql rule's query, a custom rule's engine block and a text rule's prose are kept exactly as written, which is what lets the emitter write them back unchanged.
• ODCS output is implemented (FMT-5.2), and it is the one target in the fleet whose emitted artifacts are checked against the format's own published JSON Schema, shipped with this service and run offline. The governance half is written back from the odcs_* extras verbatim, so a contract imported and re-exported is canonically identical. The structural half is rebuilt, and the emitter refuses to write a facet the standard does not admit beside the column's logicalType — a non-standard enum type option is dropped and reported rather than written illegally.
• Nothing in the governance half is ever invented on export. A contract emitted from a schema that carries no ownership, SLA or quality metadata is written without those blocks, and their absence is reported as a SYNTH finding: a fabricated owner or service level is a governance claim nobody made. The only values supplied without a source are version and status, which the standard requires for a document to exist at all, and both are reported as fabricated.

RELAX NG

• The XML syntax (.rng) and the compact syntax (.rnc) are two spellings of one language and are read by two front-ends onto one pattern algebra, so the same grammar written either way produces the same canonical model — the syntax is deliberately not part of the model, and survives only on the retained raw source.
• An include/externalRef naming an absolute URL is never fetched. Its shape is vetted against the SSRF policy — a file:/data: href, or one carrying credentials, fails the import as an unsafe construct — and a policy-legal http(s) href is recorded as a declared limit whose definitions are absent, which then surfaces as an unresolved reference rather than as a silently smaller grammar.
• RELAX NG output is not implemented (#4134), so a grammar imported here is exported through another target's emitter and is not written back as RELAX NG.

SQL DDL

• A DDL script is a sequence of edits, and the import is the state they leave behind. CREATE TABLE introduces a relation, ALTER TABLE changes one, DROP removes one, and a migrations directory is simply more of the same statements in later files, applied in path order. That is why a migrations set imports as its final state rather than its first, and why the same code path reads one script with ALTER statements in it.
• The dialect is detected from the script's own markers — backticks and AUTO_INCREMENT for MySQL, a bare GO and IDENTITY(1,1) for SQL Server, VARCHAR2 and NOCACHE for Oracle, timestamptz and INHERITS for PostgreSQL — and is recorded in provenance with the markers that decided it. A script with no vendor marker is read as ANSI, which is a verdict rather than a guess. The sql_dialect import option forces one, for the cases a user can see and a marker cannot.
• Live introspection against a connection string is out of scope and not planned. An import is a file or a file set; no driver is loaded and no socket is opened. That keeps the security surface of 'read my schema' to the surface of 'read my file'.
• A foreign key is an edge this reader writes down, so one that names a table the import does not contain is refused as INPUT_REFERENCE_UNRESOLVED rather than silently dropped — the same rule FMT-5.4 applies to a dangling relationships test. Import the whole schema dump or the whole migrations directory so the referenced table is present.
• A script in which nothing has a shape — every CREATE TABLE has an empty column list, or there is no relation at all — is refused rather than imported: it would produce a catalog entry that reads as 'this database has no tables' rather than as 'this document did not say'. A single column-less table beside real ones is kept as an empty record, because PostgreSQL allows CREATE TABLE t () and the script did declare the relation.
• SQL DDL output is filed separately as #4311. This adapter is the import half only, and the two share one type-mapping table (app.sql_ddl_dialects.SQL_TYPE_SCALARS) so a round trip cannot disagree with itself about what a VARCHAR is.

Related

• Import a specification
• Export a spec
• Catalog format details — what a catalog item records per format.
• Export fidelity — what survives a conversion between formats.