tur/schema

(def SCHEMA_STR 0)

discriminant for the :cstr scalar schema.

(def SCHEMA_INT 1)

discriminant for the :int scalar schema.

(def SCHEMA_FLOAT 2)

discriminant for the :float scalar schema.

(def SCHEMA_BOOL 3)

discriminant for the :bool scalar schema.

(def SCHEMA_NIL 4)

discriminant for the null schema.

(def SCHEMA_LITERAL 5)

discriminant for an exact-value schema.

(def SCHEMA_OBJECT 6)

discriminant for an object (field-list) schema.

(def SCHEMA_ARRAY 7)

discriminant for a homogeneous array schema.

(def SCHEMA_OPTIONAL 8)

discriminant for an optional (nullable) schema.

(def SCHEMA_UNION 9)

discriminant for a first-match union schema.

(def SCHEMA_TRANSFORM 10)

discriminant for a decode-then-map schema.

(def SCHEMA_REC 11)

discriminant for a recursive (self-referential) schema.

(def SCHEMA_ALWAYS 12)

discriminant for a schema that always succeeds (backs pure).

(def SCHEMA_NEVER 13)

discriminant for a schema that always fails (backs empty).

(def SCHEMA_AP 14)

discriminant for the Validation applicative (apply + accumulate).

(def SCHEMA_FIELD 15)

discriminant for an extract-one-field schema.

(def SCHEMA_AP_FAT 16)

discriminant for a closure-aware applicative apply.

(schema/str :int)

a schema that matches JSON strings (:cstr).

(schema-decode (schema/str) (json/string "hi"))  ; => ok("hi")

Since: Phase SC0

(schema/int :int)

a schema that matches JSON integers (:int).

(schema-decode (schema/int) (json/int 42))  ; => ok(42)

Since: Phase SC0

(schema/float :int)

a schema that matches JSON floats (:float).

Since: Phase SC0

(schema/bool :int)

a schema that matches JSON booleans (:bool).

Since: Phase SC0

(schema/nil :int)

a schema that matches JSON null.

Since: Phase SC0

(schema/literal-int [v :int] :int)

a schema matching one exact integer value.

(schema-decode (schema/literal-int 7) (json/int 7))  ; => ok(7)

Since: Phase SC0

(schema/literal-str [v :cstr] :int)

a schema matching one exact string value.

(schema-decode (schema/literal-str "active") (json/string "active"))

Since: Phase SC0

(schema/object-new :int)

start an empty object schema.

(schema/field (schema/field (schema/object-new)
                            "name" (schema/str))
              "age" (schema/int))

Since: Phase SC1

(schema/field [obj :int key :cstr inner :int] :int)

add a declared field to an object schema.

(schema/field (schema/object-new) "name" (schema/str))

Since: Phase SC1

(schema/array [elem :int] :int)

a schema for a homogeneous JSON array.

(schema/array (schema/int))  ; matches [1, 2, 3]

Since: Phase SC2

(schema/optional [inner :int] :int)

a schema where null / absent is acceptable.

(schema/optional (schema/str))

Since: Phase SC2

(schema/union [arms :int] :int)

a schema where the first matching arm wins.

(schema/union (vec-of (schema/int) (schema/str)))

Since: Phase SC2

(schema/transform [inner :int ^fat f] :int)

decode with a schema, then map the result.

(schema/transform (schema/int) (fn [x] (* x 2)))
(let [k 100] (schema/transform (schema/int) (fn [x] (+ x k))))  ; captures k

Since: Phase SC2

(schema/rec [f] :int)

a self-referential schema for recursive data.

(schema/rec (fn [self]
  (schema/field
    (schema/field (schema/object-new) "value" (schema/int))
    "children" (schema/array self))))

Since: Phase SC4

(schema/kind [s :int] :int)

return the SCHEMA_* discriminant of a schema value.

Since: Phase SC0

(schema/always [value :int] :int)

a pure schema that ignores its input, decoding to a fixed value.

(schema-decode! (schema/always 42) (json/null))  ; => 42

Since: Phase SC7

(schema/never [message :cstr] :int)

the empty schema: always fails with a fixed message (identity of schema/union).

(schema-decode (schema/never "no match") (json/int 1))  ; => err

Since: Phase SC7

(schema/ap [sf :int sa :int] :int)

the Validation applicative: apply sf's decoded function to sa's decoded value, accumulating both arms' errors.

Decodes the function arm sf and the argument arm sa against the *same* input, concatenates their errors left-to-right, and applies the decoded function to the decoded argument only when both arms succeed.

;; double-it is a top-level (defn double-it [x] (* x 2))
(schema/ap (schema/always double-it)
           (schema/field-of "n" (schema/int)))

Since: Phase SC7

(schema/field-of [key :cstr inner :int] :int)

decode a JSON object and extract one key's decoded value via an inner schema.

Yields the key's decoded value (not the whole object), so it composes with schema/ap to assemble values field by field.

(schema/field-of "age" (schema/int))  ; on {"age":30} => 30

Since: Phase SC7

(schema/fmap [inner :int ^fat f] :int)

