Schema Sleuth#

Paste raw sample data — any format, any messiness — and get production-ready schemas in every language you need. No manual typing, no guessing nullability, no forgetting nested objects.

Supports: Pydantic v2, Zod, TypeScript interfaces, JSON Schema Draft 7, Go structs. Zero config.

---

Trigger Phrases#

• "infer schema", "generate schema", "generate types", "what's the schema for this"
• "pydantic from json", "zod from json", "zod from this", "typescript interface from"
• "generate pydantic model", "generate zod schema", "type this response"
• "model this data", "schema from sample", "parse this data format"
• "/schema-sleuth"

---

How to Provide Input#

text

# Option 1: Paste raw JSON (one example)
/schema-sleuth
{"id": 42, "name": "Alice", "email": "alice@example.com", "role": null}

# Option 2: Multiple examples for better inference
/schema-sleuth
Sample 1: {"id": 1, "status": "active", "score": 98.5}
Sample 2: {"id": 2, "status": "inactive", "score": null}
Sample 3: {"id": 3, "status": "pending", "score": 72.0}

# Option 3: CSV data
/schema-sleuth
user_id,name,email,created_at,is_premium
1,Alice,alice@ex.com,2024-01-15,true
2,Bob,,2024-02-01,false
3,Carol,carol@ex.com,,true

# Option 4: Specify output format
/schema-sleuth --output pydantic,zod
{"id": "uuid-here", "payload": {"action": "click", "timestamp": 1710000000}}

# Option 5: Named schema
/schema-sleuth --name UserEvent
{"user_id": 123, "event": "purchase", "amount": 49.99}

---

Step 1: Normalize the Input#

Before inferring types, standardize the input:

1. Detect format: Is it JSON, JSON array, NDJSON, CSV, TSV, YAML, or plain key-value text?
2. Parse all samples: If multiple samples provided, parse each one separately
3. Build a field inventory: For each field seen across ALL samples, track every value observed

text

Field: "score"
  Values seen: 98.5, null, 72.0
  → Type: float | null (nullable float)
  → Not always present: check if all samples have it

Field: "status"
  Values seen: "active", "inactive", "pending"
  → Type: string — but all values are from a fixed set → candidate ENUM
  → Enum candidates: active | inactive | pending

---

Step 2: Infer Types with Pattern Detection#

For each field, determine the most specific type:

Primitive Type Rules#

Observed ValuesInferred TypeNotestrue / false``bool``42, 100 (all integers)int``3.14, 98.5 (any float)floatPromote if mixed int+float"hello" (generic string)str / string``null anywhereMark field as Optional / nullableField missing in some samplesMark as OptionalBoth null and missingOptional with default None

Semantic Pattern Detection (look at string values)#

PatternDetected TypeValidation"2024-01-15"``dateISO 8601 date"2024-01-15T10:30:00Z"``datetimeISO 8601 datetime1710000000 (10-digit int)unix_timestampNote: could be POSIX ts"alice@example.com"``emailApply EmailStr / z.string().email()"https://..." / "http://..."``urlApply AnyUrl / z.string().url()"550e8400-e29b-41d4-..."``uuidUUID v4 formatRepeated values, ≤ 8 distinct in 5+ samplesenumList all values as literals"#FF5733"``hex_colorString with patternAll values positive integersConsider PositiveInt

Nested Object Detection#

json

{"user": {"id": 1, "name": "Alice"}, "timestamp": "2024-01-01T00:00:00Z"}

→ user field is a nested object → create a sub-model User / z.object()

Array Detection#

json

{"tags": ["python", "api", "backend"], "scores": [98.5, 72.0]}

→ tags: list[str] / z.array(z.string()) → scores: list[float] / z.array(z.number())

---

Step 3: Generate Schemas#

Generate all requested output formats. Default: Pydantic + Zod + TypeScript interface.

Pydantic v2 (Python)#

python

from pydantic import BaseModel, EmailStr, AnyUrl
from typing import Optional
from datetime import datetime
from enum import Enum
from uuid import UUID

class StatusEnum(str, Enum):
    active = "active"
    inactive = "inactive"
    pending = "pending"

class UserEvent(BaseModel):
    id: int
    name: str
    email: Optional[EmailStr] = None
    status: StatusEnum
    score: Optional[float] = None
    created_at: datetime
    is_premium: bool

    model_config = {"str_strip_whitespace": True}

Pydantic rules:

• Use Optional[T] = None for nullable or missing fields
• Use EmailStr for email strings (requires pydantic[email])
• Use AnyUrl for URL strings
• Use str(Enum) for string enums
• Add model_config block with common defaults

Zod (TypeScript/JavaScript)#

typescript

import { z } from "zod";

const StatusEnum = z.enum(["active", "inactive", "pending"]);

export const UserEventSchema = z.object({
  id: z.number().int(),
  name: z.string(),
  email: z.string().email().nullable().optional(),
  status: StatusEnum,
  score: z.number().nullable().optional(),
  created_at: z.string().datetime(),
  is_premium: z.boolean(),
});

export type UserEvent = z.infer<typeof UserEventSchema>;

Zod rules:

• Chain .nullable() when null was observed, .optional() when field was absent
• Use .int() for integer fields
• Use .datetime() for ISO datetime strings
• Always export the inferred type alongside the schema
• Export both schema and type from the same file

TypeScript Interface (no runtime validation)#

typescript

type Status = "active" | "inactive" | "pending";

interface UserEvent {
  id: number;
  name: string;
  email?: string | null;
  status: Status;
  score?: number | null;
  created_at: string; // ISO 8601 datetime
  is_premium: boolean;
}

