/ 
OpenAPI-Modern-0.104
River stage one • 5 direct dependents • 5 total dependents
⭐ Starred 6 GitHub stars
/ JSON::Schema::Modern::Document::OpenAPI

NAME

JSON::Schema::Modern::Document::OpenAPI - One OpenAPI v3.1 or v3.2 document

VERSION

version 0.104

SYNOPSIS

use JSON::Schema::Modern::Document::OpenAPI;

my $openapi_document = JSON::Schema::Modern::Document::OpenAPI->new(
  canonical_uri => 'https://example.com/v1/api',
  schema => decode_json(<<JSON),
{
"openapi": "3.2.0",
"info": {
  "title": "my title",
  "version": "1.2.3"
},
"components": {
},
"paths": {
  "/foo": {
    "get": {}
  },
  "/foo/{foo_id}": {
    "post": {}
  }
}
}
JSON
  metaschema_uri => 'https://example.com/my_custom_metaschema',
);

DESCRIPTION

Provides structured parsing of an OpenAPI document, suitable as the base for more tooling such as request and response validation, code generation or form generation.

The provided document must be a valid OpenAPI document, as specified by the schema identified by one of:

CONSTRUCTOR ARGUMENTS

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

schema

The actual raw data representing the OpenAPI document. Required.

evaluator

A JSON::Schema::Modern object which is used for parsing the schema of this document. This is the object that holds all other schemas that may be used for parsing: that is, metaschemas that define the structure of the document.

Optional, unless you are using custom metaschemas for your OpenAPI document or embedded JSON Schemas (in which case you should define the evaluator first and call "add_schema" in JSON::Schema::Modern for each customization, before calling this constructor).

This argument is not saved after object construction, so it is not available as an accessor. However, if this document object was constructed via a call to "new" in OpenAPI::Modern, it will be saved on that object for use during request and response validation, so it is expected that the evaluator object should also hold the other documents that are needed for runtime evaluation (which may be other JSON::Schema::Modern::Document::OpenAPI objects).

canonical_uri

This is the identifier that the document is known by, which is used to resolve any relative $ref keywords in the document (unless overridden by a subsequent $id in a schema). See "https://spec.openapis.org/oas/latest#relative-references-in-api-description-uris" in Specification Reference: Relative References in API Description URIs. It is strongly recommended that this URI is absolute.

In v3.2+ documents, it is used to resolve the $self value in the document itself, which then replaces this canonical_uri value.

See also "retrieval_uri".

metaschema_uri

The URI of the schema that describes the OpenAPI document itself. Defaults to https://spec.openapis.org/oas/3.2/schema-base/2025-09-17 when the "https://spec.openapis.org/oas/latest#openapi-object" in jsonSchemaDialect is not changed from its default; otherwise defaults to a dynamically generated metaschema that uses the correct value of jsonSchemaDialect, so you don't need to write one yourself.

Note that both the schemas described by metaschema_uri and by the jsonSchemaDialect keyword (if you are using custom schemas) should be loaded into the evaluator in advance with "add_schema" in JSON::Schema::Modern, and then this evaluator should be provided to the OpenAPI::Modern constructor.

METHODS

This class inherits all methods from JSON::Schema::Modern::Document. In addition:

retrieval_uri

Also available as "original_uri" in JSON::Schema::Modern::Document, this is known as the "retrieval URI" in the OAS specification: the URL the document was originally sourced from, or the URI that was used to add the document to the OpenAPI::Modern instance.

In OpenAPI version 3.1.x (but not in 3.2+), this is the same as "canonical_uri".

oas_version

The major.minor version of the OpenAPI specification being used; derived from the openapi field at the top of the document. Used to determine the required document format and all derived behaviours.

Read-only.

operationId_path

my $path = $document->operationId_path($operation_id);

Returns the json pointer location of the operation containing the provided operationId (suitable for passing to $document->get(..)), or undef if the operation does not exist in the document.

tag_path

my $path = $document->tag_path($tag_name);

Returns the json pointer location of the provided tag (suitable for passing to $document->get(..)), or undef if the tag is not defined.

Note that a tag name can still be used by an operation even if it has no definition.

operations_with_tag

Returns the list of json pointer location(s) of operations that use the provided tag.

SEE ALSO

GIVING THANKS

If you found this module to be useful, please show your appreciation by adding a +1 in MetaCPAN and a star in GitHub.

SUPPORT

Bugs may be submitted through https://github.com/karenetheridge/OpenAPI-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 and OpenAPI Slack server, which are also great resources for finding help.

AUTHOR

Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENCE

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.

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