LLM Output Schema Migrator

Migrate LLM JSON between schema versions

When you change a prompt, swap models, or upgrade an API, the shape of the JSON your model returns often changes too — keys get renamed, nesting moves, arrays get wrapped. This tool lets you write a simple old-path → new-path mapping and reshape a pasted response into your target schema, so downstream code keeps working without manual editing.

When schema migration becomes necessary

LLM API schemas change more often than most developers expect. Common scenarios that force a migration:

• Swapping providers. Moving from OpenAI to Anthropic or Gemini means the message content moves from choices[0].message.content to content[0].text. Every downstream parser breaks.
• Structured output prompt changes. You update the system prompt to return a new field name (say summary instead of abstract) and all existing parsers that looked for abstract now miss it.
• API version upgrades. A provider releases a new response version that reorganizes token usage fields, adds a new nesting level, or renames finish_reason to stop_reason.
• Model-specific schema quirks. Different models within the same provider occasionally return subtly different field structures for function calls or tool use.

Writing mapping rules in this tool is faster than editing downstream code for a one-off transformation, and it documents the exact shape change in a portable format you can share with a colleague.

How the mapping works

Each line of the mapping is a rule: read the value at the source path in the pasted JSON, then write it at the destination path in a brand-new output object. Paths use dot notation for object keys (message.content) and either bracket or dot notation for array indices (choices[0] or choices.0). Writing to a path that doesn’t exist yet creates the intermediate objects and arrays for you, so you can both flatten and re-nest in a single pass. Any source path that can’t be resolved is reported back as unmatched rather than silently failing.

Concrete mapping examples

# Rename a top-level key
result -> data

# Pull nested content up to the root
choices[0].message.content -> text

# Move token counts under a new namespace
usage.prompt_tokens -> meta.tokens.input
usage.completion_tokens -> meta.tokens.output

# Re-nest flat fields into a record shape
id -> record.id
name -> record.name
created_at -> record.createdAt

Tips and examples

• Renaming a top-level key: result -> data.
• Pulling a nested value up: choices[0].message.content -> text.
• Re-nesting flat fields: id -> record.id and name -> record.name.
• Run the migrated output back through the tool with a second mapping to do a multi-step transformation when one pass isn’t enough.
• Save your mappings as a text file alongside your integration code — they serve as lightweight documentation of what the old schema looked like.