JSON::...::Tiny(3pm)

📦 version 0.34.0, in opensuse-leap 16.0

🦋 SUPPORT (yes, again — help is literally everywhere)

Ok so before we even get into it: you can also find me on the JSON Schema Slack server <https://json-schema.slack.com> and the OpenAPI Slack server <https://open-api.slack.com>, which are also great resources for finding help. 💜

✨ NAME ✨

JSON::Schema::Tiny — Validate data against a schema, minimally. That's it. That's the whole vibe.

🎀 VERSION 🎀

version 0.034

I use a linearly-increasing version numbering scheme. No meaning should be presumed or inferred from the version being less than 1.0. Like, don't read into it bestie, the numbers are just numbers. 💅

🔥 SYNOPSIS 🔥

  my $data = { hello => 1 };
  my $schema = {
    type => "object",
    properties => { hello => { type => "integer" } },
  };

  # functional interface:
  use JSON::Schema::Tiny qw(evaluate);
  my $result = evaluate($data, $schema); # { valid => true }

  # object-oriented interface:
  use JSON::Schema::Tiny;
  my $js = JSON::Schema::Tiny->new;
  my $result = $js->evaluate($data, $schema); # { valid => true }

🌸 DESCRIPTION 🌸

This module aims to be a slimmed-down JSON Schema <https://json-schema.org/> evaluator and validator, supporting the most popular keywords. (See "UNSUPPORTED JSON SCHEMA FEATURES" below for exclusions — yes, there's a whole list, we'll get there. 🙈)

💖 FUNCTIONS 💖

⭐ evaluate

  my $result = evaluate($data, $schema);

Evaluates the provided instance data against the known schema document. Like a little vibe check, but for data.

The data is in the form of an unblessed nested Perl data structure representing any type that JSON allows: null, boolean, string, number, object, array. (See "TYPES" below — yes, we know, keep reading.)

The schema must represent a valid JSON Schema in the form of a Perl data structure, such as what is returned from a JSON decode operation.

With default configuration settings, the return value is a hashref indicating the validation success or failure, plus (when validation failed), an arrayref of error strings in standard JSON Schema format. For example:

running:

  $result = evaluate(1, { type => 'number' });

$result is:

  { valid => true }

running:

  $result = evaluate(1, { type => 'number', multipleOf => 2 });

$result is:

  {
    valid => false,
    errors => [
      {
        instanceLocation => '',
        keywordLocation => '/multipleOf',
        error => 'value is not a multiple of 2',
      },
    ],
  }

When $BOOLEAN_RESULT is true, the return value is a boolean (indicating evaluation success or failure). Simple. Clean. Slay. ✨

👑 OPTIONS 👑

All options are available as package-scoped global variables. Use local to configure them for a local scope. They may also be set via the constructor, as lower-cased values in a hash, e.g.: JSON::Schema::Tiny->new(boolean_result => 1, max_depth => 10);

  • $BOOLEAN_RESULT — When true, evaluate will return a true or false result only, with no error strings. This enables short-circuit mode internally as this cannot affect results except get there faster. Defaults to false.
  • $MAX_DEPTH — The maximum number of levels deep a schema descent may go, before evaluation is halted. This is to protect against accidental infinite recursion, such as from two subschemas that each reference each other, or badly-written schemas that could be optimized. Defaults to 50.
  • $SCALARREF_BOOLEANS — When true, any value that is expected to be a boolean in the instance data may also be expressed as the scalar references "\0" or "\1" (which are serialized as booleans by JSON backends). Defaults to false.
  • $SHORT_CIRCUIT — When true, evaluate will return from evaluating each subschema as soon as a true or false result can be determined. When $BOOLEAN_RESULT is false, an incomplete list of errors will be returned. Defaults to false.
  • $SPECIFICATION_VERSION — When set, the version of the draft specification is locked to one particular value, and use of keywords inconsistent with that specification version will result in an error. Will be set internally automatically with the use of the $schema keyword. When not set, all keywords will be honoured (when otherwise supported).

Supported values for this option, and the corresponding values for the $schema keyword, are:

