Compliance reference for OpenAPI Specification 3.0.0–3.0.4.
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.
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)
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
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.
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
Content type selected by priority: application/json → application/xml → multipart/form-data → */* → 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
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.
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.
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.
