Diagnostic Code Reference

Failures reported as RdfDiagnostic values carry a stable, machine-readable code alongside severity, message, detail and location. The code is the contract: tests, the SARIF emitter, the CLI, the Python ValueError text and downstream matchers key on it, while the message is free prose that may change wording. This page lists the codes by family, with the failure each one names and what a caller can do about it. The set was enumerated from the constructor sites in the source tree, not written from memory; if a code you see is missing here, the source is authoritative and the page is stale.

Codes are kebab-case, prefixed by the family that owns them. They are never translated, and a caller should compare the whole string rather than a prefix.

RdfDiagnostic::presentation() optionally provides a stable message identity, named typed parameters and structured detail. Select a presentation template by message_id(): one diagnostic code can cover several templates. Read parameter values directly instead of extracting them from English text. to_json() emits the versioned machine record, with logical 64-bit anchors and typed integers as exact decimal strings. SARIF retains it in properties.diagnosticRecord; C callers use the borrowed purrdf_error_presentation_json accessor.

iri-* — IRI parsing and base resolution (purrdf-iri)

IriError::diagnostic_code is the single owner of these strings for the whole workspace; every codec, SPARQL, ShEx and SHACL route an IRI failure through it. The base-related codes distinguish an invalid base, a missing base and a grammar that forbids relative references; their remedies differ.

native-codec-* — the text and XML codecs (purrdf-rdf)

The last nine arise when the codec lane consumes term events rather than text — a GTS graph being resolved through the codec surface — and mirror the gts-* and rdf-ir-* codes below.

native-jsonld-* and jsonld-* — JSON-LD and YAML-LD

cdt-* — SEP-0009 composite literals

A cdt:List or cdt:Map lexical form denotes blank nodes in the enclosing document’s scope, so a form that does not parse leaves that scope undefined and the whole document is refused rather than the literal being kept opaque.

rdf-ir-* — dataset structure (purrdf-core freeze and GTS import)

RdfDatasetBuilder::freeze() validates the structure of the dataset it is about to freeze; the GTS import sink reports the same family for a container whose terms do not form a well-formed dataset.

gts-* and rdf-* — GTS graph resolution, verification and writing

native-sparql-* — the SPARQL engine boundary (purrdf-sparql-eval)

xpath-* — dated native XPath regular expressions (purrdf-core)

These codes arise only when a caller selects a dated XPath law (xpath-2.0-2010-12-14 or xpath-3.1-2017-03-21) for SPARQL REGEX and REPLACE, SHACL sh:pattern or ShEx pattern facets. Without a selection, the compatibility regular expressions run and none of these codes appears. purrdf_core::xsd_regex::xpath::Resource::code is their single owner. Each one names the Resource that a Limits bound withheld (Error::Resource, with the exact requirement and the bound), or whose storage the host refused to allocate (Error::Allocation). The production bound Limits::new() sets is given in each row, and zero withholds a resource completely.

Every xpath-* code is operational. It is never a syntax verdict and never a non-match: invalid flags (FORX0001), an invalid pattern (FORX0002), an empty-matching replacement pattern (FORX0003) or invalid replacement text (FORX0004) is the host’s ordinary invalid-pattern outcome instead, which is a SPARQL expression error, a SHACL finding or a failed ShEx facet. A refusal fails the whole operation. A query publishes no answer, an update changes nothing, and a validation writes no report; the refusal never becomes an unbound value, a false filter or a conforming graph. The C ABI reports it as PURRDF_STATUS_REGEX_RESOURCE_ERROR (13).

The bounds apply to every pattern. Matching charges the work actually performed: character comparisons, choices, state copies, search advances and replacement output. A matcher step has no universal nanosecond cost, and neither one step per byte nor a one-to-three-step range describes every search.

Under a dated law, a finite maximum that the input cannot reach no longer creates distinct count states. Compatibility nullable bodies keep their finite bounds and original capture priority. Greedy single-character runs, including choices and capture chains, scan once and retain their priority-ordered stops. Large nonnullable counts can reuse relative states while their bound comparisons stay unchanged, with exact counts restored near a bound.

Production-default tests cover four mebibytes of ^[\s\S]{0,10000000}$, ^[^\n]{0,10000000}$, ^[^<>]{1,5000000}$, ^[\p{L} ]{1,5000000}$ and ^(\w+\s?){1,5000000}$, and four mebibytes of the exact-count choices ^(a|b){4194304}$ and (a|b){4000000}. Decision and capture searches have integer work bounds of four steps per byte for these classes/grouped words and six for these choices. Nonbinding maxima ten times larger spend the same work; these fixture bounds are not universal admission or timing guarantees. REPLACE over two mebibytes of grouped words retains the final iteration’s capture and also charges template and output work. The native_xpath_large benchmark group measures these forms and their count/input-size ladders beside the original literal, grouped and adversarial neighbours.

Nested counted repetitions whose bodies can repeat empty still distinguish count combinations. On aaab, ((a?){3000}){3000}b answers while ((a?){5000}){5000}b reaches an operational bound. There is no universal minimum-count threshold: the pattern and input determine which states coexist. A backreference keeps the backtracking matcher, whose exponential exploration (^(a|aa)*c\1$ over forty a) can reach the step bound. Such refusal is a hard operational error, not false, an absent capture or a partial replacement.

reasoning-* — SPARQL under an entailment regime (purrdf)

statements-* — statement-metadata ingestion (purrdf-rdf)

These arise when a document’s rdf:reifies and owl:Axiom statements are read into the statement layer.

Other single-code families

Where the code reaches you

• Rust — RdfDiagnostic::code on the returned error; its Display form is <severity> <code>: <message>.
• Python — the ValueError message is that Display form (for example error native-codec-parse: …); an IRI failure is rendered as <code>: <message> (for example iri-relative-no-base: …).
• JavaScript — the thrown Error message carries the same text, and its code property carries the code itself. The wasm package’s own refusals carry a purrdf-wasm-* code: purrdf-wasm-options (an option or argument an operation refused), purrdf-wasm-usage (a job asked for something out of turn), purrdf-wasm-serialize (a result that cannot be written in the format asked for), purrdf-wasm-entailment (an entailment regime or its closure failed), purrdf-wasm-extension-environment (the aggregate registry could not be built), purrdf-wasm-shacl and purrdf-wasm-shacl-product-refusal (a SHACL surface failed, or refused a prepared product).
• C — the error string returned through the C ABI carries the same text.
• SARIF — the ruleId of each result is the code, with a reportingDescriptor in the run’s rule table (purrdf-validate).