Arrow IPC schema documents

Export one contract asset schema without opening its dataset:

packata schema export contract.yaml --asset orders --output-format arrow-ipc -o orders.schema.ipc
packata schema export contract.yaml --asset orders --output-format arrow-ipc > orders.schema.ipc

--asset is optional only when exactly one asset has a declared schema. Output filenames do not select a format. There are no --arrow aliases or Arrow IPC compatibility profiles. --target, --language, templates and naming options belong to schema generate and are rejected by export. Existing output files and the source descriptor are protected. An interactive terminal requires -o; redirected stdout receives only raw bytes, without a BOM, banner, text encoding or trailing newline. Diagnostics go to stderr. Use a byte-preserving shell redirection (PowerShell 7.4+, cmd, or a POSIX shell); older shells may decode native stdout as text. Export exit codes follow the CLI conventions: 0 success, 1 invalid document/mapping, 2 invalid invocation, 3 I/O failure and 130 cancellation.

Encoding and readers

The artifact is one encapsulated Arrow IPC Schema message, equivalent in purpose to pyarrow.Schema.serialize(). It contains no record batches, stream end marker, file footer, Feather envelope or data. Packata.Arrow.ArrowSchemaSerializer uses Apache.Arrow 23.0.0 ArrowStreamWriter.WriteStartAsync and disposes the writer without writing batches or WriteEndAsync. IPC framing is generated by the supported Arrow API.

Python 3.10+ with PyArrow 23+:

import pyarrow as pa

with open("orders.schema.ipc", "rb") as source:
    schema = pa.ipc.read_schema(source)
    assert not source.read()  # exactly one schema message
print(schema)

.NET with Apache.Arrow 23.0.0:

using Apache.Arrow.Ipc;

using var source = File.OpenRead("orders.schema.ipc");
using var reader = new ArrowStreamReader(source);
var schema = await reader.GetSchema();
Console.WriteLine(schema.FieldsList.Count);

The Arrow encapsulated message specification and PyArrow Schema API define the portable representation. Schema export does not materialize records, generate code, create tables or start a Flight service.

Shared projection and diagnostics

SchemaDocumentService.Formats is the Application catalog for document export, distinct from the generation target/language catalog. It declares arrow-ipc as binary with suggested extension .schema.ipc, alongside text json-schema. ExportAsync returns a completed SchemaDocumentResult containing either bytes or text and structured diagnostics. Mapping and serialization finish in memory before hosts publish any artifact. Cancellation discards the result; CLI file publication writes a sibling temporary file and moves it without overwrite, cleaning up on failure. Cancellation during raw stdout I/O may leave a truncated pipe; a nonzero exit status and a failed schema read must be treated as failure.

Both Arrow code targets and this serializer use ArrowSchemaProjection, outside Core. They retain field order/names, nesting, nullability, supported schema/field string metadata, decimal precision/scale, and temporal units/zones. See schema generation for the complete mapping profile. Decimal precision and scale must be explicit; values outside decimal256 capacity, unsupported types, ambiguous temporal offsets, malformed metadata and unavailable dictionary/extension representations fail with diagnostics. Canonical arrow namespace metadata is retained. Dictionary encoding is not inferred from categories. Arrow extension metadata is rejected until a dedicated registered adapter can preserve its meaning. Required presence remains separate as packata.required metadata; Arrow does not validate absent fields, uniqueness or all contract constraints.

Editor artifact flow

The contract/asset context menu declares Export Schema > Arrow IPC…. Its capability and representation come from the Application catalog via LanguageServer. Binary bytes travel as base64 in JSON-RPC and are decoded only for an explicit save dialog; they never open in a UTF-8 text editor. The extension writes a temporary file and renames without overwrite. It preserves clicked asset scope and unsaved source versions and discards cancelled, stale or mismatched responses. Text document exports open untitled previews. Other Formats… uses the same operation-filtered catalog. C# and Python Arrow schemas are separate source-code commands under Generate Schema Code > C#/Python > Arrow Schema…; the commands validate their exact target/language pair against the generation catalog. Unavailable catalog entries are hidden, including after server disconnects.

LanguageServer advertises the shared packata.schema.options, packata.schema.catalog and packata.schema.export commands, with schema version 1. Export requires the source URI, version, selection hash, optional clicked source path, and options selecting outputFormat: "arrow-ipc". Results include representation, suggested filename, diagnostics and binaryContent (base64 on JSON transport) or text content. The schema-document commands remain available for clients using that protocol. No CLI process is spawned by editor operations.

Focused validation covers .NET/PyArrow round trips, comparison with generated Python, exact single-message boundaries, nested/decimal/temporal/nullability/metadata/map fixtures, CLI binary stdout/file identity, protected files, removed/wrong-operation options, mapping failure without artifacts, cancellation, synchronized/unsaved LanguageServer snapshots, JSON-RPC base64 transport and editor atomic saving. Python checks use PACKATA_TEST_PYTHON and an optional test-local PYTHONPATH; ordinary production export never runs Python. Full repository test suites, interactive VS Code host checks and .NET 8/9 runtime checks were deferred; all solution target frameworks were built.