NAME
JSON::Schema::Modern::Document::OpenAPI - One OpenAPI v3.1 document
VERSION
version 0.085
SYNOPSIS
use JSON::Schema::Modern;
use JSON::Schema::Modern::Document::OpenAPI;
my $js = JSON::Schema::Modern->new;
my $openapi_document = JSON::Schema::Modern::Document::OpenAPI->new(
evaluator => $js,
canonical_uri => 'https://example.com/v1/api',
schema => $schema,
metaschema_uri => 'https://example.com/my_custom_dialect',
);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 https://spec.openapis.org/oas/3.1/schema-base/2024-10-25.
and the OpenAPI v3.1 specification.
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. Unlike in the parent class, this is REQUIRED, because loaded vocabularies, metaschemas and resource identifiers must be stored here as they are discovered in the OpenAPI document. This is the object that will be used for subsequent evaluation of data against schemas in the document, either manually or perhaps via a web framework plugin (coming soon).
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/v3.1.1#relative-references-in-api-description-uris" in §4.6. It is strongly recommended that this URI is absolute.
See also "retrieval_uri".
json_schema_dialect
The URI of the metaschema to use for all embedded JSON Schemas in the document.
Overrides the value of jsonSchemaDialect in the document, or the specification default (https://spec.openapis.org/oas/3.1/dialect/base).
If you specify your own dialect here or in jsonSchemaDialect, then you need to add the vocabularies and schemas to the implementation yourself. (see JSON::Schema::Modern/add_vocabulary and JSON::Schema::Modern/add_schema).
Note this is NOT the same as "metaschema_uri" in JSON::Schema::Modern::Document (and metaschema_uri below), which contains the URI of the schema describing the entire document (and is not a metaschema in this case, as the entire document is not a JSON Schema).
metaschema_uri
The URI of the schema that describes the OpenAPI document itself. Defaults to https://spec.openapis.org/oas/3.1/schema-base/2024-10-25 when the json schema dialect is not changed; otherwise defaults to a dynamically generated metaschema that uses the correct value of jsonSchemaDialect, so you don't need to write one yourself.
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, this is the same as "canonical_uri".
get_operationId_path
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.
SEE ALSO
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.