JSON Schema
Ajson_schema contract has an input and an output schema, both JSON Schema
draft 2020-12. The input is one JSON value and so is the output, on the API and
on the function’s stdin and stdout alike. Over HTTP the content type is
application/json.
$ref may point inside its own document,
and one that points anywhere else fails the version instead of reading a file
or a URL.
Arrow
Anarrow contract types the boundary with Arrow schemas, for functions that
work on a batch of rows at a time. input_schema and output_schema are each
an Arrow IPC stream holding only the schema message, such as pyarrow’s
schema.serialize(). Over HTTP the content type is
application/vnd.apache.arrow.stream.
An input or output is an Arrow IPC stream holding exactly one record batch. Its
schema is matched against the contract field by field:
- Names and types must be equal. Field metadata is ignored.
- A field the contract marks nullable accepts a non-nullable column. A nullable column where the contract says non-nullable is a violation.
- For list types, the child field’s name and nullability are ignored, since Arrow libraries disagree on their defaults.
Where checks happen
The server compiles the contract when a version is created, and a contract that does not compile isINVALID_ARGUMENT. Hosts check every invocation, in
internal/contract, and keep each compiled contract in memory.
- The host takes the invocation from the queue and checks the input. An input that breaks the contract ends the invocation here. No microVM is acquired and the function never runs.
- The function runs and writes its output to stdout.
- The host checks the output against the contract and the size limit. What passes is what the caller receives, byte for byte.
Violations
Each violation names where it is.instancePath is a JSON Pointer into the
value, schemaPath one into the schema, and message says what is wrong. Arrow
violations carry a message only, plus schemaPath rows when the row counts
differ.
An input violation is the caller’s mistake. The invocation is REJECTED and the
call fails with INVALID_ARGUMENT, one ContractViolation error detail per
violation. Over HTTP it is a 400 with the violations in the body:
FAILED with
a function error of kind FUNCTION_ERROR_KIND_OUTPUT_INVALID and the violations
in it. Over HTTP a sync call answers 500 with that error as its JSON body.
Content types and size limits
A call over HTTP must carry the content type its version’s contract takes. Any other is a 415.
Inputs and outputs over 8 MiB still work: they travel between servers and hosts
through a NATS object store instead of inside the queue message.