Structured LLM Output Without JSON Schemas, A Different Approach

{
  "patient": {
    "name": "Jane Doe",
    "date_of_birth": "1990-03-15",
    "chief_complaint": "Persistent headache for 3 days",
    "vitals": {
      "blood_pressure": "120/80",
      "heart_rate": 72,
      "temperature": 98.6
    },
    "assessment": "Tension-type headache. No red flags.",
    "plan": "OTC analgesics, follow up in 1 week if no improvement"
  }
}

# Patient Intake

The JSON version gives you data. The [MDMA](https://github.com/mobile-reality/mdma) version gives you data **and** an interactive form the user fills out, without building a single line of frontend code.

At scale, the token difference compounds. If your application makes 10,000 LLM calls per day, switching from JSON to Markdown-based structured output can cut your token costs by a third.

### 10-15% Reasoning Degradation in JSON Mode

This one is less discussed but well-documented. When you force an LLM into JSON mode, you're constraining its generation process. The model can no longer "think out loud", it must produce valid JSON from the first token.

Multiple benchmarks show **10-15% performance degradation on reasoning tasks** when using constrained JSON output compared to free-form generation. The model is spending capacity on structural compliance instead of problem-solving.

With Markdown, the LLM writes in the format it was trained on. Markdown is the lingua franca of the internet, it appears massively in training data. The model doesn't fight the format; it flows with it.

### Schema Boilerplate That Scales with Complexity

A simple JSON Schema for a contact form is manageable. A schema for a multi-step KYC workflow with conditional fields, nested objects, and validation rules? You're looking at hundreds of lines of schema definition before writing any application logic.

Here's what a KYC form schema looks like in Pydantic:

Then you need a separate UI component to render this form, validation logic in the frontend, and mapping between the schema and the rendered fields.

With MDMA, the schema, the UI definition, and the validation rules are one thing:

id: kyc-form
type: form
fields:
  - name: full_name
    type: text
    label: Full Legal Name
    required: true
    sensitive: true
  - name: date_of_birth
    type: date
    label: Date of Birth
    required: true
    sensitive: true
  - name: ssn
    type: text
    label: Social Security Number
    required: true
    sensitive: true
    validation:
      pattern: "^\\d{3}-\\d{2}-\\d{4}$"
      message: "Format: XXX-XX-XXXX"
  - name: email
    type: email
    label: Email Address
    required: true
    sensitive: true
  - name: employment_status
    type: select
    label: Employment Status
    required: true
    options:
      - { label: Employed, value: employed }
      - { label: Self-Employed, value: self-employed }
      - { label: Unemployed, value: unemployed }
      - { label: Retired, value: retired }
  - name: annual_income
    type: number
    label: Annual Income
    required: true
    validation:
      min: 0
  - name: source_of_funds
    type: textarea
    label: Source of Funds
    required: true
  - name: is_pep
    type: checkbox
    label: Politically Exposed Person (PEP)
onSubmit: submit-kyc
`` `

Based on your description, this sounds like a P2 incident.
Let me set up the triage workflow.

## Incident Assessment

Natural language and structured components coexist in one document. The model doesn't need to choose between explaining context and collecting data, it does both.

## Extended Markdown: Forms, Tables, and Approval Gates from LLM Output

### How MDMA Extends Markdown with Interactive Components

[MDMA (Markdown Document with Mounted Applications)](https://github.com/mobile-reality/mdma) adds nine component types to standard Markdown via fenced code blocks with the `mdma` language tag:

| Component | Purpose | Example Use Case |
| --- | --- | --- |
| <code>form</code> | Structured data collection | Patient intake, bug reports, KYC |
| <code>table</code> | Tabular data with sorting/filtering | Search results, audit logs |
| <code>approval-gate</code> | Multi-step approval workflow | Manager sign-off, compliance review |
| <code>tasklist</code> | Checklist with completion tracking | Pre-deploy checklist, triage steps |
| <code>button</code> | Clickable action with confirmation | Notify Slack, deploy to production |
| <code>callout</code> | Highlighted message (info/warning/error) | SLA warnings, compliance notices |
| <code>chart</code> | Data visualization | Revenue trends, error rates |
| <code>webhook</code> | HTTP request trigger | Slack notifications, API calls |
| <code>thinking</code> | Collapsed AI reasoning | Debug transparency |

Components communicate through bindings, `{{field_name}}` expressions that resolve at runtime. When a user fills a form field, bound components update automatically.

### Code Example: From JSON Schema to a Single Prompt

**The JSON Schema approach** requires three artifacts:

1. Schema definition (Pydantic/JSON Schema)
2. LLM integration (function calling or structured output)
3. Frontend component (React form mapped to schema fields)

**The MDMA approach** requires one:

The LLM decides what fields to include based on the conversation. No predefined schema. The form structure emerges from context.

### What the User Actually Sees vs What the System Parses

When the LLM generates this response:

id: change-request
type: form
fields:
  - name: change_title
    type: text
    label: Change Title
    required: true
  - name: risk_level
    type: select
    label: Risk Level
    options:
      - { label: Low, value: low }
      - { label: Medium, value: medium }
      - { label: High, value: high }
  - name: rollback_plan
    type: textarea
    label: Rollback Plan
    required: true
onSubmit: submit-change
`` `

**The user sees**: a paragraph of text, a rendered form with input fields and dropdowns, and an approval gate with Approve/Deny buttons.

**The system sees**: typed AST nodes, validated component schemas, dispatchable actions, and a binding map connecting the form to the approval gate.

**The audit log sees**: every field change, every button click, every approval decision, timestamped, actor-tagged, and hash-chained.

One response. Three consumers. Zero custom UI code.

## MDMA vs Instructor vs Outlines vs Guidance

### Feature Comparison at a Glance

| Feature | Instructor | Outlines | Guidance | MDMA |
| --- | --- | --- | --- | --- |
| <strong>Output format</strong> | JSON (Pydantic) | JSON/regex/grammar | JSON/structured text | Markdown + YAML components |
| <strong>Schema definition</strong> | Python classes | JSON Schema/regex | Template programs | YAML in Markdown |
| <strong>Requires custom UI</strong> | Yes | Yes | Yes | No, renderer included |
| <strong>Human-readable output</strong> | No (raw JSON) | No | Partially | Yes, it's Markdown |
| <strong>Approval workflows</strong> | Not built-in | Not built-in | Not built-in | First-class&nbsp;<code>approval-gate</code> |
| <strong>Audit trail</strong> | Not built-in | Not built-in | Not built-in | Hash-chained event log |
| <strong>PII handling</strong> | Not built-in | Not built-in | Not built-in | Automatic detection &amp; redaction |
| <strong>Token efficiency</strong> | JSON overhead | JSON overhead | Varies | 34-38% fewer tokens |
| <strong>LLM compatibility</strong> | OpenAI, Anthropic, others | Local models (HF) | Local models | Any LLM (prompt-based) |
| <strong>Validation</strong> | Pydantic validators | Grammar constraints | Template constraints | YAML schema + field validation |

### When You Still Need JSON (and When You Don't)

**Use Instructor/Outlines/Guidance when:**

- Output feeds directly into a machine pipeline (no human interaction)
- You need guaranteed JSON for database insertion or API calls
- You're doing bulk extraction from documents (NER, classification)
- Latency is critical and you need constrained decoding

**Use MDMA when:**

- A human needs to see, review, or interact with the output
- You need approval workflows or multi-step processes
- Compliance requires audit trails (HIPAA, SOX, MiFID)
- You want the LLM to dynamically decide what data to collect
- You're building a chatbot that needs to do more than return text

The key distinction: Instructor and friends solve **LLM → machine** communication. MDMA solves **LLM → human → machine** communication.

## Building Human-in-the-Loop Workflows Without a Separate Frontend

### Approval Gates as First-Class Output

Most human-in-the-loop implementations follow this pattern:

1. LLM produces JSON
2. Backend stores the JSON
3. Frontend renders a custom approval UI
4. User approves/denies
5. Backend processes the decision

That's five steps across three systems. With MDMA, it's one:

id: deploy-approval
type: approval-gate
title: Production Deployment Approval
description: >
  Deploying v2.4.1 to production. Changes include
  the new payment processing module and updated rate limits.
requiredApprovers: 2
allowedRoles:
  - tech-lead
  - engineering-manager
  - director
onApprove: execute-deployment
onDeny: return-to-author
requireReason: true
`` `

## Step 1: Risk Assessment

id: pre-deploy-checklist
type: tasklist
items:
  - id: tests-pass
    text: All tests pass in CI
    required: true
  - id: code-review
    text: Code reviewed by 2 engineers
    required: true
  - id: staging-verified
    text: Changes verified on staging
    required: true
  - id: rollback-ready
    text: Rollback plan documented
    required: true
onComplete: checklist-done

id: change-approval
type: approval-gate
title: Change Approval
description: >
  Approve deployment of {{change_type}} change
  with {{risk_level}} risk level.
requiredApprovers: 1
allowedRoles:
  - tech-lead
  - engineering-manager
onApprove: execute-change
onDeny: reject-change
requireReason: true
`` `

npm install @mobile-reality/mdma-parser \
            @mobile-reality/mdma-runtime \
            @mobile-reality/mdma-renderer-react \
            @mobile-reality/mdma-prompt-pack

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import { remarkMdma } from '@mobile-reality/mdma-parser';
import { createDocumentStore } from '@mobile-reality/mdma-runtime';
import { MdmaProvider, MdmaDocument } from '@mobile-reality/mdma-renderer-react';

// Parse
const processor = unified().use(remarkParse).use(remarkMdma);
const ast = await processor.run(processor.parse(markdownString));

// Create runtime
const store = createDocumentStore(ast, {
  documentId: 'my-doc',
  sessionId: crypto.randomUUID(),
  environment: 'production',
});

// Render
function App() {
  return (
    <MdmaProvider store={store} ast={ast}>
      <MdmaDocument />
    </MdmaProvider>
  );
}

import { buildSystemPrompt } from '@mobile-reality/mdma-prompt-pack';

const systemPrompt = buildSystemPrompt({
  customPrompt: `You are an HR onboarding assistant. When a new
  employee needs to be onboarded, generate MDMA forms to collect
  their information, a tasklist for IT setup, and an approval
  gate for their manager.`,
});

// Works with OpenAI
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: systemPrompt },
    { role: 'user', content: 'New hire: Senior Engineer starting March 1st' },
  ],
});

// Works with Anthropic
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  system: systemPrompt,
  messages: [
    { role: 'user', content: 'New hire: Senior Engineer starting March 1st' },
  ],
});

// Parse the response, same code regardless of LLM provider
const ast = await processor.run(processor.parse(response.content));
const store = createDocumentStore(ast, { /* config */ });