.. index:: single: open_api_provider_protocol
.. _open_api_provider_protocol/0:

.. rst-class:: right

**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)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: api_info/1
.. _open_api_provider_protocol/0::api_info/1:

``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``


------------

.. index:: servers/1
.. _open_api_provider_protocol/0::servers/1:

``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``


------------

.. index:: security/1
.. _open_api_provider_protocol/0::security/1:

``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``


------------

.. index:: operations/1
.. _open_api_provider_protocol/0::operations/1:

``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``


------------

.. index:: schema/2
.. _open_api_provider_protocol/0::schema/2:

``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``


------------

.. index:: security_scheme/2
.. _open_api_provider_protocol/0::security_scheme/2:

``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)

