Yeptris — validation and schemas (engine v0.6.75)
Yeptris ships four distinct faces that are easy to blur: the parse-time schema MODES (YAML 1.2 core vs 1.1-compat — how implicit typing resolves), the schema-family VALIDATION walk (spec-conformance diagnostics, core and the spec 10.2 JSON productions), JSON SCHEMA draft 2020-12 (the keyword subset, schema bytes parsed by the same engine), and schema DESCRIPTORS (typed columns materialized in one C pass — no intermediate document). This page keeps them apart and documents each with snippets executed against the shipped artifacts.
The four faces, kept apart
1. Parse-time schema modes —Document.parse(src, schema: :core_12) vs:compat_11: which implicit productions resolve during the parse (1.2 core vs the 1.1-compat family psych rides). This is a parse input, not a validation verdict.
2. The schema-family validation walk —document.validate(schema:) /yeptris_validate: the document is parsed, then checked against the YAML 1.2 spec's own conformance rules — explicit-tag consistency (spec 10.3 resolution), canonical-form mapping-key uniqueness (spec 3.2.1.3 — 0o13 and 0xBare the same key). Under :json_12 the same walk swaps in the spec 10.2 JSON productions: implicit resolution stays JSON-shaped (the core extensions — 0o/0xradix, +12.3, the True/~casings — stay strings per example 10.8), mapping keys must be strings, and explicit non-JSON tags are rejected. Whole reports, not callbacks.
3. JSON Schema validation —yeptris_json_schema_validate: the schema arrives as bytes and is parsed by the same engine (JSON is YAML flow), the target is validated against the draft 2020-12 keyword subset; unknown keywords are ignored, per 2020-12. Compile the schema once and validate many instance streams against the retained model withyeptris_schema_compile.
4. Schema descriptors —Yeptris::Schema: one native pass fills typed columns against a caller-compiled descriptor (KIND scalar/sequence/mapping, TYPE str/int/float/bool/null/any, REQUIRED, FIRST_WINS duplicate policy) — the intermediate generic document never exists. This is the lutaml-model KV path (issue #184).
The validation walk (Ruby)
Document.parse under a schema, thenvalidate — an array ofYeptris::Validation::Diagnostic; empty means valid. A duplicate key (the diagnostic carries path, 1-based line/col, a numeric code, and a bounded detail):
require "yeptris"
doc = Yeptris::Document.parse("---\nname: x\nname: y\n", schema: :core_12)
doc.validate(schema: :core_12)
# => [#<Yeptris::Validation::Diagnostic duplicate-key path="" line=3 col=1
# detail="duplicate mapping key (\"name\")">]Canonical-form key uniqueness: 0o13 and0xB both resolve to 11, so as keys of one mapping they collide:
doc = Yeptris::Document.parse("---\n0o13: x\n0xB: y\n", schema: :core_12)
doc.validate(schema: :core_12)
# => [#<Yeptris::Validation::Diagnostic duplicate-key path="" line=3 col=1
# detail="duplicate mapping key (\"0xB\")">]The JSON productions family (:json_12)
schema: :json_12 applies the spec 10.2 restriction: mapping keys must be strings (a complex key is a violation), and an explicit non-JSON tag is rejected with the instance path:
doc = Yeptris::Document.parse("? [complex, key]\n: v\n", schema: :json_12)
doc.validate(schema: :json_12)
# => [#<Yeptris::Validation::Diagnostic key-not-string path="" line=1 col=4
# detail="mapping key is a sequence">]
doc = Yeptris::Document.parse("---\na: !!custom v\n", schema: :json_12)
doc.validate(schema: :json_12)
# => [#<Yeptris::Validation::Diagnostic non-json-type path="/a" line=2 col=13
# detail="explicit custom tag is not a JSON type">]The core-only productions stay strings here —a: True under :json_12 is a plain string"True" (spec example 10.8), so it validates clean:
doc = Yeptris::Document.parse("---\na: True\n", schema: :json_12)
doc.validate(schema: :json_12)
# => []JSON Schema validation (draft 2020-12)
yeptris_json_schema_validate takes the schema and the target as bytes — the schema is parsed by the same engine (JSON is YAML flow; document 0 of the schema stream is the schema), then every document of the target stream is validated against it. The keyword subset is draft 2020-12: type,enum, const, pattern; the numeric minimum/maximum/exclusive bounds and multipleOf; minLength/maxLength (code points); items/prefixItems, minItems/maxItems, uniqueItems,contains (+minContains/maxContains);properties, required,patternProperties, propertyNames,minProperties/maxProperties,additionalProperties;dependentRequired/dependentSchemas;if/then/else;allOf/anyOf/oneOf/not; local $ref ($defs anddefinitions both resolve); boolean schemas. Unknown keywords — and known keywords with unreadable values — are ignored, per 2020-12. Instance types ride the engine's core-schema resolution (the YAML→JSON data model): "y" is boolean, 1.0 is integer.
#include <stdio.h>
#include <string.h>
#include <yeptris/validate.h>
int main(void) {
const char *schema =
"{ \"type\": \"object\","
" \"properties\": { \"id\": { \"type\": \"integer\" } },"
" \"required\": [\"id\"] }";
const char *doc = "---\nid: \"42\"\n";
yeptris_validate_report *report = NULL;
YeptrisStatus st = yeptris_json_schema_validate(schema, strlen(schema),
doc, strlen(doc), &report);
if (st != YEPTRIS_OK && st != YEPTRIS_ERROR_SCHEMA) return 1;
size_t n = yeptris_validate_report_count(report);
for (size_t i = 0; i < n; i++) {
const yeptris_diagnostic *d = yeptris_validate_report_at(report, i);
printf("code=%u path=%s line=%u col=%u detail=%s\n",
d->code, d->path, d->line, d->col, d->detail);
}
yeptris_validate_report_free(report);
return 0;
}
/* code=5 path=/id line=2 col=6 detail=expected integer, got string */The COMPILED SCHEMA — parse once, validate many (yeptris_schema_compile retains the schema bytes, its DOM, and the pattern kernel's compiled programs;yeptris_schema_validate keeps the exact status/report contract; yeptris_schema_free releases everything in one call). The handle is immutable after compile: one handle per thread like documents, read-only sharing safe:
#include <stdio.h>
#include <string.h>
#include <yeptris/validate.h>
int main(void) {
const char *schema = "{ \"type\": \"integer\" }";
yeptris_schema *compiled = yeptris_schema_compile(schema, strlen(schema));
if (!compiled) return 1;
const char *streams[] = { "12\n", "---\ntrue\n" };
for (int i = 0; i < 2; i++) {
yeptris_validate_report *report = NULL;
yeptris_schema_validate(compiled, streams[i], strlen(streams[i]), &report);
size_t n = yeptris_validate_report_count(report);
for (size_t j = 0; j < n; j++) {
const yeptris_diagnostic *d = yeptris_validate_report_at(report, j);
printf("stream %d: code=%u path=%s line=%u col=%u detail=%s\n",
i, d->code, d->path, d->line, d->col, d->detail);
}
yeptris_validate_report_free(report);
}
yeptris_schema_free(compiled);
return 0;
}
/* stream 1: code=5 path= line=2 col=1 detail=expected integer, got boolean */The same faces in Ruby — Yeptris::YAML.validate withjson_schema: (bytes, one-shot) or a compiledYeptris::Validation::Schema; load takes the same keyword and raisesYeptris::Validation::Error carrying the diagnostics before loading a byte:
require "yeptris"
schema = '{ "type": "object",
"properties": { "id": { "type": "integer" } },
"required": ["id"] }'
Yeptris::YAML.validate("---\nid: 42\n", json_schema: schema)
# => []
Yeptris::YAML.validate("---\nid: \"42\"\n", json_schema: schema)
# => [#<Yeptris::Validation::Diagnostic type path="/id" line=2 col=6
# detail="expected integer, got string">]
Yeptris::YAML.load("---\nid: \"42\"\n", json_schema: schema)
# => Yeptris::Validation::Error: validation failed (1 diagnostics):
# type at /id: expected integer, got stringYeptris::Validation::Schema.open(schema) do |compiled|
compiled.valid?("id: 7\n") # => true
compiled.validate("---\nname: n\n")
# => [#<Yeptris::Validation::Diagnostic required path="/id" line=2 col=1
# detail="missing required property \"id\"">]
endAnd in Python — yeptris.yaml carriesvalidate/is_valid (one-shot bytes or a compiled schema), the safe_load gate (json_schema= validates the whole stream before any document is built, raising yeptris.ValidationError), and compile_schema:
import yeptris.yaml as y
schema = '{ "type": "object", "properties": { "id": { "type": "integer" } }, "required": ["id"] }'
y.validate('---\nid: "42"\n', json_schema=schema)
# => [Diagnostic(code=5, keyword='type', path=['id'],
# message='expected integer, got string', line=2, col=6)]
y.is_valid('---\nid: 42\n', json_schema=schema) # => True
y.safe_load('---\nid: 42\n', json_schema=schema) # => {'id': 42}
compiled = y.compile_schema(schema)
compiled.is_valid("id: 7\n") # => True
compiled.validate("name: n\n")
# => [Diagnostic(code=6, keyword='required', path=['id'],
# message='missing required property "id"', line=1, col=1)]Diagnostic anatomy
Every diagnostic — C, Ruby, and Python — carries the same shape:path (a JSON-pointer instance path, /a/b/0for array items, ~0/~1 escaped, root relative per document; multi-document streams prefix the document index — /1/a/b is a/b of document 1),line/col (1-based; 0 = unknown — arena- owned scalars have no input position, the path still names them), a stable numeric code (the YEPTRIS_DIAG_*enum in <yeptris/validate.h> — appending only; the bindings hard-code the values, the ABI test pins the head, and each binding spells the code as a keyword:duplicate-key/type in Ruby,duplicateKey/type in Python), and a bounded detail string. The document-index prefix is what names a miss in a stream — a bad second document reports its own path, not the first document's:
schema = '{ "type": "object", "properties": { "id": { "type": "integer" } } }'
Yeptris::YAML.validate("---\nid: 1\n---\nid: \"x\"\n", json_schema: schema)
# => [#<Yeptris::Validation::Diagnostic type path="/1/id" line=4 col=6
# detail="expected integer, got string">]C
yeptris_validate parses and validates in one call — every document of the stream. An already-parsed document or stream validates without re-parsing:yeptris_validate_document (the document is not modified; the report borrows nothing from it). Statuses compose:YEPTRIS_OK (valid — empty report) orYEPTRIS_ERROR_SCHEMA (the report carries diagnostics). Every diagnostic is a flat yeptris_diagnostic struct (16 + 256 + 128 bytes, ABI-pinned); the report frees in one call:
#include <stdio.h>
#include <string.h>
#include <yeptris/validate.h>
int main(void) {
const char *doc = "---\nname: x\nname: y\n";
yeptris_validate_report *report = NULL;
YeptrisStatus st = yeptris_validate(doc, strlen(doc), YEPTRIS_SCHEMA_12_CORE, &report);
if (st != YEPTRIS_OK && st != YEPTRIS_ERROR_SCHEMA) return 1;
size_t n = yeptris_validate_report_count(report);
for (size_t i = 0; i < n; i++) {
const yeptris_diagnostic *d = yeptris_validate_report_at(report, i);
printf("code=%u path=%s line=%u col=%u detail=%s\n",
d->code, d->path, d->line, d->col, d->detail);
}
yeptris_validate_report_free(report);
return 0;
}
/* code=4 path= line=3 col=1 detail=duplicate mapping key ("name") */Schema descriptors
The descriptor face compiles a flat table (the root entry first; container entries point at their children viachild_index/child_count) and one native pass fills typed columns — lutaml-model's KV path rides this. Engine tags after 0.6.12 carry the executed:any verdict —Yeptris::Schema.headroom_supported? probes the loaded engine rather than trusting a version:
require "yeptris"
desc = [
{ kind: :mapping, child_index: 1, child_count: 3 },
{ wire_name: "id", kind: :scalar, type: :int },
{ wire_name: "name", kind: :scalar, type: :str },
{ wire_name: "active", kind: :scalar, type: :bool },
]
Yeptris::Schema.load_records("id: 42\nname: widget\nactive: true\n", desc: desc)
# => [{ id: 42, name: "widget", active: true }]load_records zips the columns into record hashes: mapping root → one hash, sequence-of-mappings → one hash per element, sequence-of-scalars → { value: ... } hashes. Absent keys are omitted (not nil-filled) — absent seeds defaults; explicit nil is a present value. The:any type rides the C tag after engine 0.6.12 —headroom_supported? gates it.
This is the curated guide. The repositories are canonical: when this page and the repo disagree, the repo wins. Full documentation lives with the source.