Introduction to FOON

FOON is a TypeScript SDK that transforms messy, inconsistent JSON data into your strict, validated schemas. It uses AI to understand field semantics and generate mapping plans, but the actual transformation is deterministic and validated.

What FOON Is

  • A JSON transformation library that bridges the gap between external data sources and your internal types
  • AI-assisted mapping that understands semantic relationships between fields
  • Schema-first with mandatory JSON Schema validation
  • Provider-agnostic - works with Gemini, OpenAI, Ollama, and more
  • Production-ready with caching, observability, and security features

What FOON Isn't

  • Not a replacement for manual mappings - Use FOON when you have unpredictable input formats
  • Not an AI black box - The AI proposes mappings, but validation ensures correctness
  • Not a data cleaning tool - FOON transforms structure, not content quality

Core Philosophy

Traditional JSON transformation requires you to write brittle mapping code for every possible input format:

// The old way: endless if-statements and field mappings
const customer = {
  name: {
    given: payload.fullName?.split(' ')[0] || payload.first_name || payload.firstName,
    family: payload.fullName?.split(' ')[1] || payload.last_name || payload.lastName,
  },
  email: payload.email || payload.email_addr || payload.emailAddress,
  // ... and on and on
};

FOON takes a different approach:

  1. Define your target schema once - What you want, not how to get it
  2. Let AI understand semantics - It figures out that fullName maps to name.given and name.family
  3. Trust the validation - If it passes your schema, it's correct

Key Concepts

Mapping Plans

A mapping plan is the AI-generated strategy for transforming input to output. It includes:

  • Source-to-target field mappings
  • Transformation operations (split, merge, direct copy)
  • Confidence scores for each mapping

Deterministic Transforms

Once a mapping plan exists, transformations are purely deterministic. The same input with the same plan always produces the same output. No AI randomness in your production data.

Schema Validation

Every output is validated against your JSON Schema. Invalid data throws an error - it never slips through silently.

Next Steps