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