the Functor map for schemas: decode with inner, then map the result with f (alias for schema/transform).

(schema/fmap (schema/int) double-it)

Since: Phase SC7

(schema/alt [a :int b :int] :int)

the Alternative <|>: a two-arm first-match union (try a, then b).

(schema/alt (schema/int) (schema/str))

Since: Phase SC7

(schema/ap-fat [sf :int sa :int] :int)

closure-aware Validation applicative (kind 16).

Like schema/ap, but applies the decoded function arm to the decoded argument through the fat-closure protocol (TUR_APPLY1) rather than a raw C call, so the function arm may be a *capturing* closure -- e.g. the partially-applied curried constructor produced by fmap ctor field when assembling a struct field by field. Same accumulating error semantics as schema/ap. This is the combinator the Applicative [Schema] instance's ap method is built on.

Since: Phase SC7

(defstruct Schema [A] (raw :int))

phantom wrapper over an int-carrier schema, for HKT dispatch.

Since: Phase SC7

(definstance Functor [Schema])

map a function over a schema's decoded value.

(definstance Applicative [Schema])

Validation applicative: pure + accumulating ap.

pure lifts a value (schema/always); ap applies a decoded function arm to a decoded argument arm via the closure-aware schema/ap-fat, accumulating both arms' errors (Validation, not fail-fast). Monad is deliberately omitted: the lawful fail-fast >>= contradicts this accumulating <*> (see schema/ap).

(definstance Alternative [Schema])

first-match choice (alt-or) + the empty schema.

(schema-error-path [e :int] :cstr)

the dot-separated field path of a SchemaError.

Since: Phase SC3

(schema-error-text [e :int] :cstr)

the human-readable message of a SchemaError.

Since: Phase SC3

(schema-error-count [errs :int] :int)

number of errors in an error Vec.

Since: Phase SC3

(schema-error-at [errs :int i :int] :int)

the i-th SchemaError in an error Vec.

Since: Phase SC3

(schema-error-message [errs :int] :cstr)

format an error Vec into one human-readable cstr.

(schema-error-message errs)  ; => "user.age: expected :int, got :cstr"

Since: Phase SC3

(sch-vpush- [v :ptr x :int] :void)

validate a JSON node against a schema.

(let [s (schema/field (schema/object-new) "age" (schema/int))
      r (schema-decode s (json/decode "{\"age\":1}"))]
  (schema-decode-ok? r))  ; => true

Since: Phase SC1

(sch-push-err- [errs :ptr path :cstr msg :cstr val :int] :void)

(sch-mkpath- [base :cstr key :cstr] :ptr)

(sch-mkidx- [base :cstr idx :int] :ptr)

(sch-tyname- [jtype :int] :cstr)

(sch-want-name- [kind :int] :cstr)

(sch-jtype- [n :int] :int)

(sch-jpayload- [n :int] :int)

(sch-decode-rec- [schema :int node :int path :cstr errs :ptr] :int)

(schema-decode [schema :int node :int] :int)

(schema-decode-ok? [r :int] :bool)

whether a schema-decode Result succeeded.

Since: Phase SC1

(schema-decode-value [r :int] :int)

the decoded value of a successful Result.

Since: Phase SC1

(schema-decode-errors [r :int] :int)

the error Vec of a failed Result.

Since: Phase SC1

(schema-decode-report [errs :int] :int)

internal: print an error Vec to stderr.

(schema-decode-abort [errs :int] :int)

internal: report an error Vec and raise.

A panic, not a bare abort(): with no catch boundary in scope the two are indistinguishable (both print and die), but a panic is what makes (catch-unwind (fn [] : T (decode! ...))) -- and with it the Result-returning #json-str?<T> reader -- able to recover from a schema violation instead of taking the process down. The errors are printed first, so the diagnostic detail survives either way.

(schema-decode! [schema :int node :int] :int)

decode against a schema, panicking on any violation.

(schema-decode! (schema/int) (json/int 5))  ; => 5

Since: Phase SC1

(defclass HasSchema [a])

a type that knows how to validate-and-build itself from a tagged JSON node.

The single method, decode!, puts its dispatch type variable a only in the return position, so the concrete instance is selected from the *expected type at the use site* (an ascription (:: (decode! node) T) or a typed binding (let [x : T (decode! node)] ...)) rather than from any argument. This is return-type-directed dispatch (Phase RT): the elaborator unifies the method's a against the ascribed type and emits a direct call to the matching instance.

An instance pairs a schema (the wire shape) with a builder that turns the validated node into the typed value, e.g.

(definstance HasSchema [User]
  (decode! [node]
    (let [v (schema-decode! (user-schema) node)]
      (make-struct User (json/get-string (json/get! v "name"))
                        (json/get-int    (json/get! v "age"))))))

and is then driven by an ascription:

(:: (decode! (json/decode body)) User)   ; => a real User struct

decode! panics (via schema-decode!) on any schema violation; it is for trusted data and tests. For graceful handling, validate first with schema-decode against the type's schema and branch on schema-decode-ok?.

Since: Phase SC5