object

open_api

OpenAPI 3.1.0 document derivation, parsing, generation, and validation built on top of the json and json_schema libraries.

Availability:
logtalk_load(open_api(loader))
Author: Paulo Moura
Version: 1:0:1
Date: 2026-06-26
Compilation flags:
static, context_switching_calls
Imports:
public http_json_term_helpers
Uses:
http_core
json
json_schema
list
url(Representation)
user
Remarks:
(none)
Inherited public predicates:
(none)

Public predicates

document/2

Derives an OpenAPI 3.1.0 document in the repository-standard JSON term representation from an object implementing the open_api_provider_protocol protocol. When the provider also implements the application_protocol protocol, missing description and license info fields may be backfilled from application metadata and homepage/1 may be mapped to the top-level externalDocs object. Top-level security defaults declared by security/1 are emitted under the root security field. Reusable security schemes declared by security_scheme/2 are emitted under components.securitySchemes and referenced scheme names and OAuth flow scopes are validated against those declarations when locally available.

Compilation flags:
static
Template:
document(Provider,Document)
Mode and number of proofs:
document(+object_identifier,-compound) - one

parse/2

Parses an OpenAPI document from the given source (file(Path), stream(Stream), codes(List), chars(List), or atom(Atom)) into the JSON term representation used by the json library.

Compilation flags:
static
Template:
parse(Source,Document)
Mode and number of proofs:
parse(++compound,--term) - one_or_error
Exceptions:
Source is a variable:
instantiation_error
Source is neither a variable nor a valid JSON source term or does not contain parsable JSON by the implementation:
domain_error(json_source,Source)

generate/2

Generates the representation specified in the first argument (file(Path), stream(Stream), codes(List), chars(List), or atom(Atom)) for an OpenAPI document term using JSON serialization.

Compilation flags:
static
Template:
generate(Sink,Document)
Mode and number of proofs:
generate(+compound,++term) - one_or_error
Exceptions:
Sink is a variable:
instantiation_error
Sink is neither a variable nor a valid JSON sink term:
domain_error(json_sink,Sink)
A JSON version of Document cannot be generated by the implementation:
domain_error(json_sink,Document)

validate_document/1

Succeeds if the given OpenAPI document term is valid according to the phase-1 OpenAPI validation schema.

Compilation flags:
static
Template:
validate_document(Document)
Mode and number of proofs:
validate_document(+term) - zero_or_one

validate_document/2

Validates an OpenAPI document term and returns a list of validation errors (empty list if valid).

Compilation flags:
static
Template:
validate_document(Document,Errors)
Mode and number of proofs:
validate_document(+term,--list) - one

operation/3

Resolves an operation descriptor exposed by a provider object using its operationId atom.

Compilation flags:
static
Template:
operation(Provider,OperationId,Operation)
Mode and number of proofs:
operation(+object_identifier,+atom,-compound) - one_or_error
Exceptions:
Provider does not expose the requested operationId:
existence_error(open_api_operation,OperationId)
Provider exposes duplicated operationId values:
domain_error(open_api_operation_id,duplicate(Id))

validate_request/3

Succeeds when the given normalized HTTP request term or object implementing the http_request_protocol protocol conforms to the provider operation descriptor identified by the given operationId.

Compilation flags:
static
Template:
validate_request(Provider,OperationId,Request)
Mode and number of proofs:
validate_request(+object_identifier,+atom,++term) - zero_or_one

validate_request/4

Validates a normalized HTTP request term or an object implementing the http_request_protocol protocol against the provider operation descriptor identified by the given operationId and returns any contract errors.

Compilation flags:
static
Template:
validate_request(Provider,OperationId,Request,Errors)
Mode and number of proofs:
validate_request(+object_identifier,+atom,++term,--list) - one

validate_http_request/3

Succeeds when an HTTP request wire source parsed by the http_core library conforms to the provider operation descriptor identified by the given operationId.

Compilation flags:
static
Template:
validate_http_request(Provider,OperationId,Source)
Mode and number of proofs:
validate_http_request(+object_identifier,+atom,++compound) - zero_or_one

validate_http_request/4

Parses an HTTP request wire source using the http_core library and validates the resulting normalized request against the provider operation descriptor identified by the given operationId.

Compilation flags:
static
Template:
validate_http_request(Provider,OperationId,Source,Errors)
Mode and number of proofs:
validate_http_request(+object_identifier,+atom,++compound,--list) - one

validate_response/3

Succeeds when the given normalized HTTP response term or object implementing the http_response_protocol protocol conforms to the provider operation descriptor identified by the given operationId.

Compilation flags:
static
Template:
validate_response(Provider,OperationId,Response)
Mode and number of proofs:
validate_response(+object_identifier,+atom,++term) - zero_or_one

validate_response/4

Validates a normalized HTTP response term or an object implementing the http_response_protocol protocol against the provider operation descriptor identified by the given operationId and returns any contract errors.

Compilation flags:
static
Template:
validate_response(Provider,OperationId,Response,Errors)
Mode and number of proofs:
validate_response(+object_identifier,+atom,++term,--list) - one

validate_http_response/3

Succeeds when an HTTP response wire source parsed by the http_core library conforms to the provider operation descriptor identified by the given operationId.

Compilation flags:
static
Template:
validate_http_response(Provider,OperationId,Source)
Mode and number of proofs:
validate_http_response(+object_identifier,+atom,++compound) - zero_or_one

validate_http_response/4

Parses an HTTP response wire source using the http_core library and validates the resulting normalized response against the provider operation descriptor identified by the given operationId.

Compilation flags:
static
Template:
validate_http_response(Provider,OperationId,Source,Errors)
Mode and number of proofs:
validate_http_response(+object_identifier,+atom,++compound,--list) - one