JSON Schema Draft 7#

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "UserEvent",
  "type": "object",
  "required": ["id", "name", "status", "created_at", "is_premium"],
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "email": { "type": ["string", "null"], "format": "email" },
    "status": { "type": "string", "enum": ["active", "inactive", "pending"] },
    "score": { "type": ["number", "null"] },
    "created_at": { "type": "string", "format": "date-time" },
    "is_premium": { "type": "boolean" }
  },
  "additionalProperties": false
}

Go Struct#

go

package models

import "time"

type Status string

const (
    StatusActive   Status = "active"
    StatusInactive Status = "inactive"
    StatusPending  Status = "pending"
)

type UserEvent struct {
    ID          int        `json:"id"`
    Name        string     `json:"name"`
    Email       *string    `json:"email,omitempty"`
    Status      Status     `json:"status"`
    Score       *float64   `json:"score,omitempty"`
    CreatedAt   time.Time  `json:"created_at"`
    IsPremium   bool       `json:"is_premium"`
}

---

Step 4: Output Report#

Always structure the output as:

markdown

## Schema Sleuth: [SchemaName]
Input: [N samples] | Detected format: JSON | Fields: 7 | Nullable: 2 | Optional: 1 | Enums: 1

### Field Analysis

| Field | Observed Types | Inferred Type | Nullable | Optional | Notes |
|-------|---------------|--------------|----------|----------|-------|
| `id` | int | `int` | No | No | |
| `name` | str | `str` | No | No | |
| `email` | str, null | `Optional[EmailStr]` | Yes | Yes | Email pattern detected |
| `status` | str (3 values) | `StatusEnum` | No | No | Enum: active/inactive/pending |
| `score` | float, null | `Optional[float]` | Yes | Yes | |
| `created_at` | str | `datetime` | No | No | ISO 8601 datetime |
| `is_premium` | bool | `bool` | No | No | |

### Confidence Notes

- `score`: seen as null in 1/3 samples — marked Optional. If it's always present but can be null, remove `Optional`.
- `email`: missing in 1 CSV row — marked Optional. Confirm if email is truly optional in your domain.
- `status` enum: only 3 values seen in 3 samples — may not be exhaustive. Add `| str` to the type if other values are possible.

### Generated Schemas

[Pydantic v2 code block]
[Zod code block]
[TypeScript interface code block]
[JSON Schema code block — if requested]
[Go struct code block — if requested]

---

Quick Mode#

For a single JSON object, just paste it and get back types immediately:

text

Input: {"user_id": 123, "action": "click", "ts": 1710000000}

Quick Schema:
- user_id: int (required)
- action: str (required) — consider enum if values are limited
- ts: int — looks like Unix timestamp (10 digits), consider datetime

Pydantic: UserEvent(user_id: int, action: str, ts: int)
Zod: z.object({ user_id: z.number().int(), action: z.string(), ts: z.number().int() })
TS: { user_id: number; action: string; ts: number }

---

Edge Cases#

SituationHandlingField has null in every sampleType is None / null → flag as "always null, probably placeholder"Empty string "" in some samplesDistinguish from null — may need str | None + validatorIntegers and floats mixedAlways promote to floatIntegers that look like booleans (0/1)Flag: "could be bool or int — confirm intent"Very long strings (> 500 chars)Flag as "possibly free text / markdown / HTML, consider Text type"Array with mixed types [1, "a", null]``list[int | str | None] / z.array(z.union([z.number(), z.string(), z.null()]))Deeply nested objectsRecursively generate sub-models/sub-schemasDate vs datetime ambiguityIf no time component seen, use date; if any has time, use datetimeLarge integers (> 2^53)Flag: "may exceed JavaScript Number precision — use BigInt or string"UUID-like stringsDetect v4 pattern, use UUID type or z.string().uuid()

---

Parser Generation (Optional)#

If user says "also write the parser", generate extraction code:

Python parser#

python

import json
from pathlib import Path

def parse_user_events(data: str | dict | list) -> list[UserEvent]:
    """Parse raw JSON string, dict, or list into UserEvent objects."""
    if isinstance(data, str):
        raw = json.loads(data)
    else:
        raw = data

    if isinstance(raw, list):
        return [UserEvent.model_validate(item) for item in raw]
    return [UserEvent.model_validate(raw)]

# Usage:
events = parse_user_events(api_response_text)

TypeScript parser#

typescript

export function parseUserEvents(raw: unknown): UserEvent[] {
  const input = Array.isArray(raw) ? raw : [raw];
  return input.map((item) => UserEventSchema.parse(item));
}

// With error details:
export function safeParseUserEvents(raw: unknown): {
  data: UserEvent[] | null;
  errors: string[] | null;
} {
  try {
    return { data: parseUserEvents(raw), errors: null };
  } catch (e) {
    return { data: null, errors: [String(e)] };
  }
}

---

Why This Doesn't Already Exist#

Tools like quicktype do JSON → types, but require a CLI install and produce verbose output that often needs manual cleanup. This skill:

1. Handles multiple samples — sees score: null in sample 2 and correctly marks it Optional; quicktype with one sample misses nullability
2. Detects semantic types — "alice@example.com" → EmailStr, not just str
3. Infers enums from repeated values — 3 samples with only "active"/"inactive"/"pending" → Literal enum, not generic string
4. Multi-language in one pass — Pydantic + Zod + TS interface simultaneously
5. Explains its reasoning — confidence table shows exactly which fields need human review
6. Zero install — no npm install quicktype, no CLI, works from any data paste

---

Author#

Canlah AI — Run performance marketing without breaking your brand.

• GitHub: github.com/PHY041
• All Skills: clawhub.ai/PHY041