Skip to content
AggregaAggrega
Select language: English

Aggrega Wasm-plugin shared diagnostic schema

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

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

The single diagnostic shape every Wasm socket shares. A plugin reports one entry per issue it raises; the host surfaces it. The shape is a superset: every socket populates the subset it uses and omits the rest, so a diagnostic from any socket is one uniform structure. severity is one of three values every socket shares — halt, warn, or info — so a diagnostic carries the same meaning whichever socket raised it.

Top-level type: object

Definitions

Diagnostic

One issue a diagnostic emitter raised: a severity, a human-readable message, an optional location, and optional emitter-specific fields. An emitter is a Wasm plugin socket or the compiler itself — both report on this one shape, so a reader interprets an entry the same way whichever raised it. Each populates the subset it uses and omits the rest: a parser sets a location span, an import sets code and source_ref, a publishing linter sets rule_id and classification, a governance verdict sets the build-outcome severity and message and may add any of code, rule_id, classification, source_ref, location and suggest, and a render advisory sets code, source_ref and a structured location.

PropertyTypeRequiredDescription
severitystring (enum)yesThe diagnostic’s severity, drawn from one closed set every socket shares. halt stops the build and names what to fix. warn surfaces alongside a build that still completes. info records the observation and leaves the build outcome unchanged. Every emitter reports from this one set, so a reader interprets a severity the same way whichever raised it. Allowed values: "halt", "warn", "info"
messagestringyesThe human-readable diagnostic text.
codestringnoAn optional stable, machine-matchable code for the diagnostic, independent of the human-readable message. Absent when the emitter assigns no code. A code may come from a plugin socket or from the compiler’s own advisories, which set one on every entry they raise.
rule_idstringnoThe identifier of the rule that produced the diagnostic, when the emitter is rule-based (a publishing linter). Absent otherwise.
classificationstring (enum)noA semantic-version-impact classification the diagnostic carries, when the emitting rule assigns one (a schema-evolution rule). Absent for diagnostics that carry no classification. Allowed values: "PATCH", "MINOR", "MAJOR"
source_refstringnoAn opaque reference to the source element the diagnostic concerns (for example the identifier of a source node an import could not resolve). Absent when the diagnostic references no specific source element.
locationLocationnoWhere the diagnostic points, when the emitter can locate the issue. A parser fills the byte span; a renderer fills the structured position within a source document. Absent when the diagnostic has no location.
suggeststringnoAn optional remediation hint the emitter offers alongside the diagnostic. Absent when no hint is offered.

Additional properties are not permitted.

Location

Where a diagnostic points. It carries one unified locator that serves both a byte-precise position in raw source text (a parser fills the span) and a structured position within a source document (a renderer fills key_path, uri, line, and kind), and names the instance of the build the diagnostic concerns where there is one (instance). Every field is optional; a socket populates the representation it can produce and omits the rest.

PropertyTypeRequiredDescription
spanSpannoThe span of raw source bytes the diagnostic locates, when the emitter parses source and can pin the issue to a byte range (a parser). Absent otherwise.
key_pathstringnoA dotted path to the offending element within a structured source document, when the emitter locates the issue structurally (a renderer). Absent otherwise.
uristringnoAn identifier for the source artifact the diagnostic concerns, when the emitter knows it (a renderer). Absent otherwise. It never names an instance of the build; instance carries that.
lineintegernoA line number within the structured source document, distinct from the raw-byte line and column carried by span. Present when the emitter knows a document line (a renderer). Absent otherwise.
kindstringnoAn open string naming the source surface the location refers to, when the emitter distinguishes surfaces (a renderer). Absent otherwise.
instancestringnoThe instance of the build the diagnostic concerns, by the identity the build gives it: a component by the name the Aggregate declares it under, a component a module contributes by its path dotted through the module, a component the build derives by the identity the build composes for it, and a module by its own path. Present when the diagnostic is about one instance; absent otherwise.

Additional properties are not permitted.

Span

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.