OpenAPI & JSON Schema — FAQ for Engineers#

This FAQ collects answers to the questions engineers actually ask when working with OpenAPI and JSON Schema in real projects. It’s aimed at mid–senior developers who want clarity, best practices, and shortcuts without digging through dry specification text.

1. What’s the difference between OpenAPI and Swagger?#

Swagger was the original project name; OpenAPI is the standardized specification managed by the OpenAPI Initiative. Swagger tooling (like Swagger UI and Codegen) still exists, but they consume the OpenAPI spec.
Think: Swagger = tools, OpenAPI = spec.

2. How does OpenAPI 3.1 differ from 3.0 (and 3.2)?#

• 3.1: Full alignment with JSON Schema 2020-12, new webhooks, nullable removed in favor of JSON Schema type: [ ... , "null"], more consistent keyword usage.
• 3.2: Incremental changes — clarifies file upload semantics, expands examples, refines parameter serialization.
  Always check the revision history for subtle shifts.

3. Does OpenAPI fully support JSON Schema?#

No — OAS 3.1 references JSON Schema 2020-12, but with restrictions. For example, $id and $anchor aren’t always relevant inside an OAS context, and certain JSON Schema vocabularies aren’t supported. Treat OAS as a subset integration rather than a full JSON Schema processor.

4. What’s the best way to structure a large OpenAPI spec?#

Break it into modular files and use $ref for reuse:

• schemas/ for data models
• paths/ for operations
• components/ for shared responses, parameters, headers

Keep a master openapi.yaml that stitches them together. This makes diffs cleaner and avoids merge conflicts.

5. How do I version my API in OpenAPI?#

Avoid encoding version in paths (/v1/…) unless necessary. Preferred approaches:

• Use semantic versioning in info.version.
• Add version headers (Accept: application/vnd.myapi+json;version=2).
• Maintain parallel specs (e.g., openapi.v1.yaml, openapi.v2.yaml) when breaking changes occur.

6. How do I document error handling properly?#

• Define a standard error schema in components/schemas/Error.
• Reuse it across responses (default, 4XX, 5XX).
• Include machine-readable codes and human-readable messages.
• Document error examples — engineers care as much about how errors look as they do about success responses.

7. How should I handle polymorphism (oneOf, anyOf, allOf) in OAS?#

• Use oneOf with a discriminator when clients need to resolve types reliably.
• Use allOf for composition (base + extension).
• Avoid anyOf unless absolutely necessary — it’s hard for client generation and validation.
  Polymorphism is powerful, but poorly supported in some SDKs.

8. What are the common pitfalls when writing OpenAPI specs?#

• Forgetting to define content type (application/json) → leads to poor tooling support.
• Using nullable in 3.1+ (deprecated).
• Overloading enums instead of using reusable schemas.
• Mixing camelCase and snake_case field names inconsistently.
• Not providing examples — which reduces the usefulness of generated mocks.

9. How do I represent file uploads in OpenAPI?#

For single file:

content:
  multipart/form-data:
    schema:
      type: object
      properties:
        file:
          type: string
          format: binary

For multiple files: use array of string with format: binary.

Note: semantics changed slightly in OAS 3.2, so always check version-specific guidance.

10. How do I keep my spec “always current”?#

• Treat it as code, version-controlled with PR reviews.
• Validate on every commit (e.g., CI pipeline with Spectral + OpenAPI validator).
• Keep doc tooling (Swagger UI, Redoc, etc.) automatically generated from the spec, not manually edited.
• Make the spec the source of truth — everything else derives from it.

11. What’s the difference between example and examples in OpenAPI?#

• example: a single inline example (value).
• examples: multiple named examples, each with a summary + value.

Use examples for complex scenarios, but keep at least one example for fast tooling previews.

12. How can I use OpenAPI to generate SDKs and clients?#

Leverage codegen tools:

• openapi-generator (broad language support)
• swagger-codegen (legacy, but still used)
• oazapfts (TypeScript-first)

Always inspect generated code — don’t assume it’s production-ready. Often you’ll wrap generated clients with custom logic.

13. What’s the right way to document authentication?#

• Define under components/securitySchemes (e.g., API keys, OAuth2, Bearer tokens).
• Apply globally under security: or per-operation if mixed.
• Include at least one example of an authenticated request.

This prevents “guesswork” by client developers.

14. How do I validate my JSON data against a schema?#

Use libraries like:

• AJV (JavaScript)
• jsonschema (Python)
• Everit (Java)

For APIs, many frameworks (Express, FastAPI, Spring Boot) have middleware/plugins that validate requests/responses automatically against your OpenAPI spec.