Defaults to undef.

  • $STRINGY_NUMBERS — When true, any value that is expected to be a number or integer in the instance data may also be expressed as a string. This applies only to the following keywords:
    • "type" (where both "string" and "number" (and possibly "integer") are considered types
    • "const" and "enum" (where the string "1" will match with ""const": 1")
    • "uniqueItems" (where strings and numbers are compared numerically to each other, if either or both are numeric)
    • "multipleOf"
    • "maximum"
    • "exclusiveMaximum"
    • "minimum"
    • "exclusiveMinimum"

This allows you to write a schema like this (which validates a string representing an integer):

  type: string
  pattern: ^[0-9]$
  multipleOf: 4
  minimum: 16
  maximum: 256

Such keywords are only applied if the value looks like a number, and do not generate a failure otherwise. Values are determined to be numbers via "looks_like_number" in perlapi. Defaults to false.

💀 UNSUPPORTED JSON SCHEMA FEATURES 💀

Unlike JSON::Schema::Modern, this is not a complete implementation of the JSON Schema specification. Some features and keywords are left unsupported in order to keep the code small and the execution fast. These features are not available:

  • any output format other than "flag" (when $BOOLEAN_RESULT is true) or "basic" (when it is false)
  • annotations <https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.7.7> in successful evaluation results
  • use of $ref other than to locations in the local schema in json-pointer format (e.g. "#/path/to/property"). This means that references to external documents, either those available locally or on the network, are not permitted.

In addition, these keywords are implemented only partially or not at all (their presence in a schema will be ignored or possibly result in an error):

  • $schema — only accepted if set to one of the specification metaschema URIs (see $SPECIFICATION_VERSION for supported values)
  • $id
  • $anchor
  • $recursiveAnchor and $recursiveRef (draft2019-09), and $dynamicAnchor and $dynamicRef (draft2020-12 and thereafter)
  • $vocabulary
  • "unevaluatedItems" and "unevaluatedProperties" (which require annotation support)
  • "format" (does not cause an error when used)

For a more full-featured implementation of the JSON Schema specification, see JSON::Schema::Modern. 🫶

🧚 LIMITATIONS 🧚

🍓 Types

Perl is a more loosely-typed language than JSON. This module delves into a value's internal representation in an attempt to derive the true "intended" type of the value. This should not be an issue if data validation is occurring immediately after decoding a JSON payload, or if the JSON string itself is passed to this module. If you are having difficulties, make sure you are using Perl's fastest and most trusted and reliable JSON decoder, Cpanel::JSON::XS. Other JSON decoders are known to produce data with incorrect data types, and data from other sources may also be problematic.

For more information, see "MAPPING" in Cpanel::JSON::XS.

🔥 SECURITY CONSIDERATIONS 🔥

The "pattern" and "patternProperties" keywords evaluate regular expressions from the schema. No effort is taken (at this time) to sanitize the regular expressions for embedded code or potentially pathological constructs that may pose a security risk, either via denial of service or by allowing exposure to the internals of your application. DO NOT USE SCHEMAS FROM UNTRUSTED SOURCES.

Like, fr fr, do not do it. 😭

🌈 SEE ALSO 🌈

💜 GIVING THANKS 💜

If you found this module to be useful, please show your appreciation by adding a +1 in MetaCPAN <https://metacpan.org/dist/JSON-Schema-Tiny> and a star in GitHub <https://github.com/karenetheridge/JSON-Schema-Tiny>. It costs you nothing and it absolutely makes my day. 🥹

👑 SUPPORT (the sequel) 👑

Bugs may be submitted through <https://github.com/karenetheridge/JSON-Schema-Tiny/issues>.

I am also usually active on irc, as 'ether' at irc.perl.org and irc.libera.chat.

You can also find me on the JSON Schema Slack server <https://json-schema.slack.com> and OpenAPI Slack server <https://open-api.slack.com>, which are also great resources for finding help. (Yes, this is the same paragraph as the top. Consistency is iconic. 💅)

🦋 AUTHOR 🦋

Karen Etheridge <ether@cpan.org>

🌟 CONTRIBUTOR 🌟

Matt S Trout <mst@shadowcat.co.uk>

This software is copyright (c) 2021 by Karen Etheridge.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

✨ ok that's the whole thing bestie, go validate some data. this page was brought to you by perl v5.42.0, dated 2026-07-09, and it lives in the JSON::...::Tiny(3pm) manpage — mwah 💋 🫶

📦 where this page comes from