Teptris — schema validation (engine v0.3.31)
libteptris validates TOML documents against JSON Schema (draft 2020-12, practical subset). Compile a schema once, validate many documents — the same engine serves C, the CLI, Ruby, Python, JavaScript and Rust. Zero divergences on the entire official test suite: 1789/1789 (2026-11-12).
A schema is ordinary JSON Schema — the same vocabulary you use for JSON today. The engine compiles it into an immutable, arena-backed graph and validates parsed TOML against it, collectingevery violation (up to 256) rather than stopping at the first. The violation shape is identical on every surface:
{ "path": "server.port", // where in the document (dotted TOML path, array indices as items.0.name)
"schemaPath": "#/properties/server/properties/port", // where in the schema
"message": "expected a matching type, found string" // why
}An empty result means the document is valid. Documents that do not parse raise the binding’s parse error (line/column) instead — a syntax failure is never reported as a violation.
The CLI
teptris validate compiles a schema file, validates a TOML file, prints the violation JSON array on stdout, and exits non-zero when anything fails:
$ teptris validate --schema service.json service.toml
[{"path":"port","schemaPath":"#/properties.port","message":"expected a matching type, found string"}]
$ echo $? # 1
$ teptris validate --schema service.json good.toml && echo ok
okThe output is jq-pipeable — this is the same handback every binding decodes.
C
The stable ABI lives in <teptris/schema.h>(shipped by cmake --install). Compile, validate, free; every buffer handed back is malloc’d memory you release:
#include <string.h>
#include <stdlib.h>
#include <teptris/schema.h>
teptris_schema *sch = NULL;
char *diag = NULL;
const char *sj = "{\"properties\":{\"port\":{\"type\":\"integer\"}}}";
if (teptris_schema_compile(sj, strlen(sj), &sch, &diag, NULL) != TEPTRIS_OK) {
fprintf(stderr, "schema rejected: %s\n", diag ? diag : "?");
teptris_diag_free(diag);
return 1;
}
char *buf = NULL; size_t n = 0;
const char *doc = "port = \"x\"\n";
teptris_schema_validate(sch, doc, strlen(doc), &buf, &n);
/* buf = [{"path":"port","schemaPath":"#/properties.port",
* "message":"expected a matching type, found string"}] */
free(buf);
teptris_schema_free(sch);Ruby
require "teptris"
schema = Teptris::Schema.compile('{"properties":{"port":{"type":"integer"}}}')
schema.valid?("port = 8080\n") # => true
schema.validate("port = \"x\"\n")
# => [#<Teptris::Schema::Violation path: "port",
# schema_path: "#/properties.port",
# message: "expected a matching type, found string">]
# each violation answers .path, .schema_path, .message (and .to_h)Compile failures raise Teptris::Error carrying the engine’s diagnostic JSON; documents that do not parse raiseTeptris::ParseError with line/column.
Python
import teptris
schema = teptris.compile_schema('{"properties":{"port":{"type":"integer"}}}')
schema.valid('port = 8080\n') # => True
schema.validate('port = "x"\n')
# => [{"path": "port",
# "schema_path": "#/properties.port",
# "message": "expected a matching type, found string"}]teptris.Schema accepts str or bytes; violations come back as plain dicts with path /schema_path / message. Malformed documents raise TOMLDecodeError.
JavaScript / TypeScript
import { init } from "teptris";
const api = await init();
const schema = api.compileSchema('{"properties":{"port":{"type":"integer"}}}');
schema.validate("port = 8080\n"); // => []
schema.validate('port = "x"\n');
// => [{ path: "port", schemaPath: "#/properties.port",
// message: "expected a matching type, found string" }]The handle is wasm-side — call schema.free() when done. Compile failures throw Error carrying the diagnostic JSON.
Rust
use teptris::schema::Schema;
let schema = Schema::compile(r#"{"properties":{"port":{"type":"integer"}}}"#).unwrap();
let violations = schema.validate(b"port = \"x\"\n").unwrap();
assert_eq!(violations[0].path, "port");
assert_eq!(violations[0].schema_path, "#/properties.port");
assert!(schema.validate(b"port = 8080\n").unwrap().is_empty());Compile failures return SchemaCompileError carrying the diagnostic verbatim. A compiled Schema isSend + Sync — share it across threads.
The four TOML/JSON policies
TOML and JSON differ in exactly four places; each difference has a documented policy (engine contract — SCHEMAS.md in the repository):
- null — TOML has no null. A branch requiring null matches no TOML value; optionality stays with
required+ absence, so the JSON idiom"type": ["string", "null"]behaves as an optional string. - integer — TOML’s integer is a distinct type from float:
1and1.0differ."type": "integer"matches only TOML integers;"type": "number"matches both. - datetimes — TOML’s four datetime shapes validate as
"type": "string", and theformatkeywordsdate-time,date,timecheck the datetime shape — a TOML datetime of the matching shape passes, and so does a string whose content parses as that shape. - non-finite floats —
nan,inf,-infare TOML floats matching"type": "number"; nan fails every range/multipleOf, inf violates anymaximum. No special-casing.
What compiles — and what rejects
The engine implements the practical 2020-12 subset: types, enums/consts, numeric and string constraints, required/ properties/additionalProperties, items/prefixItems/contains, allOf/anyOf/oneOf/not, $ref (local pointers,$anchors, recursive definitions),$defs/definitions, default/ examples/deprecated/annotations, and content keywords. Unknown keywords are ignored (extensions, per the spec).
Constructs that would silently change results if ignored are rejected at compile with a diagnostic naming the problem — never silently skipped:
schema.compile('{"properties":{"p":{"pattern":"((a"}}}')
# => schema rejected: {"error":"unterminated group at pattern"}That class: unevaluatedProperties/unevaluatedItems, $dynamicRef/$dynamicAnchor/$recursiveRef/$recursiveAnchor, backreferences and lookaround in patterns, and any remote (absolute-URI) $ref — a parser library never touches the network.
Formats: annotation by default, assertion on demand
Draft 2020-12 makes format annotation-only by default, and teptris follows the spec: schemas that declare the standard 2020-12 dialect treat format as an annotation. Schemas that opt in via the sanctionedformat-assertion dialect({"$schema": "https://json-schema.org/draft/2020-12/format-assertion"}) get format checking. When formats assert, the battery is real:
date, time, date-time, datetime-local, time-local RFC 3339 (leap seconds at the UTC day end)
email, idn-email RFC 5322 / RFC 6531 (quoted locals, LDH labels)
hostname, idn-hostname RFC 1035/5891 + UTS #46 + IDNA:
NFC, RFC 3492 punycode, RFC 5892 context rules,
RFC 5893 bidi rules, wire-form length gates
uri, uri-reference, iri, iri-reference RFC 3986/3987 (authority, port, IPv6 literals, IRI unicode)
uri-template RFC 6570 (operators, varname dots, :N / * modifiers)
uuid RFC 4122 (8-4-4-4-12 hex)
json-pointer, relative-json-pointer RFC 6901
regex the engine's own NFA (a compile trial)
duration RFC 3339 duration grammar (strict canonical order)Every case above is asserted against the official JSON Schema test suite’s unified model — 1789/1789, zero divergences — including the punycode, context-rule and bidi corners of internationalized hostnames.
Patterns are ReDoS-immune
pattern and patternProperties run on a linear-time NFA (Thompson construction): no backtracking, no pathological inputs, no host hangs. The practical ECMA subset is supported: literals, ., classes, groups, alternation, greedy quantifiers, anchors, \b,\d \w \s (and negations), \xNN,\uNNNN; lazy quantifiers are accepted (boolean match semantics are identical).
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.