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

bash

pip install pyyaml

Running Schema Inference

Preview Changes (Dry Run)

bash

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

bash

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

This will:

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

Why the relocation pre-step matters

Some toolchains (notably AMF) emit specs where

example

is nested inside

schema:

yaml

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:

yaml

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:

yaml

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:

Review generated schemas: Check that inferred types are correct
Update descriptions: Replace all "TODO" placeholders with meaningful descriptions
Add enums: If a field has limited options, add an
```
enum
```
array
Refine required fields: Adjust the
```
required
```
array if some fields are optional
Add constraints: Add
```
minLength
```
,
```
maxLength
```
,
```
minimum
```
,
```
maximum
```
, etc. as needed
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

api-schema-inferrer

NPX Install

Tags

SKILL.md Content

API Schema Inferrer

When to Use This Skill

Prerequisites

Running Schema Inference

Preview Changes (Dry Run)

Apply Changes

Why the relocation pre-step matters

What It Does

Example

Post-Inference Steps

Using with Claude

Related Skills