LEPTRIS

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:

json
{ "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:

console
$ 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
ok

The 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:

c
#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

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

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

ts
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

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):

  1. null — TOML has no null. A branch requiring null matches no TOML value; optionality stays withrequired + absence, so the JSON idiom"type": ["string", "null"] behaves as an optional string.
  2. integer — TOML’s integer is a distinct type from float: 1 and 1.0 differ."type": "integer" matches only TOML integers;"type": "number" matches both.
  3. datetimes — TOML’s four datetime shapes validate as "type": "string", and theformat keywords date-time,date, time check the datetime shape — a TOML datetime of the matching shape passes, and so does a string whose content parses as that shape.
  4. non-finite floats — nan,inf, -inf are TOML floats matching"type": "number"; nan fails every range/multipleOf, inf violates any maximum. 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:

console
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:

text
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.