{
    "$schema": "https://alexanderparker.github.io/instruction-template-specification/schema/v1.0/its-base-schema-v1.json",
    "version": "1.0.0",
    "extends": [
        "https://alexanderparker.github.io/instruction-template-specification/schema/v1.0/its-json-types-v1.json"
    ],
    "metadata": {
        "name": "API Response Documentation Template",
        "description": "Documents a REST endpoint whose example response JSON is authored literally in the template, with JSON type placeholders filling the generated values",
        "author": "Alexander Parker",
        "tags": [
            "example",
            "json",
            "api",
            "structured-output"
        ],
        "created": "2026-07-29T00:00:00Z"
    },
    "variables": {
        "apiBaseUrl": "https://api.example.com/v2",
        "resourceName": "orders",
        "includeErrorExample": true
    },
    "content": [
        {
            "type": "text",
            "text": "# ${resourceName} API\n\n## GET ${apiBaseUrl}/${resourceName}\n\nReturns a paginated collection of ${resourceName}.\n\n### Example response\n\n{\n  \"data\": [\n"
        },
        {
            "type": "placeholder",
            "id": "data_items",
            "instructionType": "json_array_items",
            "config": {
                "description": "three ${resourceName} objects, each with an id string, a status string and a total number",
                "displayName": "Data Items",
                "itemType": "object",
                "itemCount": 3
            }
        },
        {
            "type": "text",
            "text": "\n  ],\n  \"page\": 1,\n  \"pageSize\": 20,\n  \"total\": "
        },
        {
            "type": "placeholder",
            "id": "total_count",
            "instructionType": "json_number",
            "config": {
                "description": "a plausible total count of ${resourceName} across all pages",
                "displayName": "Total Count",
                "numberType": "integer"
            }
        },
        {
            "type": "text",
            "text": "\n}"
        },
        {
            "type": "conditional",
            "condition": "includeErrorExample == true",
            "content": [
                {
                    "type": "text",
                    "text": "\n\n### Error response\n\nReturned with HTTP status 404 when the resource does not exist.\n\n{\n  \"error\": {\n    \"code\": \"not_found\",\n    \"message\": "
                },
                {
                    "type": "placeholder",
                    "id": "error_message",
                    "instructionType": "json_string",
                    "config": {
                        "description": "a human-readable message about a missing ${resourceName} resource",
                        "displayName": "Error Message"
                    }
                },
                {
                    "type": "text",
                    "text": "\n  }\n}"
                }
            ]
        }
    ]
}