Skip to content
AggregaAggrega
Select language: English

Aggrega Wasm Parser Socket schema

Generated reference. Do not edit by hand — regenerate from the published JSON Schema.

Schema id: https://aggrega.ai/schemas/wasm-parse-v1beta1.schema.json

The wire shapes a parser plugin socket consumes (ParseInput) and emits (ParseOutput). A parser is a stateless, side-effect-free transformer that turns a foreign text representation into a canonical structured JSON tree, so any consumer in any language can read the tree without carrying its own language parser. A parser declares the formats it handles as parse: capabilities in its descriptor; the host hands it the bytes to parse and the format name, and it returns the tree plus optional diagnostics and source spans. The parser attaches no meaning to the tree beyond its syntax — the compiler pipes the tree through opaquely.

One of the following shapes

  • ParseInput
  • ParseOutput

Definitions

ParseInput

The payload a parser guest receives: the format name that selects how to read the bytes, the source bytes to parse, and an optional opaque options document the consumer supplies for parser-specific behavior.

PropertyTypeRequiredDescription
formatstringyesThe name of the source format to parse, matching one of the parser’s advertised parse: capabilities (for example hcl, toml, yaml, or json). The parser reads the bytes as this format.
bytesstringyesThe source bytes to parse. Each kit carries them in its own field type — raw where that type is a byte type, base64-encoded where it is a string the parser decodes to recover them — and the generated encoder converts between the field and the form the wire carries bytes in. The parser reads the recovered bytes as the named format.
optionsanynoAn opaque options document the consumer supplies for parser-specific behavior. The host pipes it through without interpreting it; the parser reads whatever shape it documents. Absent when the consumer supplies no options.

Additional properties are not permitted.

ParseOutput

The payload a parser guest returns: the canonical structured tree of the parsed source, plus any diagnostics the parse raised and any source spans locating tree nodes back to the original bytes.

PropertyTypeRequiredDescription
treeanyyesThe canonical structured view of the parsed source, as a JSON document. Here “JSON document” names the form of the value a parser produces — which is the substance of what parsing is for — and not the encoding the value travels in: the tree is a JSON document whatever wire this socket carries it on. The top level may be an object, an array, or a scalar, matching the parsed document’s own shape (a JSON file, for example, may parse to any of these). The host pipes the tree through opaquely, carrying it verbatim without interpreting its content.
diagnosticsDiagnostic[]noDiagnostics the parse raised — for example a syntax error or a warning. Absent when the parse produced none.
spansNodeSpan[]noSource spans locating tree nodes back to their position in the original bytes, so a consumer can map a finding on a tree node to a source location. Absent when the parser reports no spans.
errorstringnoA failure message set when the guest ran but could not complete the operation; absent on success. It is distinct from any diagnostics the output carries: diagnostics report issues found during a run that still produced a result, while error reports that the operation itself did not complete. The host surfaces a present error as a failed plugin invocation.

Additional properties are not permitted.

NodeSpan

A source span for one tree node: an RFC 6901 JSON Pointer addressing the node within the tree, paired with the span locating it in the original bytes.

PropertyTypeRequiredDescription
pointerstringyesAn RFC 6901 JSON Pointer into the tree, addressing the node this span locates.
spanSourceSpanyesThe span locating the addressed node in the original bytes.

Additional properties are not permitted.

SourceSpan

A span of the original source bytes: the byte offsets are the primary, exact location, and the line and column numbers accompany them for human-readable diagnostics.

PropertyTypeRequiredDescription
start_offsetintegeryesThe byte offset of the span’s first byte in the original source, zero-based.
end_offsetintegeryesThe byte offset one past the span’s last byte in the original source, so end_offset minus start_offset is the span’s length in bytes.
start_lineintegeryesThe line number of the span’s start, one-based, for human-readable diagnostics.
start_columnintegeryesThe column number of the span’s start, one-based, for human-readable diagnostics.
end_lineintegeryesThe line number of the span’s end, one-based, for human-readable diagnostics.
end_columnintegeryesThe column number of the span’s end, one-based, for human-readable diagnostics.

Additional properties are not permitted.

ParseSourceResponse

The parse-source host function’s reply: on success the canonical structured tree the resolved parser produced, on failure an error message. Exactly one of the two fields is populated. Failure is delivered in-band rather than by trapping, so a consumer guest carries a no-parser or a parse failure into its own diagnostics as a deterministic failure. This is the envelope a consumer socket receives when it asks the host to run a producer through the host; the request payload is a ParseInput.

PropertyTypeRequiredDescription
treeanynoThe canonical structured tree the resolved parser produced on success, as a JSON document carried verbatim; absent on failure. As on the parse output’s own tree, “JSON document” names the form of the value rather than the encoding it travels in.
errorstringnoThe failure message on failure, naming the format and the reason; absent on success.
hostfunc_error_codestring (enum)noThe machine-matchable failure identity on failure, drawn from the closed host-function error-code catalog, set beside the human error message; absent on success. That catalog is a fixed vocabulary naming the ways a host function can fail, and it is a different vocabulary from the halting conditions the compiler registers, whose identifiers a guest reports on a socket output as condition_code and condition_short_code — the key name says which of the two a value belongs to, so the two are never read as one set. A guest branches on this code without parsing the message, tolerating an absent code (older host) or an unrecognized one (newer host) by falling back to the message. Allowed values: "fetch_request_unreadable", "fetch_input_unavailable", "fetch_failed", "request_unreadable", "request_undecodable", "source_root_unavailable", "source_read_failed", "unknown_selection_op", "source_escape", "producer_consumption_reentry", "no_source_parser", "no_parser_for_format", "parse_failed"

Additional properties are not permitted.