oas2mcp.models.normalized

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.

Examples

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

HTTP_METHODS

Classes

ApiCatalog	Top-level normalized API catalog.
ApiContact	Contact metadata for an API.
ApiInfo	Top-level API metadata.
ApiLicense	License metadata for an API.
ApiMediaType	Normalized media type description.
ApiOperation	One normalized HTTP operation.
ApiParameter	Normalized operation parameter.
ApiPathItem	Normalized path item grouping multiple operations.
ApiRequestBody	Normalized request body definition.
ApiResponse	Normalized response definition.
ApiSecurityRequirement	One normalized security requirement mapping.
ApiSecurityScheme	One named security scheme.
ApiServer	Resolved server definition.
ApiTag	Normalized tag metadata.
NormalizedBaseModel	Base model for normalized OpenAPI objects.

Module Contents

class oas2mcp.models.normalized.ApiCatalog(/, **data: Any)

Bases: NormalizedBaseModel

Top-level normalized API catalog.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

catalog = ApiCatalog(
    name="Petstore",
    source_uri="https://example.com/openapi.json",
)

component_counts: dict[str, int] = None

global_security: list[ApiSecurityRequirement] = None

info: ApiInfo | None = None

name: str

openapi_version: str | None = None

property operation_count: int

Return the number of normalized operations.

Parameters:

None.

Returns:

The number of operations in the catalog.

Raises:

None. –

Examples

catalog = ApiCatalog(
    name="Petstore",
    source_uri="https://example.com/openapi.json",
)
assert catalog.operation_count == 0

operations: list[ApiOperation] = None

paths: list[ApiPathItem] = None

raw_spec: dict[str, Any] = None

security_schemes: list[ApiSecurityScheme] = None

servers: list[ApiServer] = None

source_uri: str

property tag_names: list[str]

Return all tag names.

Parameters:

None.

Returns:

A list of tag names.

Raises:

None. –

Examples

catalog = ApiCatalog(
    name="Petstore",
    source_uri="https://example.com/openapi.json",
)
assert catalog.tag_names == []

tags: list[ApiTag] = None

class oas2mcp.models.normalized.ApiContact(/, **data: Any)

Bases: NormalizedBaseModel

Contact metadata for an API.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

contact = ApiContact(
    name="API Support",
    email="support@example.com",
    url="https://example.com/support",
)

email: str | None = None

name: str | None = None

url: str | None = None

class oas2mcp.models.normalized.ApiInfo(/, **data: Any)

Bases: NormalizedBaseModel

Top-level API metadata.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

info = ApiInfo(
    title="Petstore",
    version="1.0.0",
    summary="Pet operations",
)

contact: ApiContact | None = None

description: str | None = None

license: ApiLicense | None = None

summary: str | None = None

terms_of_service: str | None = None

title: str

version: str

class oas2mcp.models.normalized.ApiLicense(/, **data: Any)

Bases: NormalizedBaseModel

License metadata for an API.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

license_info = ApiLicense(name="MIT")

identifier: str | None = None

name: str

url: str | None = None

class oas2mcp.models.normalized.ApiMediaType(/, **data: Any)

Bases: NormalizedBaseModel

Normalized media type description.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

media = ApiMediaType(
    content_type="application/json",
    schema_type="object",
)

content_type: str

example: Any | None = None

examples: dict[str, Any] = None

raw_schema: dict[str, Any] = None

schema_ref: str | None = None

schema_type: str | None = None

class oas2mcp.models.normalized.ApiOperation(/, **data: Any)

Bases: NormalizedBaseModel

One normalized HTTP operation.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

operation = ApiOperation(
    method="get",
    path="/pets/{petId}",
    operation_id="getPetById",
)

classmethod normalize_method(value: str) → str

Normalize and validate an HTTP method.

Parameters:

value – The input HTTP method.

Returns:

The normalized uppercase HTTP method.

Raises:

ValueError – If the method is unsupported.

Examples

ApiOperation(
    method="get",
    path="/pets",
)

classmethod normalize_path(value: str) → str

Normalize a path string.

Parameters:

value – The raw path string.

Returns:

The normalized path starting with /.

Raises:

ValueError – If the path is empty.

Examples

ApiOperation(
    method="GET",
    path="pets/{petId}",
)

deprecated: bool = False

description: str | None = None

external_docs_description: str | None = None

external_docs_url: str | None = None

property is_mutating: bool

