OpenAPI 3.0

These pages document exactly which OpenAPI fields MCP Blacksmith processes during generation — field by field, with support status and behavior notes. Use them to check whether a specific feature in your spec will be reflected in the generated server. This page covers OpenAPI 3.0 (all patch versions 3.0.0–3.0.4). The OAS 3.1 and OAS 3.2 pages document only what changed relative to this baseline.

Swagger 2.0 specs are automatically converted to OAS 3.0 before generation.

Data Types

OAS 3.0 defines primitive data types based on JSON Schema with format modifiers.

Type / Format	Support	Behavior
`integer` / `int32`		Maps to `int` with runtime overflow validation
`integer` / `int64`		Maps to `int` with runtime overflow validation
`number` / `float`		Maps to `float`
`number` / `double`		Maps to `float`
`string`		Maps to `str`
`string` / `byte`		Maps to `str` with Base64 encoding validation
`string` / `binary`		Maps to `bytes` with binary validation
`boolean`		Maps to `bool`
`string` / `date`		Maps to `str` with RFC 3339 full-date validation
`string` / `date-time`		Maps to `str` with RFC 3339 date-time validation
`string` / `password`		Maps to `str`; no special validation (UI hint only per specification)

Extended Formats

MCP Blacksmith supports all 49 formats defined in the OAS Format Registry with runtime validators, plus additional formats commonly found in real-world API specifications. See the OAS 3.2 Format Registry section for the full registry breakdown.The following formats extend beyond what is defined in the OAS 3.0 base Data Types table above:

Format	Support	Behavior
`int8`		Signed 8-bit range validation (-128 to 127)
`int16`		Signed 16-bit range validation (-32,768 to 32,767)
`uint8`		Unsigned 8-bit range validation (0 to 255)
`uint16`		Unsigned 16-bit range validation (0 to 65,535)
`uint32`		Unsigned 32-bit range validation (protobuf/gRPC convention)
`uint64`		Unsigned 64-bit range validation (protobuf/gRPC convention)
`double-int`		Integer storable in IEEE 754 double without precision loss (±2^53-1)
`decimal`		Arbitrary-precision decimal validation
`decimal128`		IEEE 754 decimal128 validation (≤34 significant digits)
`time`		RFC 3339 time validation
`duration`		ISO 8601 duration validation
`date-time-local`		RFC 3339 date-time without timezone
`time-local`		RFC 3339 time without timezone
`http-date`		RFC 7231 HTTP-date (IMF-fixdate, RFC 850, asctime)
`unixtime`		Unix timestamp range validation
`email`		RFC 5322 email validation
`idn-email`		RFC 6531 internationalized email validation
`hostname`		RFC 1123 hostname validation
`idn-hostname`		RFC 5890 internationalized hostname validation
`ipv4`		Dotted-decimal IPv4 validation
`ipv6`		IPv6 address validation
`uri`		RFC 3986 URI validation
`uri-reference`		RFC 3986 URI-reference validation
`uri-template`		RFC 6570 URI template validation
`iri`		RFC 3987 IRI validation
`iri-reference`		RFC 3987 IRI-reference validation
`uuid`		UUID format validation
`json-pointer`		RFC 6901 JSON Pointer validation
`relative-json-pointer`		Relative JSON Pointer validation
`regex`		Regular expression validation
`commonmark`		CommonMark-formatted text (string type check)
`html`		HTML-formatted text (string type check)
`char`		Single character validation
`media-range`		RFC 9110 media-range validation (e.g., `text/html`, `/`)
`base64url`		URL-safe Base64 validation (alias for `byte`)
`sf-integer`		RFC 8941 Structured Fields integer (±15 digits)
`sf-decimal`		RFC 8941 Structured Fields decimal (12+3 digits)
`sf-string`		RFC 8941 Structured Fields string (printable ASCII)
`sf-token`		RFC 8941 Structured Fields token
`sf-boolean`		RFC 8941 Structured Fields boolean (`?0` / `?1`)
`sf-binary`		RFC 8941 Structured Fields binary (`:base64:`)

Custom Formats (not in OAS registry)

These additional formats are not part of the OAS Format Registry but are commonly found in real-world API specifications:

