Generate YAML Schema for OpenAPI Specification

Q: Generate YAML Schema for OpenAPI Specification

## JSON to OpenAPI-Compatible YAML Schema OpenAPI (formerly Swagger) uses a subset of JSON Schema to define request and response models. Converting JSON API payloads to YAML Schema produces definitions that plug directly into an OpenAPI specification. ### Example JSON API Response json { "id": 42, "name": "Alice Johnson", "email": "alice@example.com", "role": "admin", "createdAt": "2024-01-15T09:30:00Z", "profile": { "avatar": "https://cdn.example.com/alice.jpg", "bio": "F

Learn how to convert JSON API models into YAML Schema definitions compatible with OpenAPI 3.x. Covers components/schemas, $ref references, discriminator, oneOf/anyOf, and request/response models.

Advanced Patterns

Detailed Explanation

JSON to OpenAPI-Compatible YAML Schema

OpenAPI (formerly Swagger) uses a subset of JSON Schema to define request and response models. Converting JSON API payloads to YAML Schema produces definitions that plug directly into an OpenAPI specification.

Example JSON API Response

{
  "id": 42,
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "role": "admin",
  "createdAt": "2024-01-15T09:30:00Z",
  "profile": {
    "avatar": "https://cdn.example.com/alice.jpg",
    "bio": "Full-stack developer"
  }
}

OpenAPI-Compatible YAML Schema

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
        name:
          type: string
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, editor, viewer]
        createdAt:
          type: string
          format: date-time
          readOnly: true
        profile:
          $ref: "#/components/schemas/UserProfile"
      required:
        - id
        - name
        - email
        - role

    UserProfile:
      type: object
      properties:
        avatar:
          type: string
          format: uri
          nullable: true
        bio:
          type: string
          maxLength: 500

OpenAPI-Specific Keywords

Keyword	Purpose
`readOnly`	Field appears in responses only
`writeOnly`	Field appears in requests only (e.g., password)
`nullable`	Allows null (OpenAPI 3.0 style)
`format`	Extended formats: `int32`, `int64`, `float`, `double`
`example`	Sample value for documentation
`deprecated`	Marks field as deprecated

Using `$ref` for Reuse

components:
  schemas:
    UserList:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
        pagination:
          $ref: "#/components/schemas/Pagination"

    Pagination:
      type: object
      properties:
        page:
          type: integer
        perPage:
          type: integer
        total:
          type: integer

Polymorphism with discriminator

components:
  schemas:
    Notification:
      oneOf:
        - $ref: "#/components/schemas/EmailNotification"
        - $ref: "#/components/schemas/SmsNotification"
      discriminator:
        propertyName: type
        mapping:
          email: "#/components/schemas/EmailNotification"
          sms: "#/components/schemas/SmsNotification"

Request vs Response Models

Create separate schemas for input (create/update) and output (response):

UserCreate:
  type: object
  properties:
    name:
      type: string
    email:
      type: string
      format: email
    password:
      type: string
      writeOnly: true
      minLength: 8
  required:
    - name
    - email
    - password

UserResponse:
  allOf:
    - $ref: "#/components/schemas/UserCreate"
    - type: object
      properties:
        id:
          type: integer
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true

Use Case

API-first development requires defining schemas before writing code. By taking a sample JSON response from an existing API or prototype and converting it to OpenAPI-compatible YAML schema, you bootstrap API documentation and can generate client SDKs, server stubs, and validation middleware automatically.

Try It — JSON to YAML Schema

Open full tool →