--- title: "Spec compatibility" description: "What typeship accepts: Swagger 2.0, OpenAPI 3.0 and 3.1, and GraphQL, and how each construct maps to the generated packages." url: https://typeship.dev/docs/reference/spec-compatibility markdown: https://typeship.dev/docs/reference/spec-compatibility.md section: "Get started" --- > ## Documentation index > Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt. > Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page. # Spec compatibility What typeship accepts: Swagger 2.0, OpenAPI 3.0 and 3.1, and GraphQL, and how each construct maps to the generated packages. typeship accepts Swagger 2.0, OpenAPI 3.0.x, and OpenAPI 3.1.x as JSON or YAML, up to 10MB, plus GraphQL schemas as SDL, introspection JSON, or an introspectable endpoint URL. The rule throughout: generation fails only for a document that is not a spec at all. Everything else generates, and anything skipped or approximated is reported as a warning on the result. ## Swagger 2.0 2.0 documents are normalized to OpenAPI 3.0 before generation. The converter covers the constructs that appear in real specs: * `host`, `basePath`, and `schemes` become the server URL. https is preferred when listed. * `definitions` become `components.schemas`. `$ref` pointers are rewritten to their 3.0 locations. * `body` parameters become request bodies. `formData` parameters become a form-encoded body, or multipart when there are file uploads. * `consumes` and `produces` become content types on request and response bodies. * `securityDefinitions` become security schemes. Basic, apiKey, and oauth2 are mapped. Unsupported types are skipped with a warning. Known limitation: shared parameters in the top-level `parameters` section that are `body` or `formData` parameters cannot be converted in place and are skipped with a warning. Inline them in each operation for full fidelity. ## References Only local references (`#/components/...`) are resolved. External references to other files or URLs are not fetched. The referenced schema becomes `unknown` and a warning is reported. Dangling local references are treated the same way. Bundle multi-file specs into one document before generating. ## GET and HEAD request bodies Request bodies declared on GET or HEAD operations are dropped, with a warning listing the affected operations. Intermediaries do not reliably transmit GET bodies, so the SDK refuses to expose them. ## Server URLs * The first entry in `servers` becomes the client's default base URL. Server variables are substituted with their declared defaults. * Two or more servers export named environments, taken from each server's description. * A relative server URL (`/v1`) or a variable without a default cannot produce a usable base URL. The client is still generated, but the base URL becomes a required constructor option and a warning says so. ## Authentication | Scheme in the spec | Client option | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | HTTP bearer | `bearerToken` | | HTTP basic | `basicAuth` | | API key in a header or query | `apiKey`, or one option per key when there are several | | OAuth2 and OpenID Connect | `bearerToken` for a token you obtained elsewhere, plus `clientCredentials` for the client credentials grant against the spec's token URL | | Cookie parameters | Dropped | | Anything else | Warning, no option | When OAuth2 is declared, the generated CLI also gains a device-flow `login` once a client id is configured. See [login, logout, whoami](https://typeship.dev/docs/platforms/cli#login-logout-whoami). ## Webhooks The `webhooks` section (3.1) and the `x-webhooks` convention (3.0) generate typed events and a verifying parser. Each webhook needs a JSON request body schema. See [Webhooks](https://typeship.dev/docs/guides/webhooks). ## Bodies and responses | Content type | Generated as | | ----------------------------------- | ---------------------------------------------------- | | `application/json` | Typed body, JSON encoded | | `application/x-www-form-urlencoded` | Typed body, deep bracket encoded | | `multipart/form-data` | SDK-only. Not in the CLI, MCP server, Python, or Go. | | Binary bodies | SDK-only. Same exclusions. | | `text/event-stream` responses | A stream. SDK-only. | | Other `text/*` responses | A string | | Other responses | Raw bytes | ## Pagination Four styles are detected from parameter and response names. When detection guesses wrong, pin the rule per operation. See [Pagination](https://typeship.dev/docs/platforms/sdk#pagination) and [Pagination rules](https://typeship.dev/docs/projects/config#pagination-rules). ## GraphQL GraphQL schemas generate the same TypeScript package as OpenAPI specs, on the same runtime. Queries become methods on `client.query`, mutations on `client.mutation`. Object types carry an optional `__typename` literal. Unions, and interfaces with implementers, become a union of their concrete types, discriminated by `__typename`. Subscriptions are skipped with a warning. Custom scalars map to `unknown`. Operation documents are not an input. The endpoint and auth scheme, which a schema cannot declare, come from [config](https://typeship.dev/docs/projects/config#graphql-schemas) and default to the URL the schema was fetched from and a bearer token. See [Generate from GraphQL](https://typeship.dev/docs/guides/graphql). ## When generation fails Hard failures are reserved for documents that are not a spec at all: empty input, unparseable JSON or YAML, a top level that is not an object, no `openapi` or `swagger` field, an unsupported version, no `paths`, no Query or Mutation fields, or more than 10MB. [Errors and warnings](https://typeship.dev/docs/reference/errors-and-warnings) lists every message with what to do about it. ## Sitemap [Every page of these docs](https://typeship.dev/llms.txt)