Format	Support	Behavior
`unix-time`		Unix timestamp range validation (alias: `unixtime` is the registry name)
`date-time-rfc-2822`		RFC 2822 date-time validation
`date-time-rfc1123`		RFC 1123 date-time validation
`phone-number`		E.164 phone number validation
`timestamp`		Alias for `unix-time`
`url`		Alias for `uri`

Unknown format strings are kept as metadata on the generated field (visible to AI agents) but have no runtime validation.

OpenAPI Object (Root)

Field	Support	Behavior
`openapi`		Selects version-specific validation and processing rules (3.0, 3.1, and 3.2 each have dedicated handling)
`info`		Title becomes the server name; description and version appear in the server docstring and `.env`
`servers`		Three-level cascade: root → `BASE_URL`, path-item/operation → per-tool URL overrides in `.env`
`paths`		Each operation becomes an MCP tool with typed parameters, authentication, and response models
`components`		Schemas become Pydantic models; parameters, request bodies, and responses are resolved via `$ref` into tool definitions
`security`		Generates authentication classes applied to all tools unless overridden per-operation

Info Object

Field	Support	Behavior
`title`		Used as fallback server name when no override provided
`description`		Used as generated server description
`termsOfService`		Rendered in generated server docstring and README
`contact`		Contact name, email, URL rendered in server docstring and README
`license`		License name and URL rendered in server docstring and README
`version`		Appears in the generated server docstring

Server Object

All three server levels are supported (operation > pathItem > root). The first entry at each level is used; you can override any resolved URL via SERVER_URL_* environment variables.

Field	Support	Behavior
`url`		Resolved with variable default substitution; trailing slashes stripped. At root level, becomes `BASE_URL`. At path-item/operation level, stored as per-tool override when it differs from root
`variables`		Defaults substituted into URL at all three levels. Root-level variables become `SERVER_*` entries in `.env` — editable by the user to switch environments without code changes

Server Variable Object

Field	Support	Behavior
`enum`		Documented as allowed values in `.env` comments (root-level variables)
`default`		Substituted into server URL; used as env var default value (root-level variables)
`description`		Rendered as `.env` comment (root-level variables)

Only servers[0] is used at each level. Multiple server entries (e.g., production vs sandbox) are accepted but alternates beyond the first are not exposed. Users can override any resolved URL via the corresponding SERVER_URL_* or BASE_URL environment variable.

Paths Object

Feature	Support	Behavior
`/{path}` entries		All path entries processed for MCP tool generation
Path templating		Template variables (e.g., `/users/{id}`) become path parameters on generated tools

Path Item Object

Field	Support	Behavior
`$ref`		Shared path items resolved — multiple paths can reference the same definition
`get`		Generates an MCP tool
`put`		Generates an MCP tool
`post`		Generates an MCP tool
`delete`		Generates an MCP tool
`options`		Generates an MCP tool
`head`		Generates an MCP tool
`patch`		Generates an MCP tool
`trace`		Generates an MCP tool
`servers`		Per-path server override applied to all operations under this path item
`parameters`		Inherited by all operations; overridden by operation-level parameters with same name+location

Operation Object

Field	Support	Behavior
`summary`		Preferred as the tool description shown to AI agents
`description`		Used as the tool description when `summary` is absent
`operationId`		Primary tool name identifier; auto-synthesized from method + path when missing
`parameters`		Each parameter becomes a typed argument on the generated tool function
`requestBody`		Body schema properties are flattened into tool function arguments
`responses`		Success response schema generates a Pydantic model used as the tool’s return type
`tags`		Rendered as comments in generated server code and used for operation grouping
`deprecated`		Deprecated operations optionally filtered out during generation
`security`		Per-operation authentication requirements override global security
`servers`		Per-operation server override; takes priority over path-item and root servers
`callbacks`		Not supported. Planned for a future release

Parameter Object

Core Fields

Field	Support	Behavior
`name`		Used as parameter identifier; collision-safe renaming applied when names conflict across locations
`in`		All four locations supported: `path`, `query`, `header`, `cookie`
`description`		Becomes `Field(description=...)` on the generated parameter, visible to AI agents
`required`		Controls whether parameter has a default value; always `true` for path params
`deprecated`		Deprecated parameters optionally filtered out during generation
`allowEmptyValue`		Not processed (flagged NOT RECOMMENDED since OAS 3.0.2)

