JSON::...ilities(3pm)

📦
version 0.642 · 4 versions
, in ubuntu stonking

💖 NAME 💖

okay so bestie, welcome to JSON::Schema::Modern::Utilities — that's this page right here (JSON::...ilities(3pm) in your man viewer, yes the header is doing ✨aesthetic truncation✨, we love her). It's the internal utilities toolkit for JSON::Schema::Modern. Internal! Like, backstage crew energy. 🎀

🦋 VERSION 🦋

version 0.642

ngl the versioning here has a whole personality: I use a linearly-increasing version numbering scheme. No meaning should be presumed or inferred from the version being less than 1.0. Like, 0.99 is not "almost there" — it's just the next number. Chill. 😌

✨ SYNOPSIS ✨

use JSON::Schema::Modern::Utilities qw(func1 func2..);

that's it, that's the vibe. import your lil functions and go 🫶

🌸 DESCRIPTION 🌸

This class contains internal utilities to be used by JSON::Schema::Modern, and other useful helpers. so they're technically for the module itself, but hey, helpers are helpers, come get y'all juice. 💅

🔥 FUNCTIONS 🔥

⭐ is_type

if (is_type('string', $value)) { ... }

Returns a boolean, bestie — is the value you handed it one of the specified core types ("null", "boolean", "string", "number", "object", "array") or "integer"? yes/no, iconic/no. 😻

It also optionally takes a hashref { legacy_ints => 1 } which says: apply draft4 number semantics. which matters because, unlike later drafts, in draft4 2.0 is not an integer. the drama of it all.

⭐ get_type

my $type = get_type($value);

Returns one of the core types ("null", "boolean", "string", "number", "object", "array") or "integer". Same optional hashref dealie: { legacy_ints => 1 } for draft4 number semantics. Behaviour is consistent with is_type — they're twins, they coordinate, periodt. 👯

⭐ is_bool

if (is_bool($value)) { ... }

Literal equivalent of is_type('boolean', $value). Accepts JSON booleans and builtin booleans, but not dualvars (because JSON encoders do not recognize these as booleans). so if you're out here passing dualvars expecting a true... no. 🚫

⭐ is_schema

if (is_schema($value)) { ... }

Equivalent to is_type('object') || is_type('boolean'). short king of a function, does exactly one thing, loves it. 💜

⭐ is_equal

if (not is_equal($x, $y, my $state = {})) {
  say "values differ starting at $state->{path}: $state->{error}";
}

Compares two arbitrary data payloads for equality, as per Instance Equality in the JSON Schema draft2020-12 specification: https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.4.2.2

The optional third argument hashref supports the following fields:

  • "scalarref_booleans" (provided by caller input): as in "scalarref_booleans" in JSON::Schema::Modern
  • "stringy_numbers" (provided by caller input): when set, strings will also be compared numerically, as in "stringy_numbers" in JSON::Schema::Modern
  • "path" (populated by function): if result is false, the json pointer location of the first difference
  • "error" (populated by function): if result is false, an error description of the first difference

⭐ is_elements_unique

