oas2mcp.utils.refs
==================

.. py:module:: oas2mcp.utils.refs

.. autoapi-nested-parse::

   Reference and JSON pointer helpers.

   Purpose:
       Resolve JSON pointers and schema references against normalized OpenAPI raw
       spec data.

   Design:
       - Support local ``#/...`` references first.
       - Keep helpers read-only and deterministic.
       - Return ``None`` instead of raising for missing refs in normal lookup
         flows.
       - Provide separate request and response schema ref collection so viewers
         and agent-context builders can distinguish input from output structure.

   .. rubric:: Examples

   .. code-block:: python

       schema = dereference_schema_ref(catalog.raw_spec, "#/components/schemas/Pet")



Functions
---------

.. autoapisummary::

   oas2mcp.utils.refs.collect_operation_schema_refs
   oas2mcp.utils.refs.collect_request_schema_refs
   oas2mcp.utils.refs.collect_response_schema_refs
   oas2mcp.utils.refs.dereference_schema_ref
   oas2mcp.utils.refs.resolve_json_pointer


Module Contents
---------------

.. py:function:: collect_operation_schema_refs(operation: oas2mcp.models.normalized.ApiOperation) -> list[str]

   Collect all schema refs mentioned by an operation.

   :param operation: The normalized API operation.

   :returns: A de-duplicated list of request and response schema refs.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       refs = collect_operation_schema_refs(operation)


.. py:function:: collect_request_schema_refs(operation: oas2mcp.models.normalized.ApiOperation) -> list[str]

   Collect request-body schema refs mentioned by an operation.

   :param operation: The normalized API operation.

   :returns: A de-duplicated list of request schema refs.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       refs = collect_request_schema_refs(operation)


.. py:function:: collect_response_schema_refs(operation: oas2mcp.models.normalized.ApiOperation) -> list[str]

   Collect response schema refs mentioned by an operation.

   :param operation: The normalized API operation.

   :returns: A de-duplicated list of response schema refs.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       refs = collect_response_schema_refs(operation)


.. py:function:: dereference_schema_ref(document: dict[str, Any], schema_ref: str) -> dict[str, Any] | None

   Dereference a local schema reference.

   :param document: The raw OpenAPI specification dictionary.
   :param schema_ref: A local schema reference.

   :returns: The resolved schema mapping when found, otherwise ``None``.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       schema = dereference_schema_ref(
           {"components": {"schemas": {"Pet": {"type": "object"}}}},
           "#/components/schemas/Pet",
       )


.. py:function:: resolve_json_pointer(document: dict[str, Any], pointer: str) -> Any | None

   Resolve a local JSON pointer within a document.

   :param document: The target document.
   :param pointer: The JSON pointer, such as ``#/components/schemas/Pet``.

   :returns: The resolved value when found, otherwise ``None``.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       value = resolve_json_pointer(
           {"components": {"schemas": {"Pet": {"type": "object"}}}},
           "#/components/schemas/Pet",
       )