One-Shot & Structured Output

Compare two output modes: One-Shot returns freeform markdown, while Structured returns validated JSON conforming to a Zod schema.

Generated Recipe

Enter a recipe name and click "Generate Recipe" to get started.

How It Works

Structured JSON Mode (New!)

Uses Cloudflare Workers AI's native response_format parameter with json_schema. The model (@cf/meta/llama-4-scout-17b-16e-instruct) natively enforces the schema, guaranteeing valid JSON output without prompt engineering.

One-Shot Markdown Mode

Traditional prompt engineering approach. The AI generates freeform markdown text based on natural language instructions. No schema enforcement, but allows creative formatting.

Tech Stack: TanStack Start API routes → Cloudflare Workers AI (@cf/meta/llama-4-scout-17b-16e-instruct) → JSON Mode with response_format → Zod validation

What I Learned

✓
Native JSON Mode is reliable:Cloudflare's response_format parameter enforces schemas at the model level, not via prompts. This eliminates JSON parsing errors.
✓
Prompt engineering is brittle:The old approach (asking AI to "respond with valid JSON") failed 30-40% of the time. Models added markdown, extra text, or malformed JSON requiring regex hacks.
✓
Model selection matters:Not all Cloudflare models support JSON Mode. Must use @cf/meta/llama-4-scout-17b-16e-instruct or other supported models.
✓
Zod + JSON Mode is the ideal combo:JSON Mode guarantees valid structure, Zod provides TypeScript types and runtime validation for extra safety.
✗
JSON Mode doesn't support streaming:Trade-off - you get guaranteed structure but can't stream tokens. Use streaming for chat, structured mode for data extraction.

Key Differences

Structured JSON

  • ✅ Guaranteed valid JSON
  • ✅ Type-safe with Zod
  • ✅ Database-ready
  • ✅ No parsing errors
  • ⏱️ No streaming
  • 🎯 API endpoints

One-Shot Markdown

  • ✅ Flexible formatting
  • ✅ Creative freedom
  • ✅ Human-readable
  • ✅ Streaming supported
  • ⚠️ No type safety
  • 📝 Content pages