protocol

# `open_api_provider_protocol`

Protocol for Logtalk objects that provide metadata used to derive OpenAPI 3.1.0 documents.

Availability:
`logtalk_load(open_api(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-06-08
Compilation flags:
`static`
Dependencies:
(none)
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `api_info/1`

Returns the API metadata descriptor. The descriptor must be the compound term `info(Title, Version, Summary, Properties)` where `Title`, `Version`, and `Summary` are atoms and `Properties` is a list of optional metadata terms. Currently recognized properties: `description(Description)` where `Description` is an atom.

Compilation flags:
`static`
Template:
`api_info(Info)`
Mode and number of proofs:
`api_info(-compound)` - `one`

### `servers/1`

Returns a list of server descriptors available for this API. Each descriptor must be a compound term `server(URL, Description)` where `URL` is a valid OpenAPI Server Object URL atom, allowing absolute URLs, relative references, and templated variables, and `Description` is a human-readable atom.

Compilation flags:
`static`
Template:
`servers(Servers)`
Mode and number of proofs:
`servers(-list(compound))` - `one`

### `security/1`

Returns the top-level OpenAPI security requirement alternatives for this API. The returned list uses the same representation as operation `security(Requirements)` properties: each element is a requirement alternative represented as a list of `Scheme-Scopes` pairs and `[]` denotes an empty security requirement object. Scheme names must be declared by `security_scheme/2`.

Compilation flags:
`static`
Template:
`security(Security)`
Mode and number of proofs:
`security(-list(compound))` - `zero_or_one`

### `operations/1`

Returns a list of operation descriptors exposed by this API. Each descriptor must be a compound term `operation(Id, Method, Path, Summary, Parameters, RequestBody, Responses, Properties)` where `Id` is an atom and unique across the returned descriptors, `Method` is a lowercase HTTP method atom, `Path` is a path-template atom, `Summary` is an atom, `Parameters` is a list of `parameter(Name, In, Description, Required, Schema)` terms, `RequestBody` is either `none` or `request_body(Description, Required, MediaTypes)`, `Responses` is a list of `response(Status, Description, MediaTypes)` terms, and `Properties` is a list of optional operation property terms. `Status` may be an integer HTTP status code, `default`, or a wildcard range atom such as `'2XX'`. Path parameters must use `In = path`, match a template expression in `Path`, and use `Required = true`. Currently recognized property terms are `description(Description)`, `tags(Tags)`, `deprecated(Boolean)`, and `security(Requirements)` where `Requirements` is a list whose elements are requirement alternatives represented as lists of `Scheme-Scopes` pairs; the empty list element `[]` denotes an empty security requirement object, scheme names must be declared by `security_scheme/2`, and referenced OAuth flow scopes must be declared by the corresponding security scheme when locally available.

Compilation flags:
`static`
Template:
`operations(Operations)`
Mode and number of proofs:
`operations(-list(compound))` - `one`

### `schema/2`

Maps reusable schema names to JSON Schema terms. `Name` must be an atom and `Schema` must be a JSON Schema curly term compatible with the `json_schema` library. This predicate is intended both for lookup by name and for enumeration of all reusable schemas referenced from `schema_ref(Name)` terms.

Compilation flags:
`static`
Template:
`schema(Name,Schema)`
Mode and number of proofs:
`schema(?atom,?compound)` - `zero_or_more`

### `security_scheme/2`

Maps reusable security scheme names to security descriptor terms. `Name` must be an atom matching scheme names referenced from operation `security(Requirements)` properties and `Scheme` must use one of the supported descriptor shapes: `api_key/2-3`, `http/1-2`, `mutual_tls/0-1`, `oauth2/1-2`, or `openid_connect/1-2`. OAuth flow descriptors are expressed using `implicit/2-3`, `password/2-3`, `client_credentials/2-3`, and `authorization_code/3-4` with `scope/2` terms. `openid_connect/2` also accepts a provider-only `flows(Flows)` option for local scope declarations used during security-reference validation; those local flow declarations are not emitted into the derived OpenAPI document. Provider-side validation checks required fields, valid `apiKey` locations, and URL-valued fields in OAuth or OpenID Connect descriptors.

Compilation flags:
`static`
Template:
`security_scheme(Name,Scheme)`
Mode and number of proofs:
`security_scheme(?atom,?compound)` - `zero_or_more`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)