Table of contents

March 12, 2026 · View on GitHub

s-exp.legba

default-options

Default options used by openapi-handler

Source

ensure-route-coverage!


(ensure-route-coverage! routes {:as _schema, :keys [openapi-schema]})

Checks that a map of openapi-handlers covers all paths defined by the schema

Source

handlers


(handlers routes schema-src & {:as opts})

From a map of [method path] -> ring handler returns a map of [method path] -> openapi-wrapped-handler.

Options:

  • :key-fn - Control map keys decoding when turning jackson JsonNodes to clj data for the handler - default to keyword

  • :query-string-params-key - where to find the decoded query-string parameters - defaults to :query-params

  • :validation-result - function that controls how to turn com.networknt.schema.ValidationResult into a clj -> json response. Defaults to s-exp.legba.openapi-schema/validation-result

  • :include-schema: - adds the path-relevant schema portion to the request-map under :s-exp.legba/schema (false by default)

Source

middlewares


(middlewares schema-src & {:as opts})

From a sequence of [method path] tuples returns a map of [method path] -> openapi validation middlewares.

Options:

  • :key-fn - Control map keys decoding when turning jackson JsonNodes to clj data for the handler - default to keyword

  • :query-string-params-key - where to find the decoded query-string parameters - defaults to :query-params

  • :validation-result - function that controls how to turn com.networknt.schema.ValidationResult into a clj -> json response. Defaults to s-exp.legba.openapi-schema/validation-result

  • :include-schema: - adds the path-relevant schema portion to the request-map under :s-exp.legba/schema (false by default)

  • :schema-src-type - :path (default) to load from a URI/path via read-schema, or :string to load from a raw JSON/YAML string via read-schema-str

Source

routing-handler


(routing-handler routes schema-src & {:as opts})

Same as routing-handler* but wraps with s-exp.legba.middleware/wrap-error-response middleware turning exceptions into nicely formatted error responses

Source

routing-handler*


(routing-handler* routes schema-src & {:as opts, :keys [path-params-key]})

Takes a map of routes as [method path] -> ring-handler, turns them into a map of routes to openapi handlers then creates a handler that will dispatch on the appropriate openapi handler from a potential router match. If not match is found, returns not-found-response.

Options:

  • :not-found-response - defaults to {:status 404 :body " Not found "}

  • :key-fn - Control map keys decoding when turning jackson JsonNodes to clj data for the handler - default to keyword

  • :query-string-params-key - where to find the decoded query-string parameters - defaults to :query-params

  • :validation-result - function that controls how to turn com.networknt.schema.ValidationResult into a clj -> json response. Defaults to s-exp.legba.openapi-schema/validation-result

  • :extra-routes - extra routes to be passed to the underlying router

throw and assocs the error on the ring response as response-validation-error.

Source

s-exp.legba.json

Simple utils to convert to and from jsonNode

-json-node->clj


(-json-node->clj node opts)

Source

JsonNodeToClj

Source

clj->json-node


(clj->json-node x)

Takes a clj value and converts it to a Jackson JsonNode

Source

json-content-type?


(json-content-type? content-type)

Returns true if content-type is application/json

Source

json-mapper-default

Source

json-node->clj


(json-node->clj node)
(json-node->clj node opts)

Takes a Jackson JsonNode returns an equivalent clj datastructure. :key-fn controls how map-entries keys are decoded, defaulting to keyword

Source

json-node->str


(json-node->str json-node)

Takes a Jackson JsonNode and returns an equivalent String value

Source

multipart-content-type?


(multipart-content-type? content-type)

Returns true if content-type is multipart/form-data

Source

set-mapper-defaults!


(set-mapper-defaults! object-mapper)

Sets sane defaults on jsonista, without this jsonista will do mad stuff such as serializing POJO fields as json attributes

Source

str->json-node


(str->json-node json-str)

Takes a json-str String and returns a Jackson JsonNode

Source

yaml-mapper

Source

yaml-str->json-str


(yaml-str->json-str yaml-str)

Converts a YAML string to a JSON string

Source

s-exp.legba.json-pointer

Implementation of https://datatracker.ietf.org/doc/html/rfc6901 parser and resolver

add-pointer


(add-pointer node pointer)

Adds :json-pointer metadata to node

Source

annotate-tree


(annotate-tree node)
(annotate-tree node pointer)

Walks tree and add :json-pointer metadata to every node

Source

decode-token


(decode-token token)

Decodes a single reference token according to RFC 6901.

Source

encode-token


(encode-token token)

Encodes a single reference token according to RFC 6901.

Source

parse-json-pointer


(parse-json-pointer pointer)

Parses a JSON Pointer string into a sequence of reference tokens.

Source

pointer-append


(pointer-append pointer val)

Adds value to existing json-pointer and returns a new one

Source

query


(query json-data pointer)

Resolves a JSON Pointer against a given JSON data structure.

Source

s-exp.legba.json-schema

