### 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](https://spec.openapis.org/registry/format/) with runtime validators, plus additional formats commonly found in real-world API specifications. See the [OAS 3.2 Format Registry](/reference/oas-3-2#oas-format-registry) section for the full registry breakdown. The following formats extend beyond what is defined in the OAS 3.0 base [Data Types](#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](https://spec.openapis.org/registry/format/) 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](/server/authentication#jwt-bearer) | | `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](/reference/oas-3-2#oauth-flows-object) 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](/server/authentication#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'`) | Generated server doesn't match this reference? Let us know — we'll fix it.