Serialization Fields

Field	Support	Behavior
`style`		Read for query and path parameters; non-default styles generate serialization transforms
`explode`		Read for query and path parameters; non-default values generate serialization transforms
`schema`		Determines the Python type annotation for the generated tool parameter
`example`		Emitted in generated `Field(examples=[...])`
`examples`		Named Example Objects read and emitted in `Field(examples=[...])`. When both `example` and `examples` present, `examples` takes priority
`content`		Supported for all locations. Content-encoded values are JSON-serialized for `application/json` and `*+json` media types. Non-JSON encodings pass through as-is
`allowReserved`		Not supported — `httpx` always percent-encodes query parameters; most servers decode transparently

Serialization Style Values

Style	Support	Behavior
`matrix`		Path params: `;name=value` serialization for primitives, arrays, and objects with explode control
`label`		Path params: `.value` serialization for primitives, arrays, and objects with explode control
`form`		Default for query/cookie; `explode: false` generates comma-joined serialization
`simple`		Default for path/header; primitives pass through, arrays/objects comma-joined
`spaceDelimited`		Query params: space-joined serialization for arrays
`pipeDelimited`		Query params: pipe-joined serialization for arrays
`deepObject`		Query params: `key[subkey]=value` serialization for objects

Request Body Object

Field	Support	Behavior
`description`		Used as docstring on generated body model classes
`content`		Content type selected by priority: `application/json` → `application/x-www-form-urlencoded` → `multipart/form-data` → `application/xml` → `/` → first available. Each tool uses the correct HTTP encoding for its content type
`required`		When `false`, all body parameters become optional. When `true`, optionality follows the schema’s `required` array

Media Type Object

Field	Support	Behavior
`schema`		Generates the Pydantic model for this request or response body
`example`		For flat body schemas, emitted in `Field(examples=[...])`. For multi-property schemas, property-level examples are used instead
`examples`		Same as `example`. Named Example Objects normalized to list format. `externalValue` not fetched
`encoding`		Not processed. Per-property serialization for form and multipart bodies

