JSON::Schema::Modern::Document(3pm)

NAME
JSON::Schema::Modern::Document - One JSON Schema document

VERSION
version 0.642

I use a linearly-increasing version numbering scheme. No meaning should be presumed or inferred from the version being less than 1.0.

SYNOPSIS
    use JSON::Schema::Modern::Document;

    my $document = JSON::Schema::Modern::Document->new(
      canonical_uri => 'https://example.com/v1/schema',
      schema => $schema,
    );
    my $foo_definition = $document->get('/$defs/foo');
    my %resource_index = $document->resource_index;
    my $metaschema_uri = $document->metaschema_uri;

DESCRIPTION
This class represents one JSON Schema document, to be used by JSON::Schema::Modern.

CONSTRUCTOR ARGUMENTS
Unless otherwise noted, these are also available as read-only accessors.

  schema
The actual raw data representing the schema. Required.

  canonical_uri
As a constructor value, represents the initial URI by which the document should be known, or a base URI to use to determine that value. The URI found in the root schema's $id keyword is resolved against this URI to determine the final value, which is then stored in this accessor. As such, it can be considered the canonical URI for the document as a whole, from which subsequent $ref keywords are resolved.

The original passed-in value is saved in "original_uri".

  metaschema_uri
Sets the metaschema that is used to describe the document (or more specifically, any JSON Schemas contained within the document), which determines the specification version and vocabularies used during evaluation. Does not override any $schema keyword actually present in the schema document, and normally you should use this keyword instead.

  specification_version
Only a constructor argument, not an accessor method.

Indicates which version of the JSON Schema specification is used during evaluation. This value is overridden by the value determined from the $schema keyword in the schema used in evaluation (when present), or defaults to the latest version (currently "draft2020-12").

The use of the $schema keyword in your schema is HIGHLY encouraged to ensure continued correct operation of your schema. The current default value will not stay the same over time.

May be one of:

•   "draft2020-12" or "2020-12" <https://json-schema.org/specification-links.html#2020-12>, corresponding to metaschema "https://json-schema.org/draft/2020-12/schema"

•   "draft2019-09" or "2019-09" <https://json-schema.org/specification-links.html#2019-09-formerly-known-as-draft-8>, corresponding to metaschema "https://json-schema.org/draft/2019-09/schema"

•   "draft7" or 7 <https://json-schema.org/specification-links.html#draft-7>, corresponding to metaschema "http://json-schema.org/draft-07/schema#"

•   "draft6" or 6 <https://json-schema.org/specification-links.html#draft-6>, corresponding to metaschema "http://json-schema.org/draft-06/schema#"

•   "draft4" or 4 <https://json-schema.org/specification-links.html#draft-4>, corresponding to metaschema "http://json-schema.org/draft-04/schema#"

  evaluator
A JSON::Schema::Modern object. Optional, unless custom metaschemas are used (see notes below under "validate").

This argument is not preserved by the constructor, so it is not available as an accessor.

  skip_ref_checks
Only a constructor argument, not an accessor method.

When true, the normal checks for bad reference targets are skipped. This should only be used for large documents that are known to be valid, such as specification metaschemas.

METHODS

  errors
Returns a list of JSON::Schema::Modern::Error objects that resulted when the schema document was originally parsed. (If a syntax error occurred, usually there will be just one error, as parse errors halt the parsing process.) Documents with errors cannot be used for evaluation.

  original_uri
Returns the original value of "canonical_uri" that was passed to the document constructor (which $id keywords within the document would have been resolved against, if they were not already absolute). Some subclasses may make use of this value for resolving URIs when matching HTTP requests at runtime.

This URI is not added to the document's resource index, so if you want the document to be addressable at this location you must add it to the evaluator yourself with the two-argument form of "add_document" in JSON::Schema::Modern.

Read-only.

  resource_index
An index of URIs to subschemas (JSON pointer to reach the location, and the canonical URI of that location) for all identifiable subschemas found in the document. An entry for URI '' is added only when no other suitable identifier can be found for the root schema.

This attribute should only be used by JSON::Schema::Modern and not intended for use externally (you should use the public accessors in JSON::Schema::Modern instead).

When called as a method, returns the flattened list of tuples (path, uri). You can also use "resource_pairs" which returns a list of tuples as arrayrefs.

  contains
Check if "schema" contains a value that can be identified with the given JSON Pointer. See "contains" in Mojo::JSON::Pointer.

  get
Extract value from "schema" identified by the given JSON Pointer. See "get" in Mojo::JSON::Pointer.

  validate
  $result = JSON::Schema::Modern::Document->validate(<normal constructor arguments>);

Constructs the document object, and then performs a further sanity check by evaluating the document against its metaschema. (See "evaluate" in JSON::Schema::Modern.) This is preferred to simply attempting to add the document to the evaluator with "add_schema" in JSON::Schema::Modern in cases where the document's sanity is not known, as that method will die if errors are encountered.

As with calling "new", if the document's metaschema is one of the core bundled metaschemas (see "BUNDLED META-SCHEMAS" in JSON::Schema::Modern), the $evaluator argument is optional, as these metaschemas are available to all evaluator instances; otherwise (you are using a custom metaschema), you must provide the same evaluator instance as would be used to construct the document object.

Returns a JSON::Schema::Modern::Result object containing the final result.

See also "validate_schema" in JSON::Schema::Modern, which is nearly equivalent but only works for JSON Schemas, not any potential subclass of JSON::Schema::Modern::Document.

  TO_JSON
Returns a data structure suitable for serialization. See "schema".

SUBCLASSING
This class can be subclassed to describe documents of other types, which follow the same basic model (has a document-level identifier and may contain internal referenceable identifiers). The overall document itself may not be a JSON Schema, but it may contain JSON Schemas internally. Referenceable entities may or may not be JSON Schemas. As long as the "traverse" method is implemented and the $state object is respected, any other functionality may be contained by this subclass. The "traverse" method is responsible for finding any identifiers within the document, setting "canonical_uri" and "metaschema_uri", and finding any $refabble entities within the document.

To date, there is one subclass of JSON::Schema::Modern::Document: JSON::Schema::Modern::Document::OpenAPI, which contains entities of type "schema" as well as others (e.g. "request-body", "response", "path-item", etc). An object of this class represents one OpenAPI document, used by OpenAPI::Modern to specify application APIs.

SEE ALSO

•   JSON::Schema::Modern

•   Mojo::JSON::Pointer

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>.

SUPPORT
Bugs may be submitted through <https://github.com/karenetheridge/JSON-Schema-Modern/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.

AUTHOR
Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENCE
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.