oas2mcp.models.normalized ========================= .. py:module:: oas2mcp.models.normalized .. autoapi-nested-parse:: Normalized OpenAPI models. Purpose: Define stable, typed Pydantic models for the normalized internal view of an OpenAPI specification. Design: - Flatten OpenAPI structures into reusable, agent-friendly models. - Preserve enough metadata for Rich rendering, inspection, and later MCP generation. - Use clean internal field names instead of OpenAPI alias names where the alias would be awkward or invalid in Python, such as ``in``. - Keep raw fragments available for debugging and future enrichment. .. rubric:: Examples .. code-block:: python from oas2mcp.models.normalized import ApiCatalog, ApiOperation operation = ApiOperation( method="get", path="/pets/{petId}", operation_id="getPetById", summary="Fetch one pet", ) catalog = ApiCatalog( name="Petstore", source_uri="https://petstore3.swagger.io/api/v3/openapi.json", operations=[operation], ) Attributes ---------- .. autoapisummary:: oas2mcp.models.normalized.HTTP_METHODS Classes ------- .. autoapisummary:: oas2mcp.models.normalized.ApiCatalog oas2mcp.models.normalized.ApiContact oas2mcp.models.normalized.ApiInfo oas2mcp.models.normalized.ApiLicense oas2mcp.models.normalized.ApiMediaType oas2mcp.models.normalized.ApiOperation oas2mcp.models.normalized.ApiParameter oas2mcp.models.normalized.ApiPathItem oas2mcp.models.normalized.ApiRequestBody oas2mcp.models.normalized.ApiResponse oas2mcp.models.normalized.ApiSecurityRequirement oas2mcp.models.normalized.ApiSecurityScheme oas2mcp.models.normalized.ApiServer oas2mcp.models.normalized.ApiTag oas2mcp.models.normalized.NormalizedBaseModel Module Contents --------------- .. py:class:: ApiCatalog(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` Top-level normalized API catalog. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python catalog = ApiCatalog( name="Petstore", source_uri="https://example.com/openapi.json", ) .. py:attribute:: component_counts :type: dict[str, int] :value: None .. py:attribute:: global_security :type: list[ApiSecurityRequirement] :value: None .. py:attribute:: info :type: ApiInfo | None :value: None .. py:attribute:: name :type: str .. py:attribute:: openapi_version :type: str | None :value: None .. py:property:: operation_count :type: int Return the number of normalized operations. :param None.: :returns: The number of operations in the catalog. :raises None.: .. rubric:: Examples .. code-block:: python catalog = ApiCatalog( name="Petstore", source_uri="https://example.com/openapi.json", ) assert catalog.operation_count == 0 .. py:attribute:: operations :type: list[ApiOperation] :value: None .. py:attribute:: paths :type: list[ApiPathItem] :value: None .. py:attribute:: raw_spec :type: dict[str, Any] :value: None .. py:attribute:: security_schemes :type: list[ApiSecurityScheme] :value: None .. py:attribute:: servers :type: list[ApiServer] :value: None .. py:attribute:: source_uri :type: str .. py:property:: tag_names :type: list[str] Return all tag names. :param None.: :returns: A list of tag names. :raises None.: .. rubric:: Examples .. code-block:: python catalog = ApiCatalog( name="Petstore", source_uri="https://example.com/openapi.json", ) assert catalog.tag_names == [] .. py:attribute:: tags :type: list[ApiTag] :value: None .. py:class:: ApiContact(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` Contact metadata for an API. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python contact = ApiContact( name="API Support", email="support@example.com", url="https://example.com/support", ) .. py:attribute:: email :type: str | None :value: None .. py:attribute:: name :type: str | None :value: None .. py:attribute:: url :type: str | None :value: None .. py:class:: ApiInfo(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` Top-level API metadata. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python info = ApiInfo( title="Petstore", version="1.0.0", summary="Pet operations", ) .. py:attribute:: contact :type: ApiContact | None :value: None .. py:attribute:: description :type: str | None :value: None .. py:attribute:: license :type: ApiLicense | None :value: None .. py:attribute:: summary :type: str | None :value: None .. py:attribute:: terms_of_service :type: str | None :value: None .. py:attribute:: title :type: str .. py:attribute:: version :type: str .. py:class:: ApiLicense(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` License metadata for an API. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python license_info = ApiLicense(name="MIT") .. py:attribute:: identifier :type: str | None :value: None .. py:attribute:: name :type: str .. py:attribute:: url :type: str | None :value: None .. py:class:: ApiMediaType(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` Normalized media type description. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python media = ApiMediaType( content_type="application/json", schema_type="object", ) .. py:attribute:: content_type :type: str .. py:attribute:: example :type: Any | None :value: None .. py:attribute:: examples :type: dict[str, Any] :value: None .. py:attribute:: raw_schema :type: dict[str, Any] :value: None .. py:attribute:: schema_ref :type: str | None :value: None .. py:attribute:: schema_type :type: str | None :value: None .. py:class:: ApiOperation(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` One normalized HTTP operation. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python operation = ApiOperation( method="get", path="/pets/{petId}", operation_id="getPetById", ) .. py:method:: normalize_method(value: str) -> str :classmethod: Normalize and validate an HTTP method. :param value: The input HTTP method. :returns: The normalized uppercase HTTP method. :raises ValueError: If the method is unsupported. .. rubric:: Examples .. code-block:: python ApiOperation( method="get", path="/pets", ) .. py:method:: normalize_path(value: str) -> str :classmethod: Normalize a path string. :param value: The raw path string. :returns: The normalized path starting with ``/``. :raises ValueError: If the path is empty. .. rubric:: Examples .. code-block:: python ApiOperation( method="GET", path="pets/{petId}", ) .. py:attribute:: deprecated :type: bool :value: False .. py:attribute:: description :type: str | None :value: None .. py:attribute:: external_docs_description :type: str | None :value: None .. py:attribute:: external_docs_url :type: str | None :value: None .. py:property:: is_mutating :type: bool Return whether the operation mutates remote state. :param None.: :returns: ``True`` for mutating HTTP methods. :raises None.: .. rubric:: Examples .. code-block:: python operation = ApiOperation(method="POST", path="/pets") assert operation.is_mutating is True .. py:property:: key :type: str Return a stable operation lookup key. :param None.: :returns: A ``METHOD path`` lookup key. :raises None.: .. rubric:: Examples .. code-block:: python operation = ApiOperation(method="GET", path="/pets") assert operation.key == "GET /pets" .. py:attribute:: method :type: str .. py:attribute:: operation_id :type: str | None :value: None .. py:attribute:: parameters :type: list[ApiParameter] :value: None .. py:attribute:: path :type: str .. py:attribute:: raw_operation :type: dict[str, Any] :value: None .. py:attribute:: request_body :type: ApiRequestBody | None :value: None .. py:attribute:: responses :type: list[ApiResponse] :value: None .. py:attribute:: security :type: list[ApiSecurityRequirement] :value: None .. py:attribute:: summary :type: str | None :value: None .. py:attribute:: tags :type: list[str] :value: None .. py:class:: ApiParameter(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` Normalized operation parameter. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python parameter = ApiParameter( name="petId", location="path", required=True, schema_type="integer", ) .. py:method:: validate_location(value: str) -> str :classmethod: Validate a parameter location. :param value: The parameter location. :returns: The validated location. :raises ValueError: If the location is unsupported. .. rubric:: Examples .. code-block:: python ApiParameter( name="petId", location="path", ) .. py:attribute:: default :type: Any | None :value: None .. py:attribute:: description :type: str | None :value: None .. py:attribute:: enum_values :type: list[Any] :value: None .. py:attribute:: location :type: str .. py:attribute:: name :type: str .. py:attribute:: raw_schema :type: dict[str, Any] :value: None .. py:attribute:: required :type: bool :value: False .. py:attribute:: schema_format :type: str | None :value: None .. py:attribute:: schema_type :type: str | None :value: None .. py:class:: ApiPathItem(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` Normalized path item grouping multiple operations. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python item = ApiPathItem( path="/pets", operations=[], ) .. py:method:: normalize_path(value: str) -> str :classmethod: Normalize a path item path. :param value: The raw path string. :returns: The normalized path string. :raises ValueError: If the path is empty. .. rubric:: Examples .. code-block:: python ApiPathItem(path="/pets") .. py:attribute:: operations :type: list[ApiOperation] :value: None .. py:attribute:: parameters :type: list[ApiParameter] :value: None .. py:attribute:: path :type: str .. py:class:: ApiRequestBody(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` Normalized request body definition. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python body = ApiRequestBody( required=True, media_types=[ApiMediaType(content_type="application/json")], ) .. py:attribute:: description :type: str | None :value: None .. py:attribute:: media_types :type: list[ApiMediaType] :value: None .. py:attribute:: required :type: bool :value: False .. py:class:: ApiResponse(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` Normalized response definition. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python response = ApiResponse( status_code="200", description="Success", ) .. py:attribute:: description :type: str | None :value: None .. py:attribute:: headers :type: dict[str, Any] :value: None .. py:attribute:: media_types :type: list[ApiMediaType] :value: None .. py:attribute:: status_code :type: str .. py:class:: ApiSecurityRequirement(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` One normalized security requirement mapping. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python requirement = ApiSecurityRequirement( scheme_names=["bearerAuth"], ) .. py:attribute:: scheme_names :type: list[str] :value: None .. py:class:: ApiSecurityScheme(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` One named security scheme. Design: ``name`` is the scheme identifier from ``components.securitySchemes``. ``parameter_name`` is the header/query/cookie parameter name used by some schemes such as API key auth. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python scheme = ApiSecurityScheme( name="apiKeyAuth", type="apiKey", location="header", parameter_name="X-API-Key", ) .. py:attribute:: bearer_format :type: str | None :value: None .. py:attribute:: description :type: str | None :value: None .. py:attribute:: flows :type: dict[str, Any] :value: None .. py:attribute:: location :type: str | None :value: None .. py:attribute:: name :type: str .. py:attribute:: open_id_connect_url :type: str | None :value: None .. py:attribute:: parameter_name :type: str | None :value: None .. py:attribute:: scheme :type: str | None :value: None .. py:attribute:: type :type: str .. py:class:: ApiServer(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` Resolved server definition. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python server = ApiServer( url="https://api.example.com", description="Production", ) .. py:attribute:: description :type: str | None :value: None .. py:attribute:: url :type: str .. py:attribute:: variables :type: dict[str, dict[str, Any]] :value: None .. py:class:: ApiTag(/, **data: Any) Bases: :py:obj:`NormalizedBaseModel` Normalized tag metadata. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python tag = ApiTag( name="pets", description="Operations about pets.", ) .. py:attribute:: description :type: str | None :value: None .. py:attribute:: external_docs_description :type: str | None :value: None .. py:attribute:: external_docs_url :type: str | None :value: None .. py:attribute:: name :type: str .. py:class:: NormalizedBaseModel(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` Base model for normalized OpenAPI objects. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python class ExampleModel(NormalizedBaseModel): name: str .. py:attribute:: model_config Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. .. py:data:: HTTP_METHODS :type: tuple[str, Ellipsis] :value: ('GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD', 'TRACE')