{
    "api": "YAML JSON TOON Database",
    "version": "1.0.0",
    "format": "json",
    "dataset": {
        "id": 1001,
        "slug": "http-cache-directives",
        "title": "HTTP Cache-Control Directives",
        "description": "Cache-Control directives for browser and shared caches, with example values, intended behavior, and common configuration mistakes.",
        "summary": "Cache-Control directives for browser and shared caches, with example values, intended behavior, and common configuration mistakes. Each row includes a practical application and a failure to check before using it.",
        "use_when": [
            "Choose cache policy for an API or a static asset.",
            "Debug a response that is stale or revalidated too often."
        ],
        "caveats": [
            "These are response examples; request directives can have different effects.",
            "Extensions depend on the cache implementation."
        ],
        "related": [
            "http-conditional-requests",
            "http-response-headers"
        ],
        "category": "HTTP Status Codes",
        "category_slug": "http-status-codes",
        "tags": "http-status-codes,http cache directives,reference,engineering",
        "view_count": 0,
        "created_at": 1791798640,
        "updated_at": 1791798640,
        "reviewed_at": "2026-10-12",
        "sources": [
            {
                "title": "IETF HTTP caching",
                "url": "https://httpwg.org/specs/rfc9111.html"
            },
            {
                "title": "RFC 8246 immutable responses",
                "url": "https://httpwg.org/specs/rfc8246.html"
            },
            {
                "title": "RFC 5861 cache extensions",
                "url": "https://www.rfc-editor.org/rfc/rfc5861.html"
            }
        ],
        "reading": [
            "http-caching-with-etags-and-cache-control"
        ],
        "provenance": "Original editorial reference notes by YJTOON, informed by the linked primary documentation. External specifications retain their own licenses.",
        "entry_count": 12,
        "fields": [
            {
                "section": "data",
                "field": "directive",
                "type": "string",
                "example": "max-age"
            },
            {
                "section": "data",
                "field": "example",
                "type": "string",
                "example": "max-age=300"
            },
            {
                "section": "data",
                "field": "use",
                "type": "string",
                "example": "Permit reuse while the response is fresh for 30…"
            },
            {
                "section": "data",
                "field": "pitfall",
                "type": "string",
                "example": "Age already spent in an upstream cache counts t…"
            }
        ]
    },
    "data": [
        {
            "directive": "max-age",
            "example": "max-age=300",
            "use": "Permit reuse while the response is fresh for 300 seconds.",
            "pitfall": "Age already spent in an upstream cache counts toward freshness."
        },
        {
            "directive": "s-maxage",
            "example": "s-maxage=60",
            "use": "Set freshness for shared caches separately from browsers.",
            "pitfall": "It does not set a browser-only lifetime."
        },
        {
            "directive": "no-cache",
            "example": "no-cache",
            "use": "Store a response but validate it before reuse.",
            "pitfall": "The name does not mean do not store."
        },
        {
            "directive": "no-store",
            "example": "no-store",
            "use": "Ask caches not to retain this request or response.",
            "pitfall": "It does not erase copies stored before this response."
        },
        {
            "directive": "private",
            "example": "private",
            "use": "Keep a personalized response out of shared caches.",
            "pitfall": "A browser may still store it."
        },
        {
            "directive": "public",
            "example": "public, max-age=600",
            "use": "Explicitly permit shared-cache storage under HTTP rules.",
            "pitfall": "Do not expose user-specific content."
        },
        {
            "directive": "must-revalidate",
            "example": "must-revalidate",
            "use": "Require validation after freshness expires.",
            "pitfall": "It does not force validation while fresh."
        },
        {
            "directive": "proxy-revalidate",
            "example": "proxy-revalidate",
            "use": "Apply the stale-validation requirement to shared caches.",
            "pitfall": "Private browser caches are outside this directive."
        },
        {
            "directive": "no-transform",
            "example": "no-transform",
            "use": "Ask intermediaries to preserve the representation.",
            "pitfall": "Compression and media pipelines need their own testing."
        },
        {
            "directive": "immutable",
            "example": "public, max-age=31536000, immutable",
            "use": "Avoid revalidation during freshness for versioned assets.",
            "pitfall": "Change the URL when the asset bytes change."
        },
        {
            "directive": "stale-while-revalidate",
            "example": "max-age=60, stale-while-revalidate=30",
            "use": "Allow a bounded stale response during background validation.",
            "pitfall": "Support and CDN configuration vary."
        },
        {
            "directive": "stale-if-error",
            "example": "max-age=60, stale-if-error=600",
            "use": "Allow bounded stale reuse on eligible failures.",
            "pitfall": "Not suitable for every correctness-sensitive response."
        }
    ]
}