JSON Schema validation utilities. Provides helpers to load, cache, and validate JSON Schemas

read-schema


(read-schema
 schema-uri
 &
 {:as _opts,
  :keys [schema-registry-config validate-schema],
  :or {schema-registry-config schema-registry-config, validate-schema true}})

Loads and builds a JSON Schema validator instance from a URI or file path.

Arguments: - schema-uri (string): Location of the JSON Schema (file:/..., http:/..., classpath:/..., etc)

- `:schema-registry-config` (optional): Custom

SchemaRegistryConfig (default: this namespace's schema-registry-config).

- `:validate-schema` (optional, default true): When true, validates the

loaded schema against the JSON Schema draft 2020-12 meta-schema and throws if it does not conform.

Returns:

An instance of the JSON Schema validator (`com.networknt.schema.JsonSchema`).
This object can be reused to validate multiple values or payloads.

Example: (schema "classpath:///tmp/foo.schema.json") (schema "file:///data/schema/bar.json") (schema "https://schemas.org/example.schema.json")

Source

read-schema-str


(read-schema-str
 s
 &
 {:as _opts,
  :keys [schema-uri schema-registry-config validate-schema],
  :or {schema-registry-config schema-registry-config, validate-schema true}})

Loads and builds a JSON Schema validator from a raw JSON string s.

An optional :schema-uri can be provided to anchor $ref resolution; if omitted a random urn:legba:<uuid> URI is generated.

Options mirror schema: :schema-registry-config, :validate-schema (default true).

Returns a com.networknt.schema.JsonSchema instance.

Source

schema

Alias for read-schema. Loads and builds a JSON Schema validator from a URI.

Source

schema-registry-config

Default reusable SchemaRegistryConfig instance.

This configures the validator to:

  • Enable JSON Schema reference preloading and caching
  • Enable format assertions (per the JSON Schema spec)
  • Set maximum reference nesting depth to 40
  • Handle nullable fields correctly
  • Use JSON_PATH for error paths in validation results

This config can be reused for schema load/validation for performance and consistency.

Source

validate


(validate schema val & {:as _opts, :keys [validation-result], :or {validation-result validation-result}})

Validates a value against a previously loaded or constructed schema.

Arguments: - [schema](#s-exp.legba.json-schema/schema): The schema object returned from [schema](#s-exp.legba.json-schema/schema) - val: The input to validate. Can be a JsonNode or a JSON string. - :validation-result (optional): Override for the function used to extract validation errors (defaults to this namespace's [validation-result](#s-exp.legba.json-schema/validation-result)).

Returns: A sequence of error maps (see [validation-result](#s-exp.legba.json-schema/validation-result)), or nil if valid.

Example: (validate myschema "{"foo":42}") (validate myschema my-jackson-json-node)

Source

validate!


(validate! schema val & {:as opts})

Validates a value against a given JSON Schema and throws if invalid.

Arguments: - [schema](#s-exp.legba.json-schema/schema) (JsonSchema): A schema instance created by the [schema](#s-exp.legba.json-schema/schema) function. - val: The data to validate (can be a Jackson JsonNode or a JSON string). - Optional keyword arguments: - :validation-result: Custom function to extract validation errors (defaults to this namespace's [validation-result](#s-exp.legba.json-schema/validation-result)).

Behavior: - If validation succeeds (no errors), returns nil. - If validation fails, throws an ex-info exception with: :type --> :s-exp.legba.json-schema/failed-validation :errors --> Sequence of error maps (see [validation-result](#s-exp.legba.json-schema/validation-result)). :val --> The input value that failed validation.

Example: (validate! myschema "{"name":42}") ; throws if invalid (validate! myschema my-jackson-json-node)

Useful for workflows where validation failure should abort or be handled via exception.

Source

validate-schema!


(validate-schema! user-schema)

Validates a loaded JSON Schema against the JSON Schema draft 2020-12 meta-schema. Throws an ex-info with :type :s-exp.legba.json-schema/invalid-schema and :errors if the schema does not conform.

Source

validation-result


(validation-result r)

Extracts and formats schema validation errors from a ValidationResult object.

Takes a NetworkNT ValidationResult and returns a vector of error maps, where each map contains: - :path (string) JSON path of the error location - :pointer (string) JSON pointer to the schema fragment - :location (string) Instance location in the JSON document - :detail (string) Validation error message/detail

Returns nil if there are no errors. Useful for turning validator output into a more consumable shape for clients, APIs, or error reporting.

Source

s-exp.legba.middleware

ex->response

Source

ex->rfc9457-type

Source

wrap-error-response


(wrap-error-response handler opts)

Wraps handler with error checking middleware that will transform validation Exceptions to equivalent http response, as infered per ex->response

Source

wrap-error-response-fn


(wrap-error-response-fn handler req {:as opts})

Source

wrap-validation


(wrap-validation handler schema method path {:as opts, :keys [include-schema]})

Middleware that wraps a standard RING handler with OpenAPI request and response validation. Validates both the incoming request and outgoing response according to the provided schema, for the specified HTTP method and path. Additional options:, such as including the validation schema with each request (include-schema).

Source

s-exp.legba.mime-type

match-mime-type?


(match-mime-type? mime-type-ptn mime-type)

Source

match-schema-mime-type


(match-schema-mime-type schema content-type)

Matches content-type with schema, return resulting sub-schema

Source

s-exp.legba.openapi-schema

get-schema


(get-schema schema-registry schema-uri json-pointer)

Returns json-schema from schema-registry at schema-uri/json-pointer

Source

read-schema


(read-schema schema-uri & {:as _opts, :keys [validate-schema], :or {validate-schema true}})

Loads JSON or YAML schema from schema-uri and returns map (of :openapi-schema, :schema-uri, :schema-registry) that contains all the necessary information to perform validate! calls later (minus a JSON pointer).

Source

read-schema-str


(read-schema-str s & {:as _opts, :keys [schema-uri format validate-schema], :or {validate-schema true}})

Loads a JSON or YAML OpenAPI schema from a raw string s.

An optional :schema-uri can be provided to anchor $ref resolution; if omitted a random urn:legba:<uuid> URI is generated. YAML strings are detected by the :yaml format option (:format :yaml), otherwise JSON is assumed.

Returns the same map as read-schema: {:openapi-schema … :schema-uri … :schema-registry …}.

Source

schema->routes-schema


(schema->routes-schema {:as _schema, :keys [openapi-schema]})

Source

schema-registry-config

Default reusable SchemaRegistryConfig instance.

This configures the validator to:

  • Enable JSON Schema reference preloading and caching
  • Enable format assertions (per the JSON Schema spec)
  • Set maximum reference nesting depth to 40
  • Handle nullable fields correctly
  • Use JSON_PATH for error paths in validation results

This config can be reused for schema load/validation for performance and consistency.

Source

validate


(validate
 {:as _schema, :keys [schema-uri schema-registry]}
 sub-schema
 val
 &
 {:as _opts, :keys [validation-result], :or {validation-result json-schema/validation-result}})

Validates a val against schema

Source

validate-schema!


(validate-schema! schema-registry schema-uri)

Validates a user-provided JSON schema against the OpenAPI 3.1 base schema.

Parameters:

  • schema-registry: An instance of SchemaRegistry containing preloaded schemas.
  • schema-uri: URI identifying the schema to validate (String).

Throws:

  • ex-incorrect! if the provided schema does not conform to the OpenAPI specification.
  • The exception contains a map of validation errors in :errors.

This function uses the OpenAPI 3.1 base schema loaded from the local classpath to validate the user schema and reports any problems found in a structured way.

Source

s-exp.legba.overlay

Provides overlay manipulation utilities for OpenAPI schemas, enabling dynamic updates or removals on schema documents using OpenAPI Overlay instructions. https://spec.openapis.org/overlay/latest.html

apply


(apply openapi-string overlay-string)

Apply overlay actions (update/remove) to the given OpenAPI schema string.

Parameters:

  • openapi-string: String, JSON representation of the OpenAPI schema
  • overlay-string: String, JSON representation of the overlay instructions

Returns the OpenAPI schema with all overlay actions applied as String

Source

conf

Source

s-exp.legba.request

Matches param-type for "cookie"

Source

path-params-schema

Matches param-type for "path"

Source

query-params-schema

Matches param-type for "query"

Source

validate


(validate request schema sub-schema opts)

Performs validation of RING request map

Source

validate-body


(validate-body {:as request, :keys [body headers]} schema sub-schema opts)

Performs eventual validation of request :body

Source


(validate-cookie-params request schema sub-schema opts)

Performs eventual validation of "parameters" of type "cookie"

Source

validate-method-params


(validate-method-params request schema sub-schema {:as opts, :keys [path-params-key]})

Performs extensive validation of "path" "parameters"

Source

validate-path-params


(validate-path-params request schema {:as _sub-schema, :keys [path-parameters]} {:as opts, :keys [path-params-key]})

Performs extensive validation of "path" "parameters"

Source

validate-query-params


(validate-query-params request schema sub-schema {:as opts, :keys [query-string-params-key]})

Performs eventual validation of "parameters" of type "query"

Source

s-exp.legba.response

validate


(validate response schema sub-schema opts)

Performs validation of RING response map

Source

validate-response-body


(validate-response-body {:as response, :keys [status body headers], :or {status 200}} schema sub-schema opts)

Performs eventual validation of response body

Source

validate-response-headers


(validate-response-headers {:as response, :keys [status], :or {status 200}} schema sub-schema opts)

Performs validation of response headers

Source

s-exp.legba.router

match

Source

router


(router handlers & {:as _opts, :keys [extra-routes], :or {extra-routes {}}})

Creates a router that matches by method/path for a given schema. extra-routes can be passed to add non openapi centric routes to the routing table

Source