json_media_descriptor/2

Constructs an OpenAPI JSON media descriptor using the default application/json media type.

Compilation flags:
static
Template:
json_media_descriptor(Schema,MediaDescriptor)
Mode and number of proofs:
json_media_descriptor(++term,-compound) - one_or_error
Exceptions:
Schema is a variable:
instantiation_error
Schema is neither a boolean schema nor a JSON object schema term nor a schema_ref/1 term:
domain_error(open_api_json_schema_term,Schema)

json_media_descriptor/3

Constructs an OpenAPI JSON media descriptor using the given media type.

Compilation flags:
static
Template:
json_media_descriptor(MediaType,Schema,MediaDescriptor)
Mode and number of proofs:
json_media_descriptor(+atom,++term,-compound) - one_or_error
Exceptions:
MediaType is a variable:
instantiation_error
MediaType is neither a variable nor a JSON-compatible HTTP media type atom:
domain_error(open_api_media_type,MediaType)
Schema is a variable:
instantiation_error
Schema is neither a boolean schema nor a JSON object schema term nor a schema_ref/1 term:
domain_error(open_api_json_schema_term,Schema)

json_request_body_descriptor/4

Constructs an OpenAPI request-body descriptor using the default application/json media type.

Compilation flags:
static
Template:
json_request_body_descriptor(Description,Required,Schema,RequestBody)
Mode and number of proofs:
json_request_body_descriptor(+atom,+boolean,++term,-compound) - one_or_error
Exceptions:
Description is a variable:
instantiation_error
Description is neither a variable nor an atom:
domain_error(open_api_description,Description)
Required is a variable:
instantiation_error
Required is neither a variable nor a boolean:
domain_error(open_api_boolean,Required)
Schema is a variable:
instantiation_error
Schema is neither a boolean schema nor a JSON object schema term nor a schema_ref/1 term:
domain_error(open_api_json_schema_term,Schema)

json_request_body_descriptor/5

Constructs an OpenAPI request-body descriptor using the given media type.

Compilation flags:
static
Template:
json_request_body_descriptor(MediaType,Description,Required,Schema,RequestBody)
Mode and number of proofs:
json_request_body_descriptor(+atom,+atom,+boolean,++term,-compound) - one_or_error
Exceptions:
MediaType is a variable:
instantiation_error
MediaType is neither a variable nor a JSON-compatible HTTP media type atom:
domain_error(open_api_media_type,MediaType)
Description is a variable:
instantiation_error
Description is neither a variable nor an atom:
domain_error(open_api_description,Description)
Required is a variable:
instantiation_error
Required is neither a variable nor a boolean:
domain_error(open_api_boolean,Required)
Schema is a variable:
instantiation_error
Schema is neither a boolean schema nor a JSON object schema term nor a schema_ref/1 term:
domain_error(open_api_json_schema_term,Schema)

json_response_descriptor/4

Constructs an OpenAPI response descriptor using the default application/json media type.

Compilation flags:
static
Template:
json_response_descriptor(Status,Description,Schema,ResponseDescriptor)
Mode and number of proofs:
json_response_descriptor(++term,+atom,++term,-compound) - one_or_error
Exceptions:
Status is a variable:
instantiation_error
Status is neither a variable nor default nor an integer in the 100..599 range nor a wildcard status atom such as '2XX':
domain_error(open_api_response_status,Status)
Description is a variable:
instantiation_error
Description is neither a variable nor an atom:
domain_error(open_api_description,Description)
Schema is a variable:
instantiation_error
Schema is neither a boolean schema nor a JSON object schema term nor a schema_ref/1 term:
domain_error(open_api_json_schema_term,Schema)

json_response_descriptor/5

Constructs an OpenAPI response descriptor using the given media type.

Compilation flags:
static
Template:
json_response_descriptor(Status,Description,MediaType,Schema,ResponseDescriptor)
Mode and number of proofs:
json_response_descriptor(++term,+atom,+atom,++term,-compound) - one_or_error
Exceptions:
Status is a variable:
instantiation_error
Status is neither a variable nor default nor an integer in the 100..599 range nor a wildcard status atom such as '2XX':
domain_error(open_api_response_status,Status)
Description is a variable:
instantiation_error
Description is neither a variable nor an atom:
domain_error(open_api_description,Description)
MediaType is a variable:
instantiation_error
MediaType is neither a variable nor a JSON-compatible HTTP media type atom:
domain_error(open_api_media_type,MediaType)
Schema is a variable:
instantiation_error
Schema is neither a boolean schema nor a JSON object schema term nor a schema_ref/1 term:
domain_error(open_api_json_schema_term,Schema)

problem_json_schema/1

Returns an inline RFC 7807-compatible JSON schema for problem responses.

Compilation flags:
static
Template:
problem_json_schema(Schema)
Mode and number of proofs:
problem_json_schema(-term) - one

problem_response_descriptor/3

Constructs an OpenAPI problem-response descriptor using the application/problem+json media type and the default problem schema.

Compilation flags:
static
Template:
problem_response_descriptor(Status,Description,ResponseDescriptor)
Mode and number of proofs:
problem_response_descriptor(++term,+atom,-compound) - one_or_error
Exceptions:
Status is a variable:
instantiation_error
Status is neither a variable nor default nor an integer in the 100..599 range nor a wildcard status atom such as '2XX':
domain_error(open_api_response_status,Status)
Description is a variable:
instantiation_error
Description is neither a variable nor an atom:
domain_error(open_api_description,Description)

Protected predicates

(no local declarations; see entity ancestors if any)

Private predicates

(no local declarations; see entity ancestors if any)

Operators

(none)

See also

json, json_schema, application_protocol, open_api_provider_protocol