Structured Output

Structured Output Skill

Bonded to: advanced-techniques-agent

Quick Start

Skill("custom-plugin-prompt-engineering:structured-output")

Parameter Schema

parameters:
  output_format:
    type: enum
    values: [json, yaml, xml, csv, markdown_table]
    default: json

  schema_validation:
    type: boolean
    default: true

  strict_mode:
    type: boolean
    default: false
    description: "Fail on any schema violation"

Output Formats

JSON Output

Respond with valid JSON only. No additional text before or after.

Schema:
{
  "field1": "string value",
  "field2": 123,
  "field3": ["array", "items"],
  "field4": {
    "nested": "object"
  }
}

YAML Output

Respond with valid YAML only.

field1: string value
field2: 123
field3:
  - array
  - items
field4:
  nested: object

XML Output

Respond with valid XML only.

<root>
  <field1>string value</field1>
  <field2>123</field2>
  <field3>
    <item>array</item>
    <item>items</item>
  </field3>
</root>

Schema Enforcement Patterns

JSON Schema

Output must strictly match this JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "score": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"},
      "maxItems": 5
    }
  },
  "required": ["name", "score"],
  "additionalProperties": false
}

TypeScript-Style Schema

Output must match this TypeScript interface:

interface Response {
  name: string;           // Required, non-empty
  score: number;          // 0-100
  tags?: string[];        // Optional, max 5 items
  metadata?: {
    created: string;      // ISO date format
    version: number;
  };
}

Pydantic-Style Schema

Output must match this Pydantic model:

class Response(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    score: float = Field(..., ge=0, le=100)
    tags: Optional[List[str]] = Field(default=None, max_items=5)

Prompting Techniques

1. Schema-First Prompting

## Output Schema
[Define exact schema]

## Task
[What to do]

## Input
[Data to process]

Remember: Output ONLY valid [format] matching the schema above.

2. Example-Guided Output

## Task
Extract entities from text.

## Example
Input: "Apple CEO Tim Cook announced iPhone 15"
Output: {
  "entities": [
    {"name": "Apple", "type": "ORG"},
    {"name": "Tim Cook", "type": "PERSON"},
    {"name": "iPhone 15", "type": "PRODUCT"}
  ]
}

## Your Turn
Input: "[actual_text]"
Output:

3. Constrained Generation

Generate output following these STRICT rules:
1. Valid JSON only
2. No markdown code blocks
3. No explanatory text
4. Exactly these fields: [field_list]
5. All strings in quotes
6. No trailing commas

Validation Strategies

validation_layers:
  syntax:
    - JSON/YAML/XML parse check
    - Well-formed structure
    - Proper encoding

  schema:
    - Required fields present
    - Types match
    - Constraints satisfied

  semantic:
    - Values make sense
    - References are valid
    - Business rules met

recovery:
  on_parse_error: "Request regeneration with error details"
  on_schema_error: "Identify specific violations, request fix"
  on_semantic_error: "Flag for review"

Common Patterns

Entity Extraction

{
  "entities": [
    {"text": "extracted text", "type": "ENTITY_TYPE", "confidence": 0.95}
  ]
}

Classification Result

{
  "label": "category_name",
  "confidence": 0.87,
  "alternatives": [
    {"label": "other_category", "confidence": 0.10}
  ]
}

Analysis Report

{
  "summary": "Brief summary",
  "findings": [
    {"id": 1, "description": "Finding", "severity": "high"}
  ],
  "recommendations": ["Action 1", "Action 2"],
  "metadata": {"analyzed_at": "2025-01-01T00:00:00Z"}
}

Troubleshooting

Integration

integrates_with:
  - prompt-design: Structure prompt for output
  - prompt-evaluation: Validate output quality
  - react-pattern: Tool return formats

parsing_libraries:
  python: json, pydantic, jsonschema
  javascript: ajv, zod
  go: encoding/json, gojsonschema

References

See references/GUIDE.md for advanced schema patterns. See assets/config.yaml for configuration options.