This is the json-schema Reference Manual, version 2.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 06:32:07 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
json-schemaJSON schema validation
Matt Novenstern <fisxoj@gmail.com>
LLGPL
.. image:: https://travis-ci.org/fisxoj/json-schema.svg?branch=master
:target: https://travis-ci.org/fisxoj/json-schema
:alt: Travis CI status badge
.. image:: https://coveralls.io/repos/github/fisxoj/json-schema/badge.svg?branch=master
:target: https://coveralls.io/github/fisxoj/json-schema?branch=master
:alt: Coveralls status badge
.. image:: https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg
:alt: Contributor Covenant
:target: CODE_OF_CONDUCT.md
:Source: ‘https://github.com/fisxoj/json-schema <https://github.com/fisxoj/json-schema>‘_
:Docs: ‘https://fisxoj.github.io/json-schema/ <https://fisxoj.github.io/json-schema/>‘_
json-schema is a validator for drafts 4, 6, 7, and 2019-09 of the ‘JSON Schema <https://json-schema.org/>‘_ standard. It is (mostly) compliant with the ‘common test suite <https://github.com/json-schema-org/JSON-Schema-Test-Suite>‘_. The exceptions are
**Draft 2019-09:**
- “unevaluatedItems“ and “unevaluatedProperties“ are unimplemented
**Drafts 4, 6, 7:**
- “$ref“ does not override any sibling keywords
——-
Example
——-
The main entry point to the library is :function:‘json-schema:validate‘, which takes a schema to validate against, the data to validate against it and a draft version to use for interpreting the schema. The default version is currently draft7.
**Validating a simple type**
Passing
::
(json-schema:validate 3 :schema (json-schema.parse:parse "{\"type\":\"integer\"}"))
;; => T
;; NIL
Failing (note the error messages in the second argument)
::
(json-schema:validate 13 :schema (json-schema.parse:parse "{\"type\":\"integer\",\"maximum\":10}"))
;; => NIL
;; ("13 must be less than or equal to 10")
**Validating an object**
::
(setf schema (json-schema.parse:parse
"{\"properties\":{\"foo\\nbar\":{\"type\":\"number\"},\"foo\\\"bar\":{\"type\":\"number\"},\"foo\\\\bar\":{\"type\":\"number\"},\"foo\\rbar\":{\"type\":\"number\"},\"foo\\tbar\":{\"type\":\"number\"},\"foo\\fbar\":{\"type\":\"number\"}}}"))
Passing
::
(json-schema:validate
(json-schema.parse:parse
"{\"foo\\nbar\":1,\"foo\\\"bar\":1,\"foo\\\\bar\":1,\"foo\\rbar\":1,\"foo\\tbar\":1,\"foo\\fbar\":1}") :schema schema)
;; => T
;; NIL
Failing
::
(json-schema:validate
(json-schema.parse:parse
"{\"foo\\nbar\":\"1\",\"foo\\\"bar\":\"1\",\"foo\\\\bar\":\"1\",\"foo\\rbar\":\"1\",\"foo\\tbar\":\"1\",\"foo\\fbar\":\"1\"}") :schema schema)
;; => NIL
;; ("got errors validating properties
;;
;; Additionally:
;; - Value 1 is not of type \"number\".
;; - Value 1 is not of type \"number\".
;; - Value 1 is not of type \"number\".
;; - Value 1 is not of type \"number\".
;; - Value 1 is not of type \"number\".
;; - Value 1 is not of type \"number\".
;; ")
**Validating a document with a referenced schema**
If your data contains a top-level “$schema“ key, you don’t need to pass a schema along. It will be fetched and validated against automatically. This works with, for example, the ‘draft2019-09 meta-schema <https://json-schema.org/draft/2019-09/schema>‘_.
———–
Usage Notes
———–
~~~~~~~~
Contexts
~~~~~~~~
A context is a reusable set of state that contains all of the fetched network resources (if your schema references external resources) and resolved ids. By storing that all, you can reuse the validation context multiple times without fetching/resolving everything again.
::
(ql:quickload ’(trivial-benchmark json-schema))
(defvar *schema* (json-schema.parse:parse #P"~/Downloads/schema"))
;; schema is the json-schema meta schema document from:
;; https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8
(defvar *context*
(json-schema:make-context
*schema*
:draft2019-09))
;;; Cached
(let ((data (json-schema.parse:parse "{\"type\": \"string\"}")))
(trivial-benchmark:with-timing (1000)
(json-schema:validate data
:context *context*)))
;; - SAMPLES TOTAL MINIMUM MAXIMUM MEDIAN AVERAGE DEVIATION
;; REAL-TIME 1000 0.826 0 0.022 0.001 0.000826 0.000797
;; RUN-TIME 1000 0.826 0 0.022 0.001 0.000826 0.0008
;; USER-RUN-TIME 1000 0.781011 0 0.020644 0.000745 0.000781 0.000665
;; SYSTEM-RUN-TIME 1000 0.049933 0 0.000986 0 0.00005 0.000184
;; PAGE-FAULTS 1000 0 0 0 0 0 0.0
;; GC-RUN-TIME 1000 0.02 0 0.02 0 0.00002 0.000632
;; BYTES-CONSED 1000 213753664 195344 228976 228032 213753.66 16221.591
;; EVAL-CALLS 1000 0 0 0 0 0 0.0
;;; Uncached
(let ((data (json-schema.parse:parse "{\"type\": \"string\"}")))
(trivial-benchmark:with-timing (1000)
(json-schema:validate data
:schema *schema*
:schema-version :draft2019-09)))
;; - SAMPLES TOTAL MINIMUM MAXIMUM MEDIAN AVERAGE DEVIATION
;; REAL-TIME 1000 203.185 0.148 1.471 0.185 0.203185 0.112807
;; RUN-TIME 1000 9.25 0.006 0.04 0.009 0.00925 0.002294
;; USER-RUN-TIME 1000 8.145081 0.003368 0.039067 0.008105 0.008145 0.002317
;; SYSTEM-RUN-TIME 1000 1.107377 0 0.004927 0.000994 0.001107 0.000967
;; PAGE-FAULTS 1000 0 0 0 0 0 0.0
;; GC-RUN-TIME 1000 0.08 0 0.03 0 0.00008 0.001464
;; BYTES-CONSED 1000 719780512 707728 751424 718160 719780.5 11026.181
;; EVAL-CALLS 1000 0 0 0 0 0 0.0
So, for this trivial example, the cached version is around a 245x speedup! Note, though, that json-schema evaluates these things lazily, so not every reference is necessarily resolved when the context is created. They are mutable, though, and will build up state as they go.
Thank you to ‘Raymond Wiker <https://github.com/rwiker>‘_ for contributing the initial implementation.
~~~~~~~~~~~~~
Decoding JSON
~~~~~~~~~~~~~
json-schema operates mostly on :class:‘cl:hash-table‘ objects. It requires them to have the “:test“ argument set to :function:‘cl:equal‘, so that they work with string keys. Further, it expects “:true“ and “:false“ as the boolean values and “:null“ as the decoded Javascript “null“. Javascrpit arrays should be rendered as lists. This behavior is provided behind the scenes by ‘st-json <https://marijnhaverbeke.nl/st-json/>‘_. The :function:‘json-schema.parse:parse‘ function provides this functionality over strings, streams, and pathnames for you.
~~~~~~~~~~~~~~
Network access
~~~~~~~~~~~~~~
JSON Schema allows schemas to reference other documents over the network. This library will fetch them automatically, by default. If you don’t want this to be allowed, you should set :variable:‘json-schema.reference:*resolve-remote-references*‘ to “nil“. If a schema references a remote one, it will raise a :class:‘json-schema.reference:fetching-not-allowed-error‘ instead of fetching it when fetching references is disallowed.
2.0.0
alexandria (system).
arrows (system).
cl-ppcre (system).
dexador (system).
function-cache (system).
local-time (system).
local-time-duration (system).
quri (system).
sanity-clause (system).
st-json (system).
str (system).
trivial-types (system).
utils.lisp (file).
parse.lisp (file).
types.lisp (file).
reference.lisp (file).
formats.lisp (file).
validators.lisp (file).
json-schema.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
json-schema/json-schema.asdjson-schema/utils.lispjson-schema/parse.lispjson-schema/types.lispjson-schema/reference.lispjson-schema/formats.lispjson-schema/validators.lispjson-schema/json-schema.lispjson-schema/utils.lispjson-schema (system).
empty-object-p (function).
json-array (type).
json-boolean (type).
json-equal-p (function).
json-null (type).
json-pretty-printer (function).
make-empty-object (function).
object (type).
object-equal-p (function).
object-get (function).
object-keys (function).
schema (type).
schema-version (type).
json-schema/parse.lispjson-schema (system).
parse (function).
json-schema/types.lispjson-schema (system).
draft2019-09 (function).
draft3 (function).
draft4 (function).
draft6 (function).
draft7 (function).
json-schema/reference.lispjson-schema (system).
*http-connect-timeout* (special variable).
*http-read-timeout* (special variable).
*resolve-remote-references* (special variable).
context-root-schema (reader).
(setf context-root-schema) (writer).
context-schema-version (reader).
(setf context-schema-version) (writer).
fetch-schema (function).
fetching-not-allowed-error (condition).
get-id-fun-for-schema-version (function).
make-context (function).
nested-reference-error (condition).
print-object (method).
reference-error (condition).
relative-reference-p (function).
remote-reference-error (condition).
resolve (function).
with-context (macro).
with-pushed-id (macro).
with-resolved-ref (macro).
%make-context (function).
*context* (special variable).
*current-lookup-depth* (special variable).
*id-fun* (special variable).
+max-lookup-depth+ (special variable).
absolute-uri (function).
collect-subschemas (function).
context (structure).
context-named-references (reader).
(setf context-named-references) (writer).
context-p (function).
context-references (reader).
(setf context-references) (writer).
context-uri-stack (reader).
(setf context-uri-stack) (writer).
copy-context (function).
default-id-fun (function).
draft2019-09-id-fun (function).
draft4-id-fun (function).
escape (function).
fetch-reference (function).
get-current-schema (function).
get-current-uri (function).
get-ref (function).
lookup (function).
make-reference (function).
make-relative-path-list (function).
make-uri-without-fragment (function).
pop-context (function).
populate-named-references-for-schema (function).
push-context (function).
ref-p (function).
reference (class).
reference-eq (function).
relative-path-of (reader method).
(setf relative-path-of) (writer method).
unescape (function).
uri-of (reader method).
(setf uri-of) (writer method).
with-lookup-depth-tracking (macro).
with-pushed-context (macro).
json-schema/formats.lispjson-schema (system).
draft2019-09 (function).
draft3 (function).
draft4 (function).
draft6 (function).
draft7 (function).
+hostname-regex+ (constant).
+unreserved-uri-characters+ (constant).
date-time-p (function).
datep (function).
def-checker (macro).
draft3-timep (function).
durationp (function).
emailp (function).
hostnamep (function).
ip-v4-address-p (function).
ip-v6-address-p (function).
json-pointer-p (function).
regexp (function).
timep (function).
uri (function).
uri-reference (function).
json-schema/validators.lispjson-schema (system).
validate (function).
validation-failed-error (condition).
$ref (function).
*schema-version* (special variable).
additional-items (function).
additional-properties (function).
all-of (function).
any-of (function).
check-dependencies (function).
const (function).
contains (function).
def-validator (macro).
defvfun (macro).
dependencies (function).
dependent-required (function).
dependent-schemas (function).
description (function).
draft2019-09 (function).
draft4 (function).
draft6 (function).
draft7 (function).
enum (function).
exclusive-maximum (function).
exclusive-minimum (function).
format-validator (function).
if-validator (function).
items (function).
max-items (function).
max-length (function).
max-properties (function).
maximum (function).
maximum-draft4 (function).
min-items (function).
min-length (function).
min-properties (function).
minimum (function).
minimum-draft4 (function).
multiple-of (function).
no-validator-condition (condition).
noop (function).
not-validator (function).
one-of (function).
pattern (function).
pattern-properties (function).
properties (function).
property-names (function).
required (function).
type-validator (function).
unevaluated-properties (function).
unique-items (function).
validate-type (function).
json-schema/json-schema.lispjson-schema (system).
*schema-version* (special variable).
validate (function).
Packages are listed by definition order.
json-schemajson-schema.utilsjson-schema.typesjson-schema.formatsjson-schema.validatorsjson-schema.parsejson-schema.referencejson-schemaalexandria.
common-lisp.
*schema-version* (special variable).
validate (function).
json-schema.utilsalexandria.
common-lisp.
empty-object-p (function).
json-array (type).
json-boolean (type).
json-equal-p (function).
json-null (type).
json-pretty-printer (function).
make-empty-object (function).
object (type).
object-equal-p (function).
object-get (function).
object-keys (function).
schema (type).
schema-version (type).
json-schema.typesalexandria.
common-lisp.
draft2019-09 (function).
draft3 (function).
draft4 (function).
draft6 (function).
draft7 (function).
json-schema.formatsalexandria.
common-lisp.
draft2019-09 (function).
draft3 (function).
draft4 (function).
draft6 (function).
draft7 (function).
+hostname-regex+ (constant).
+unreserved-uri-characters+ (constant).
date-time-p (function).
datep (function).
def-checker (macro).
draft3-timep (function).
durationp (function).
emailp (function).
hostnamep (function).
ip-v4-address-p (function).
ip-v6-address-p (function).
json-pointer-p (function).
regexp (function).
timep (function).
uri (function).
uri-reference (function).
json-schema.validatorsalexandria.
common-lisp.
validate (function).
validation-failed-error (condition).
$ref (function).
*schema-version* (special variable).
additional-items (function).
additional-properties (function).
all-of (function).
any-of (function).
check-dependencies (function).
const (function).
contains (function).
def-validator (macro).
defvfun (macro).
dependencies (function).
dependent-required (function).
dependent-schemas (function).
description (function).
draft2019-09 (function).
draft4 (function).
draft6 (function).
draft7 (function).
enum (function).
exclusive-maximum (function).
exclusive-minimum (function).
format-validator (function).
if-validator (function).
items (function).
max-items (function).
max-length (function).
max-properties (function).
maximum (function).
maximum-draft4 (function).
min-items (function).
min-length (function).
min-properties (function).
minimum (function).
minimum-draft4 (function).
multiple-of (function).
no-validator-condition (condition).
noop (function).
not-validator (function).
one-of (function).
pattern (function).
pattern-properties (function).
properties (function).
property-names (function).
required (function).
type-validator (function).
unevaluated-properties (function).
unique-items (function).
validate-type (function).
json-schema.parsealexandria.
arrows.
common-lisp.
parse (function).
json-schema.referencealexandria.
arrows.
common-lisp.
*http-connect-timeout* (special variable).
*http-read-timeout* (special variable).
*resolve-remote-references* (special variable).
context-root-schema (reader).
(setf context-root-schema) (writer).
context-schema-version (reader).
(setf context-schema-version) (writer).
fetch-schema (function).
fetching-not-allowed-error (condition).
get-id-fun-for-schema-version (function).
make-context (function).
nested-reference-error (condition).
reference-error (condition).
relative-reference-p (function).
remote-reference-error (condition).
resolve (function).
with-context (macro).
with-pushed-id (macro).
with-resolved-ref (macro).
%make-context (function).
*context* (special variable).
*current-lookup-depth* (special variable).
*id-fun* (special variable).
+max-lookup-depth+ (special variable).
absolute-uri (function).
collect-subschemas (function).
context (structure).
context-named-references (reader).
(setf context-named-references) (writer).
context-p (function).
context-references (reader).
(setf context-references) (writer).
context-uri-stack (reader).
(setf context-uri-stack) (writer).
copy-context (function).
default-id-fun (function).
draft2019-09-id-fun (function).
draft4-id-fun (function).
escape (function).
fetch-reference (function).
get-current-schema (function).
get-current-uri (function).
get-ref (function).
lookup (function).
make-reference (function).
make-relative-path-list (function).
make-uri-without-fragment (function).
pop-context (function).
populate-named-references-for-schema (function).
push-context (function).
ref-p (function).
reference (class).
reference-eq (function).
relative-path-of (generic reader).
(setf relative-path-of) (generic writer).
unescape (function).
uri-of (generic reader).
(setf uri-of) (generic writer).
with-lookup-depth-tracking (macro).
with-pushed-context (macro).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Number of seconds before a :class:‘remote-reference-error‘ will be signaled while trying to connect to a remote schema.
Number of seconds before a :class:‘remote-reference-error‘ will be signaled while trying to read a remote schema.
Whether to download other schemas for references. Will error if another uri is referenced in a schema and this var is set to “nil“.
Fetches a remote document or raises an error depending on the value of :variable:‘*resolve-remote-references*‘.
Selects an id function that’s appropriate for each schema draft.
A generic comparison function for comparing anything that might be a json value.
Given a root schema document :param:‘schema‘ and a json schema version :param:‘schema-version‘, create a reusable context object that will cache all schema data including remote references that get fetched.
Resolves a reference schema object to the referred-to schema.
The primary validation function for json-schema. Takes data: which can be a simple value or an object as a hash table, and then optionally accepts a schema (if the data doesn’t contain a top-level “$schema“ key), schema version and pretty-errors-p deterimines whether the second return value is exception objects or strings of the rendered errors (strings by default).
The third return value is a :class:‘json-schema.reference::context‘, which contains all of the state stored in processing a schema including caching network resources and all of the resolved ids.
:uri
error.
:message
:uri
The lookup context for references.
Dynamic variable for tracking reference nesting depth.
A default function for getting ids from schemas. Should return (values id found-p) like gethash.
Maximum number of nested references to allow before throwing a :class:‘nested-reference-error‘.
Return an absolute URI for the reference in the current context.
Arrays are valid, but not strings.
Collect all named subschemas into an alist of (name . schema-object).
An id extraction function that also pays attention to $anchor properties which provide only location-independent references.
Like the default, but id doesn’t have a $ prefix.
Fetches a schema and adds it to the current context as a side effect.
JSON Schema considers anything without a fractional part an integer, ie. 1.0d0 is an integer. 🤷
Look up a schema by reference in the “*context*“. Returns “(values schema new-context-p)“. “new-context-p“ indicates that this schema is a new document that should be pushed to the context stack when visited.
This exists to say we have taken care of a property, but we should do nothing with it. Likely because this property is actually handled by other things. “else“ and “then“ are handled by :function:‘if-validator‘, &c.
Takes an alist of (uri . schema) and populates the appropriate hash tables in the named references slot of the context. Takes the output from collect subschemas, which may return named references for many uri’s, since documents are allowed to insist they have whatever uri they want whenever they want.
A spec is a reference if it has only one key which is “$ref“.
Unescape a string to replace ~0 and ~1 with ~ and /.
This is a tool for checking type validation, but isn’t a validator itself. It’s used by many of the validator functions to decide wether they can have an opinion on the data being validated, but is also used by :function:‘type-validator‘.
condition.
:field-name
A container for all state related to resolving references, namely: a stack of context urls
structure-object.
json-schema.utils:schema
json-schema.utils:schema-version
(trivial-types:proper-list string)
hash-table
(make-hash-table :test (quote equal))
hash-table
(make-hash-table :test (quote equal))
| Jump to: | $
%
(
A B C D E F G H I J L M N O P R T U V W |
|---|
| Jump to: | $
%
(
A B C D E F G H I J L M N O P R T U V W |
|---|
| Jump to: | *
+
C E F M N P R S U |
|---|
| Jump to: | *
+
C E F M N P R S U |
|---|
| Jump to: | C F J N O P R S T U V |
|---|
| Jump to: | C F J N O P R S T U V |
|---|