{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/audivo-dev/json-schema/audivo-dev-chart-response-schema.json",
  "title": "ChartResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/audivo-dev-catalog-api-openapi.yml#/components/schemas/ChartResponse",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "category",
    "language",
    "size",
    "data",
    "excluded"
  ],
  "properties": {
    "category": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "language": {
      "anyOf": [
        {
          "$ref": "#/$defs/Language"
        },
        {
          "enum": [
            null
          ]
        }
      ]
    },
    "size": {
      "$ref": "#/$defs/TierClamp"
    },
    "data": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "$ref": "#/$defs/ShowSummary"
      },
      "description": "The chart, in provider order, at most `size.allowed` long."
    },
    "excluded": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "$ref": "#/$defs/DiscoveryExclusion"
      }
    }
  },
  "$defs": {
    "DiscoveryExclusion": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "title",
        "reason",
        "detail"
      ],
      "description": "A provider entry a caller cannot act on, named rather than dropped: without a usable feed URL there is no `show_id` to derive and nothing to select. Present so a list never shrinks silently.",
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        },
        "reason": {
          "type": "string",
          "enum": [
            "no_feed_url",
            "invalid_feed_url"
          ]
        },
        "detail": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1000
        }
      }
    },
    "FeedUrl": {
      "type": "string",
      "format": "uri",
      "minLength": 1,
      "maxLength": 2048,
      "description": "An RSS/Atom feed URL."
    },
    "Language": {
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$",
      "maxLength": 35,
      "description": "A BCP-47 language tag (general syntax check, not full IANA subtag validation)."
    },
    "NullableUri": {
      "description": "A URL, or `null`.",
      "anyOf": [
        {
          "type": "string",
          "format": "uri",
          "maxLength": 2048
        },
        {
          "enum": [
            null
          ]
        }
      ]
    },
    "ShowId": {
      "type": "string",
      "pattern": "^sh_[a-z2-7]{16}$",
      "description": "Canonical show identifier."
    },
    "ShowSummary": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "show_id",
        "title",
        "feed_url",
        "itunes_id",
        "author",
        "categories",
        "artwork_url",
        "music_led",
        "music_led_basis"
      ],
      "description": "One show as a discovery surface returns it (search or chart), before any selection rule applies. `show_id` is derived from the provider's iTunes id when it carries one and from the feed URL otherwise, so it is stable across the two surfaces and the quote. `music_led` is the music-led marking: a coarse, show-level judgement from the provider's category labels — `music_led_basis` says which — that cannot see a music bed inside a talk show and over-excludes spoken commentary *about* music; the caller can opt back in when quoting.",
      "properties": {
        "show_id": {
          "$ref": "#/$defs/ShowId"
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        },
        "feed_url": {
          "$ref": "#/$defs/FeedUrl"
        },
        "itunes_id": {
          "description": "The iTunes collection ID, or `null` if the provider knows none.",
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "author": {
          "description": "The show's author as the provider carries it, or `null`.",
          "anyOf": [
            {
              "type": "string",
              "maxLength": 300
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "categories": {
          "type": "array",
          "maxItems": 50,
          "items": {
            "type": "string",
            "maxLength": 100
          },
          "description": "The provider's category names for the show, in provider order."
        },
        "artwork_url": {
          "$ref": "#/$defs/NullableUri"
        },
        "music_led": {
          "type": "boolean",
          "description": "Whether the show is music-led; see the schema description."
        },
        "music_led_basis": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300,
          "description": "What `music_led` is based on, in words a caller can show."
        }
      }
    },
    "TierClamp": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "requested",
        "allowed",
        "limit",
        "clamped"
      ],
      "description": "One number after the caller's tier had its say. `requested` is what was asked for, `allowed` what the tier permitted, `limit` the ceiling that produced it — reported whether or not the ceiling bit, because \"your 40-show chart became 10\" is the sentence a caller can act on and \"10 shows\" alone is not.",
      "properties": {
        "requested": {
          "type": "integer",
          "minimum": 1
        },
        "allowed": {
          "type": "integer",
          "minimum": 0
        },
        "limit": {
          "type": "integer",
          "minimum": 1
        },
        "clamped": {
          "type": "boolean"
        }
      }
    }
  }
}