Output Formatting

Output Formatting Specialist

Enforces deterministic structured output generation to ensure downstream systems receive predictable, parseable data. When this skill is active, the model acts as a strict format enforcer, transforming free-form reasoning or API responses into validated, schema-constrained outputs suitable for programmatic consumption.

TL;DR Checklist

• Define target schema or template before generating output
• Validate all fields against type constraints and required keys
• Escape special characters that break JSON or markdown parsing
• Wrap generation in error-handling fallback for malformed output
• Log format compliance metrics for debugging pipeline issues
• Reject free-text responses when structured data is explicitly requested

When to Use

Use this skill when:

• Building AI agent pipelines that parse LLM outputs into application logic
• Generating API responses or configuration files that must be machine-readable
• Creating test fixtures, mock data, or dataset annotations with strict column types
• Designing prompt templates that require consistent formatting across multiple runs
• Integrating external tools (databases, spreadsheets, visualization engines) that reject malformed input

When NOT to Use

Avoid this skill for:

• Creative writing, narrative generation, or open-ended brainstorming tasks
• Real-time chat interactions where latency outweighs structural benefits
• Prototypes where rapid iteration matters more than output reliability
• Legacy systems without modern parsing libraries (stick to simple CSV or plain text)

Core Workflow

1. Analyze Consumption Requirements — Identify who/what will consume the output and what schema it expects. Checkpoint: Confirm required fields, data types, nullability rules, and max lengths before drafting templates.

2. Select Output Format — Choose between JSON Schema, Markdown Tables, YAML Config, or strict CSV based on downstream constraints. Checkpoint: Validate that the selected format aligns with existing pipeline tooling (e.g., pandas for CSV, Pydantic for JSON).

3. Construct Validation Layer — Implement runtime checks using typed parsers or schema validators. Checkpoint: Ensure validation runs BEFORE output is returned to the caller; fail fast on type mismatches.

4. Render Structured Output — Generate the response using template rendering or serialization functions. Checkpoint: Verify escaping rules for strings containing quotes, newlines, or HTML entities.

5. Sanitize & Normalize — Remove trailing commas, fix casing inconsistencies, normalize whitespace. Checkpoint: Run output through a linter or format checker (e.g., black, prettier, JSON linters).

6. Record Format Compliance — Track success/failure rates by schema version and input pattern. Checkpoint: Log validation errors with exact field paths for downstream debugging.

Implementation Patterns

Pattern 1: JSON Schema Validation with Pydantic

Use typed models to enforce structure before serialization. This catches type mismatches early and provides clear error messages.

from pydantic import BaseModel, Field, ValidationError
from typing import Optional
import json

class StructuredOutput(BaseModel):
    """Strict output schema for downstream consumption."""
    
    status: str = Field(..., pattern=r"^(success|failure|pending)$")
    timestamp_ms: int = Field(..., gt=0)
    metadata: dict[str, str] = Field(default_factory=dict)
    payload: list[dict[str, float]] | None = None
    
    def to_json(self, indent: int = 2) -> str:
        """Serialize to JSON with guaranteed escaping and formatting."""
        return self.model_dump_json(indent=indent)

def render_response(
    status: str, 
    timestamp_ms: int, 
    metadata: Optional[dict[str, str]] = None,
    payload: Optional[list[dict[str, float]]] = None
) -> str:
    """Generate validated JSON output or raise ValidationError."""
    try:
        out = StructuredOutput(
            status=status,
            timestamp_ms=timestamp_ms,
            metadata=metadata or {},
            payload=payload
        )
        return out.to_json()
    except ValidationError as e:
        raise RuntimeError(f"Format validation failed: {e.errors()[0]['msg']}") from e

Pattern 2: Markdown Table Rendering (BAD vs. GOOD)

# ❌ BAD — Manual string concatenation breaks on edge cases, missing alignment, no escaping
def bad_table(rows):
    header = "Column A | Column B\n"
    body = "\n".join([f"{r['a']} | {r['b']}" for r in rows])
    return f"{header}\n{body}"

# ✅ GOOD — Safe, aligned, escapes pipes and newlines, uses standard library
def good_table(rows: list[dict[str, str]], columns: list[str]) -> str:
    """Render a pipe-aligned markdown table with automatic column width calculation."""
    if not rows:
        return ""
    
    # Calculate max widths per column
    col_widths = {col: len(col) for col in columns}
    for row in rows:
        for col in columns:
            val_len = len(str(row.get(col, "")))
            col_widths[col] = max(col_widths[col], val_len)
    
    def escape(val: str) -> str:
        return str(val).replace("|", "\\|").replace("\n", " ")
    
    header = "| " + " | ".join(c for c in columns) + " |"
    separator = "|" + "|".join("-" * (col_widths[c] + 2) for c in columns) + "|"
    body_lines = [
        "| " + " | ".join(escape(str(row.get(c, ""))) for c in columns) + " |"
        for row in rows
    ]
    
    return "\n".join([header, separator] + body_lines)

Pattern 3: Fallback Serialization Strategy

When structured generation fails, degrade gracefully instead of crashing the pipeline.

import json
from typing import Any

def safe_serialize(data: Any, fallback_format: str = "json") -> str:
    """Attempt structured serialization; fall back to string representation on failure."""
    try:
        if fallback_format == "json":
            return json.dumps(data, default=str, ensure_ascii=False)
        elif fallback_format == "csv":
            if isinstance(data, list) and all(isinstance(r, dict) for r in data):
                headers = data[0].keys()
                lines = [",".join(headers)]
                for row in data:
                    lines.append(",".join(str(v) for v in row.values()))
                return "\n".join(lines)
    except Exception as e:
        # Graceful degradation — never swallow errors silently
        return f"ERROR:[serialization_failed] {e}"
    
    return str(data)

Constraints

MUST DO

• Define the target schema or template BEFORE generating any content
• Validate output against the schema using typed parsers (Pydantic, Zod, or equivalent)
• Escape special characters that break parsers (|, \n, ", {, })
• Provide clear error messages with field paths when validation fails
• Log format compliance rates to detect regression in downstream consumption

MUST NOT DO

• Generate free-text responses when a structured schema is explicitly defined
• Rely on regex for JSON or YAML parsing — use proper parsers only
• Suppress validation errors to keep pipelines running — fail fast instead
• Hardcode column widths or field lengths without dynamic calculation
• Return mixed-format outputs (e.g., JSON containing unescaped markdown tables)

Output Template

When implementing or reviewing output formatting logic, produce:

1. Target Schema/Template — Explicit definition of expected structure with types and constraints
2. Validation Layer — Code snippet showing runtime checks or schema enforcement
3. Serialization Function — Safe rendering logic with escaping and fallback handling
4. Compliance Check — Confirmation that output passes linter/schema validator before delivery
5. Error Handling Path — Documented graceful degradation strategy for malformed generations

Related Skills

Live References

Authoritative documentation links for this domain. The model follows markdown links at load time to resolve external references and inline content.

• JSON Schema Specification — Official JSON Schema specification for defining, validating, and documenting structured data formats
• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format — IETF standard defining the JSON format and its canonical representation rules
• YAML 1.2 Specification — Official YAML specification for human-readable configuration and data serialization formats
• CSV Format (RFC 4180) — IETF standard defining the CSV file format for tabular data interchange
• OpenAPI Specification — OpenAPI specification for describing API request/response formats as structured output contracts