Convert Nested JSON Objects to YAML Schema

Nested JSON to YAML Schema

Real-world JSON almost always contains nested objects. The YAML schema must define each nested structure as its own type: object with its own properties block.

Example JSON Input

{
  "server": {
    "host": "0.0.0.0",
    "port": 3000,
    "tls": {
      "enabled": true,
      "certPath": "/etc/ssl/cert.pem",
      "keyPath": "/etc/ssl/key.pem"
    }
  },
  "logging": {
    "level": "info",
    "format": "json"
  }
}

Generated YAML Schema

type: object
properties:
  server:
    type: object
    properties:
      host:
        type: string
      port:
        type: integer
      tls:
        type: object
        properties:
          enabled:
            type: boolean
          certPath:
            type: string
          keyPath:
            type: string
        required:
          - enabled
    required:
      - host
      - port
  logging:
    type: object
    properties:
      level:
        type: string
      format:
        type: string
    required:
      - level
      - format
required:
  - server
  - logging

How Nesting Works in YAML Schema

Each nested JSON object introduces a new type: object node in the schema tree. The converter recursively traverses the JSON, creating a property definition for every key it encounters. The required array at each level lists the keys that must be present.

Deep Nesting Strategies

For deeply nested configurations (4+ levels):

1. Use $ref definitions -- Extract reusable sub-schemas into a definitions block and reference them with $ref: "#/definitions/TlsConfig".
2. Flatten where possible -- If nesting is purely organizational, consider a flatter structure with dot-notation keys.
3. Add additionalProperties: false -- Prevents unexpected keys from passing validation.

Schema Composition with $ref

definitions:
  TlsConfig:
    type: object
    properties:
      enabled:
        type: boolean
      certPath:
        type: string
      keyPath:
        type: string
    required:
      - enabled

type: object
properties:
  server:
    type: object
    properties:
      tls:
        $ref: "#/definitions/TlsConfig"

This approach keeps the schema DRY and makes individual sections testable in isolation.