Return whether the operation mutates remote state.

Parameters:

None.

Returns:

True for mutating HTTP methods.

Raises:

None. –

Examples

operation = ApiOperation(method="POST", path="/pets")
assert operation.is_mutating is True

property key: str

Return a stable operation lookup key.

Parameters:

None.

Returns:

A METHOD path lookup key.

Raises:

None. –

Examples

operation = ApiOperation(method="GET", path="/pets")
assert operation.key == "GET /pets"

method: str

operation_id: str | None = None

parameters: list[ApiParameter] = None

path: str

raw_operation: dict[str, Any] = None

request_body: ApiRequestBody | None = None

responses: list[ApiResponse] = None

security: list[ApiSecurityRequirement] = None

summary: str | None = None

tags: list[str] = None

class oas2mcp.models.normalized.ApiParameter(/, **data: Any)

Bases: NormalizedBaseModel

Normalized operation parameter.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

parameter = ApiParameter(
    name="petId",
    location="path",
    required=True,
    schema_type="integer",
)

classmethod validate_location(value: str) → str

Validate a parameter location.

Parameters:

value – The parameter location.

Returns:

The validated location.

Raises:

ValueError – If the location is unsupported.

Examples

ApiParameter(
    name="petId",
    location="path",
)

default: Any | None = None

description: str | None = None

enum_values: list[Any] = None

location: str

name: str

raw_schema: dict[str, Any] = None

required: bool = False

schema_format: str | None = None

schema_type: str | None = None

class oas2mcp.models.normalized.ApiPathItem(/, **data: Any)

Bases: NormalizedBaseModel

Normalized path item grouping multiple operations.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

item = ApiPathItem(
    path="/pets",
    operations=[],
)

classmethod normalize_path(value: str) → str

Normalize a path item path.

Parameters:

value – The raw path string.

Returns:

The normalized path string.

Raises:

ValueError – If the path is empty.

Examples

ApiPathItem(path="/pets")

operations: list[ApiOperation] = None

parameters: list[ApiParameter] = None

path: str

class oas2mcp.models.normalized.ApiRequestBody(/, **data: Any)

Bases: NormalizedBaseModel

Normalized request body definition.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

body = ApiRequestBody(
    required=True,
    media_types=[ApiMediaType(content_type="application/json")],
)

description: str | None = None

media_types: list[ApiMediaType] = None

required: bool = False

class oas2mcp.models.normalized.ApiResponse(/, **data: Any)

Bases: NormalizedBaseModel

Normalized response definition.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

response = ApiResponse(
    status_code="200",
    description="Success",
)

description: str | None = None

headers: dict[str, Any] = None

media_types: list[ApiMediaType] = None

status_code: str

class oas2mcp.models.normalized.ApiSecurityRequirement(/, **data: Any)

Bases: NormalizedBaseModel

One normalized security requirement mapping.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

requirement = ApiSecurityRequirement(
    scheme_names=["bearerAuth"],
)

scheme_names: list[str] = None

class oas2mcp.models.normalized.ApiSecurityScheme(/, **data: Any)

Bases: 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.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

scheme = ApiSecurityScheme(
    name="apiKeyAuth",
    type="apiKey",
    location="header",
    parameter_name="X-API-Key",
)

bearer_format: str | None = None

description: str | None = None

flows: dict[str, Any] = None

location: str | None = None

name: str

open_id_connect_url: str | None = None

parameter_name: str | None = None

scheme: str | None = None

type: str

class oas2mcp.models.normalized.ApiServer(/, **data: Any)

Bases: NormalizedBaseModel

Resolved server definition.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

server = ApiServer(
    url="https://api.example.com",
    description="Production",
)

description: str | None = None

url: str

variables: dict[str, dict[str, Any]] = None

class oas2mcp.models.normalized.ApiTag(/, **data: Any)

Bases: NormalizedBaseModel

Normalized tag metadata.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

tag = ApiTag(
    name="pets",
    description="Operations about pets.",
)

description: str | None = None

external_docs_description: str | None = None

external_docs_url: str | None = None

name: str

class oas2mcp.models.normalized.NormalizedBaseModel(/, **data: Any)

Bases: pydantic.BaseModel

Base model for normalized OpenAPI objects.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

class ExampleModel(NormalizedBaseModel):
    name: str

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

oas2mcp.models.normalized.HTTP_METHODS: tuple[str, Ellipsis] = ('GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD', 'TRACE')