Media type range matching (e.g., application/* per RFC 7231) is not implemented. Content type keys are matched literally.

Encoding Object

Field	Support	Behavior
`contentType`		Per-field media type override for multipart parts
`headers`		Additional headers per multipart part
`style`		Serialization style for form-encoded fields
`explode`		Explode flag for form-encoded fields
`allowReserved`		Reserved character encoding control

The Encoding Object is not supported. Generated servers send form and multipart bodies using standard encoding — per-property overrides (contentType, headers, style) are rarely needed in practice.

Responses

Feature	Support	Behavior
Status codes		Each status code’s schema generates a Pydantic response model
`default`		Supported but not semantically distinguished as fallback
`1XX`, `2XX`, etc.		Range codes accepted but no semantic range interpretation

Response Object

Field	Support	Behavior
`description`		Becomes the docstring on the generated Pydantic response model
`content`		Schema from the matched media type generates the response model fields
`headers`		Not applicable — MCP tools return structured data, not raw HTTP responses
`links`		Not applicable — operation chaining is handled by the AI agent at runtime

Schema Object

JSON Schema Keywords

Field	Support	Behavior
`title`		Used as context during model class naming. Final class names are derived from the schema’s location path
`multipleOf`		Generates `Field(multiple_of=...)`
`maximum`		Generates `Field(le=...)`
`exclusiveMaximum`		When `true`, combined with `maximum` to produce `Field(lt=...)`
`minimum`		Generates `Field(ge=...)`
`exclusiveMinimum`		When `true`, combined with `minimum` to produce `Field(gt=...)`
`maxLength`		Generates `Field(max_length=...)`
`minLength`		Generates `Field(min_length=...)`
`pattern`		Generates `Field(pattern=...)`; incompatible regex patterns are not processed
`maxItems`		Generates `Field(max_length=...)` on list fields
`minItems`		Generates `Field(min_length=...)` on list fields
`uniqueItems`		Runtime uniqueness validation; handles unhashable items via equality comparison
`maxProperties`		Generates `Field(max_length=...)` on dict fields
`minProperties`		Generates `Field(min_length=...)` on dict fields
`required`		Controls field optionality in generated models
`enum`		Generates `Literal["a", "b", ...]` type annotation
`type`		Maps to the corresponding Python type. When omitted, inferred from `properties` or composition keywords
`allOf`		All variant properties merged into a single Pydantic model
`anyOf`		Generates `Union[A, B, ...]` type annotation
`items`		Generates `list[ItemType]` annotation
`properties`		Each property becomes a typed field on the generated Pydantic model
`additionalProperties`		Boolean or schema. `true` → permissive model, `false` → strict model, schema → `dict[str, ValueType]`
`description`		Generates `Field(description=...)`
`format`		All 49 OAS Format Registry formats plus custom extensions generate runtime validators; unknown formats kept as metadata for AI visibility
`default`		Generates `Field(default=...)` with type-aware coercion
`oneOf`		Generates `Union[A, B, ...]`. Exclusivity not enforced without explicit `discriminator`
`not`		Only `not: {required: [...]}` mutual exclusivity pattern handled

OAS Extension Keywords

Field	Support	Behavior
`nullable`		Produces `T \| None` type annotation. Parameters accept `None` values but explicit `null` cannot be sent to the upstream API
`discriminator`		Generates `Field(discriminator="field")` when viable; validates all variants
`readOnly`		Read-only parameters optionally filtered out during generation
`writeOnly`		Write-only parameters kept (request-only fields)
`example`		Converted to `Field(examples=[...])` format
`deprecated`		Deprecated parameters and operations optionally filtered out during generation

Nullable type annotations (T | None) are generated correctly, but explicit null values cannot be sent to the upstream API. The MCP protocol implementation does not distinguish between an omitted parameter and one explicitly set to null — both arrive as None in the tool function. This is an MCP ecosystem limitation, not a generation issue.

Discriminator Object

Field	Support	Behavior
`propertyName`		Validated against all variants; generates `Field(discriminator=...)`
`mapping`		Not processed. Union variants are built from the `oneOf`/`anyOf` array directly

Components Object

Field	Support	Behavior
`schemas`		Each schema becomes a Pydantic model class, used as request/response types across tools
`responses`		Shared response definitions resolved into Pydantic models wherever referenced
`parameters`		Shared parameter definitions resolved into typed tool arguments wherever referenced
`requestBodies`		Shared body definitions resolved into tool arguments wherever referenced
`securitySchemes`		Each referenced scheme generates a dedicated authentication class with `.env` configuration
`headers`		Not applicable — request headers are handled via `in: header` parameters instead
`links`		Not applicable — operation chaining is handled by the AI agent
`callbacks`		Not supported. Planned for a future release

Reference Object

Feature	Support	Behavior
Local `$ref`		Full JSON Pointer resolution (`#/...`) within the specification
External `$ref`		External file/URL references not resolved. Planned for multi-file bundle support

In OAS 3.0, sibling properties alongside $ref should be ignored. MCP Blacksmith implements OAS 3.1 superset behavior — select siblings (description, summary, default, deprecated, readOnly, writeOnly) are honored alongside $ref.

Security Scheme Object

Field	Support	Behavior
`type`		All four types: `apiKey`, `http`, `oauth2`, `openIdConnect`
`name`		API key parameter name used in the generated authentication class
`in`		All three locations: `query`, `header`, `cookie`
`scheme`		`basic` → BasicAuth; `bearer` → BearerTokenAuth; other schemes → generic bearer fallback
`bearerFormat`		When `"JWT"`, generates a JWT Bearer auth class that signs tokens with a private key (RS256). See JWT Bearer authentication
`flows`		All four OAuth2 flows supported
`openIdConnectUrl`		Used in generated OpenID Connect authentication configuration

OAuth Flows Object

Field	Support	Behavior
`implicit`		Supported (lowest priority among flows)
`password`		Supported (third priority)
`clientCredentials`		Supported (second priority)
`authorizationCode`		Supported (highest priority; preferred when available)

OAS 3.2 adds a fifth flow, deviceAuthorization, which slots between clientCredentials and password in the priority order.

When a specification defines multiple OAuth2 flows on the same security scheme, the generator selects one flow based on security priority: authorizationCode > clientCredentials > deviceAuthorization > password > implicit. This ensures the server always uses the most secure available grant type. See Flow Selection for details.

OAuth Flow Object

Field	Support	Behavior
`authorizationUrl`		Used in the generated OAuth2 auth class for the authorization redirect
`tokenUrl`		Used in the generated OAuth2 auth class for token exchange
`refreshUrl`		Used in the generated OAuth2 auth class for automatic token refresh
`scopes`		Per-operation scopes are passed to the auth class during token requests

Security Requirement Object

Feature	Support	Behavior
OR logic		Each array entry is an OR alternative, sorted by security: `mutualTLS > oauth2 > openIdConnect > http > apiKey`
AND logic		Multiple schemes within a single entry treated as AND
Empty (`[]`)		Recognized as “no auth required”
Global		Default `security` applied to all operations
Per-operation		Operation-level `security` overrides global

Example Object

Field	Support	Behavior
`value`		Inline and `$ref` both supported; emitted in `Field(examples=[...])`
`externalValue`		External example URLs not fetched

Specification Extensions

Feature	Support	Behavior
`x-*` extension fields		Ignored during generation. Their presence does not cause errors

Additional Generator Capabilities

Features that go beyond per-field processing of the OAS 3.0 specification:

Feature	Support	Behavior
Circular `$ref` handling		Self-references, mutual references, and deep chains all detected and handled with forward references
Inline schema discovery		Unnamed schemas within request/response bodies automatically become generated classes
Name collision resolution		Same-name parameters across locations and duplicate `operationId` values across operations get collision-safe renaming
Multiple OAuth2 merging		Identical-scope schemes merged into a single auth class
Content type negotiation		Multiple media types with different schemas generate separate tools. Identical schemas use highest-priority type
Strict/Permissive models		Models with `additionalProperties: false` or `unevaluatedProperties: false` use strict mode (`extra='forbid'`); all others use permissive (`extra='allow'`)

Found an issue?

Generated server doesn’t match this reference? Let us know — we’ll fix it.

Getting Started

Generator

Your Generated Server

Deployment

Reference

Data Types

Extended Formats

Custom Formats (not in OAS registry)

OpenAPI Object (Root)

Info Object

Server Object

Server Variable Object

Paths Object

Path Item Object

Operation Object

Parameter Object

Core Fields

Serialization Fields

Serialization Style Values

Request Body Object

Media Type Object

Encoding Object

Responses

Response Object

Schema Object

JSON Schema Keywords

OAS Extension Keywords

Discriminator Object

Components Object

Reference Object

Security Scheme Object

OAuth Flows Object

OAuth Flow Object

Security Requirement Object

Example Object

Specification Extensions

Additional Generator Capabilities

Found an issue?

​Data Types

​Extended Formats

​Custom Formats (not in OAS registry)

​OpenAPI Object (Root)

​Info Object

​Server Object

​Server Variable Object

​Paths Object

​Path Item Object

​Operation Object

​Parameter Object

​Core Fields

​Serialization Fields

​Serialization Style Values

​Request Body Object

​Media Type Object

​Encoding Object

​Responses

​Response Object

​Schema Object

​JSON Schema Keywords

​OAS Extension Keywords

​Discriminator Object

​Components Object

​Reference Object

​Security Scheme Object

​OAuth Flows Object

​OAuth Flow Object

​Security Requirement Object

​Example Object

​Specification Extensions

​Additional Generator Capabilities

Found an issue?

Data Types

Extended Formats

Custom Formats (not in OAS registry)

OpenAPI Object (Root)

Info Object

Server Object

Server Variable Object

Paths Object

Path Item Object

Operation Object

Parameter Object

Core Fields

Serialization Fields

Serialization Style Values

Request Body Object

Media Type Object

Encoding Object

Responses

Response Object

Schema Object

JSON Schema Keywords

OAS Extension Keywords

Discriminator Object

Components Object

Reference Object

Security Scheme Object

OAuth Flows Object

OAuth Flow Object

Security Requirement Object

Example Object

Specification Extensions

Additional Generator Capabilities