if (not is_elements_unique($arrayref, my $state = {}) {
  say "lists differ starting at $state->{path}: $state->{error}";
}

Compares all elements of an arrayref for uniqueness. the "no dupes allowed" check, we stan a rigorous list. 🧚

The optional second argument hashref supports the same options as is_equal, plus:

  • "equal_indices" (populated by function): if result is false, the list of indices of the (first set of) equal items found.

⭐ jsonp

# '/paths/~1foo~1{foo_id}/get/responses'
my $jsonp = jsonp(qw(/paths /foo/{foo_id} get responses));

Constructs a json pointer string from a list of path components, with correct escaping — and yes babe, escaping matters, that's the whole point. 🎀

The first argument must be '' or an already-escaped json pointer, to which the rest of the path components are appended after being escaped.

⭐ unjsonp

# ('', 'paths', '/foo/{foo_id}', 'get', 'responses')
my @components = unjsonp('/paths/~1foo~1{foo_id}/get/responses');

Splits a json pointer string into its path components, with correct unescaping. the un- girlie. 💅

⭐ jsonp_get

# 4
my $val = jsonp_get({ a => 1, b => { c => 3, d => 4 } }, '/b/d');

Returns the value of a data structure at a particular json pointer location. digs in, grabs the thing, no notes. 🔍

⭐ jsonp_elements

# {
#   '/a/b/0' => 'x',
#   '/a/b/1' => 'y',
#   '/a/c/d' => 'e',
# }
jsonp_elements({ a => { b => [ 'x', 'y' ], c => { d => 'e' } } });

Returns all the ( json pointer => value ) tuples of a data structure as a hashref. every single one. we're thorough here. 🫶

⭐ jsonp_set

my $data = { a => 1, b => { c => 3, d => 4 } };
my $defaults = {
  '/b/d' => 5,
  '/b/e' => 6,
  '/f' => 7,
  '/g/h/i/1' => [ 10 ],
};
jsonp_set($data, $_, $defaults->{$_}) foreach keys %$defaults;

# data is now:
# { a => 1, b => { c => 3, d => 5, e => 6 }, f => 7, g => { h => { i => [ undef, [ 10 ] ] } } }

Given an arbitrary data structure, a json pointer string, and an arbitrary value, assigns that value to the given position in the data structure.

⚠️ bestie. this is a destructive operation. it overwrites whatever data was there before if needed — even if an incompatible type: e.g. a hash key will overwrite an existing arrayref. 😭 Intermediary keys or indexes will spring into existence as needed. it does not ask permission. it does not text first. 💀

⭐ json_pointer_type

A Type::Tiny type representing a json pointer string.

⭐ canonical_uri_type

A Type::Tiny type representing a canonical URI: a Mojo::URL with either no fragment, or with a json pointer fragment.

⭐ core_types_type

A Type::Tiny type representing the core JSON Schema types.

⭐ core_formats_type

A Type::Tiny type representing the core JSON Schema formats (across all supported versions).

⭐ load_cached_document

my $evaluator = JSON::Schema::Modern->new;
my $uri = 'https://json-schema.org/draft-07/schema#';
my $document = load_cached_document($evaluator, $uri);

my $result = $evaluator->evaluate($data, $uri);

Loads a document object from global cache, loading data from disk if needed.

🚨 heads up: this should only be used for officially-published schemas and metaschemas that are bundled with this distribution or another related one. don't be out here pointing it at random stuff bestie, i'm begging. 🙈

⭐ add_media_type

add_media_type('application/my_zip', $decoder_sub, $encoder_sub);
add_media_type('audio/*; version=1', $decoder_sub, $encoder_sub);

Adds a media-type entry to the registry, or replaces an existing one. This registry is runtime-global, available to any code running in this process. everybody in the process can see it. main character registry energy. 👑

Either or both of the subrefs are optional (use "undef" for the decoder sub if you only want an encoder); the subref is expected to have the following signature:

sub ($content_ref, $parameters = {}, @)

The subref will be called with a reference to the content string, and a hashref of the parameters that were parsed from the "Content-Type" header (if any). Extra arguments are allowed to allow for future flexibility with this interface.

These media types are already defined:

Media-type definitions can be overridden with a new call to "add_media_type". so if you don't like one, you literally just call it again. slay.

See the official OpenAPI Media Type Registry: https://spec.openapis.org/registry/media-type for a registry of known and useful media types; for compatibility reasons, avoid defining a media type listed here with different semantics. fr fr, do not.

⭐ delete_media_type

delete_media_type('application/my_zip');

Removes a media-type entry from the registry.

✨ important: the string must match exactly, including case and whitespace. no vibes-based matching here, it's giving strict. 💅

⭐ decode_media_type

my $content_ref = decode_media_type('text/plain; charset=UTF-8', \'encoded text');

Finds the best-matching media-type decoder for the given media-type and decodes the content (which must be passed as a reference); returns a reference to the decoded content, or "undef" if no matching decoder could be found. An exception might be thrown if the data could not be successfully decoded. 😬

⭐ encode_media_type

my $content_ref = encode_media_type('text/plain; charset=UTF-8', \[ 'decoded content' ]);

Finds the best-matching media-type encoder for the given media-type and encodes the content (which must be passed as a reference); returns a reference to the encoded content, or "undef" if no matching encoder could be found. An exception might be thrown if the data could not be successfully encoded. same energy, other direction. 🔁

⭐ match_media_type

my $registered_media_type = match_media_type('text/html');
my $ad_hoc_media_type = match_media_type('text/html', [ 'text/plain', 'text/*' ]);

Finds the best match for a "Content-Type" header value from the media-types in the registry, or from an ad-hoc list reference provided in the second argument.

Types with structured suffixes will match more generic types when an exact match is not available (e.g. "application/schema+json" will match an entry for "application/json"). it's giving "close enough, family". 🫶

Exact matches to the "type/subtype" name are preferred over wildcard matches (e.g. "text/*"); if parameters are present in the value being matched against (the list of registered media-types, or the list provided to this sub), all parameters must be present and match exactly.

Comparisons of type and subtype are done case-insensitively; parameter comparison is case-sensitive, with the exception of "charset" in "text/plain". yes, it's specific. no, we won't apologise. 💅

💖 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-Modern) and a star in GitHub (https://github.com/karenetheridge/JSON-Schema-Modern). it costs you literally nothing and it makes someone's whole day, bestie. 🥹⭐

🎀 SUPPORT 🎀

Bugs may be submitted through https://github.com/karenetheridge/JSON-Schema-Modern/issues. (or you can just tell me, i'm around 👀)

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. come say hi, it's a good time. 🌸

🦋 AUTHOR 🦋

Karen Etheridge <ether@cpan.org>

This software is copyright (c) 2020 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.

Some schema files have their own licence, in share/LICENSE.

and that's the whole page, bestie!! 💖✨ this one was rendered by perl v5.40.1, dated 2026-07-31, and it's the JSON::...ilities(3pm) page — go forth and be a json pointer girlie, you got this 🫶🌈

📦 where this page comes from