API Schema Inferrer

API Schema Inferrer

This skill automatically generates schemas from examples in OpenAPI Specification (OAS) files. It analyzes example and examples fields in requests and responses, then produces corresponding schema definitions.

When to Use This Skill

Use this skill when:

• Endpoints have examples or example fields but no schema defined
• You want to quickly bootstrap schemas from sample data
• Converting from formats that don't require explicit schemas

Prerequisites

pip install pyyaml

Running Schema Inference

Preview Changes (Dry Run)

python3 skills/api-schema-inferrer/scripts/infer_schemas.py path/to/spec.yaml --dry-run

This shows what schemas would be added without modifying the file.

Apply Changes

python3 skills/api-schema-inferrer/scripts/infer_schemas.py path/to/spec.yaml

This will:

1. Create a backup file (spec.yaml.backup)
2. Relocate any example nested inside a schema: block up to the media-type level (the OAS-canonical sibling location)
3. Infer schemas from all examples in requests and responses, including shared bodies under components.requestBodies and components.responses
4. Add schemas where they are missing
5. Preserve existing schemas (never overwrites)

Why the relocation pre-step matters

Some toolchains (notably AMF) emit specs where example is nested inside schema::

content:
  application/json:
    schema:
      example:
        foo: bar

OAS 3.x defines example as a sibling of schema at the Media Type Object level. Tooling that follows the spec (including the portal generator in this repo) won't render schema-nested examples. The script automatically moves them so both the inferrer and downstream tooling can find them.

What It Does

The tool:

• Detects types: Automatically determines string, number, integer, boolean, array, object, null
• Handles nested objects: Recursively processes complex structures
• Infers formats: Detects email, uri, date formats from string patterns
• Sets required fields: Marks all fields as required (conservative approach)
• Adds descriptions: Includes placeholder descriptions that need to be updated

Example

Before:

paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            examples:
              createUser:
                value:
                  name: "John Doe"
                  email: "john@example.com"
                  age: 30
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                id: "123"
                status: "active"

After running inference:

paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [name, email, age]
              properties:
                name:
                  type: string
                  description: "Auto-generated from example. TODO: Add meaningful description for 'name'"
                email:
                  type: string
                  format: email
                  description: "Auto-generated from example. TODO: Add meaningful description for 'email'"
                age:
                  type: integer
                  description: "Auto-generated from example. TODO: Add meaningful description for 'age'"
            examples:
              createUser:
                value:
                  name: "John Doe"
                  email: "john@example.com"
                  age: 30
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required: [id, status]
                properties:
                  id:
                    type: string
                    description: "Auto-generated from example. TODO: Add meaningful description for 'id'"
                  status:
                    type: string
                    description: "Auto-generated from example. TODO: Add meaningful description for 'status'"
              example:
                id: "123"
                status: "active"

Post-Inference Steps

After running the inference tool:

1. Review generated schemas: Check that inferred types are correct
2. Update descriptions: Replace all "TODO" placeholders with meaningful descriptions
3. Add enums: If a field has limited options, add an enum array
4. Refine required fields: Adjust the required array if some fields are optional
5. Add constraints: Add minLength, maxLength, minimum, maximum, etc. as needed
6. Run validation: Use the api-spec-validator skill to check for remaining issues

Using with Claude

Ask Claude to infer schemas:

"Infer schemas from examples in my API spec at path/to/spec.yaml"
"Generate schemas from the examples in specs/my-api.yaml"
"My spec has examples but no schemas - can you add them?"

Related Skills

• api-spec-validator - Validate OAS specs against AI-agent-friendly rules
• api-doc-generator - Generate markdown documentation with curl examples from OAS specs