{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://library.dynastyplays.com/music/data/schema/music-schema.json",
  "title": "Dynasty Music Department Schema v1",
  "description": "Shared data contract for every music asset in the Dynasty Library Music Department. The Library shelf views, album pages, external playlist/landing pages, and K-D-Y-N radio all read this same structure. Never hardcode a tracklist or playlist in HTML.",
  "definitions": {
    "album": {
      "type": "object",
      "required": ["id", "title", "artist", "imprint", "shelf", "era", "source_type", "rights", "lead_track_id", "cover_image", "description", "tracks_source"],
      "properties": {
        "id": { "type": "string", "description": "Kebab-case, globally unique across the department. Used by K-D-Y-N blocks and playlist pages.", "pattern": "^[a-z0-9-]+$" },
        "catalog_id": { "type": "string", "description": "Dynasty Library Catalog row ID. DYN-#### for Dynasty originals, PUB-#### for public-domain/external works." },
        "title": { "type": "string" },
        "subtitle": { "type": "string" },
        "artist": { "type": "string" },
        "imprint": { "type": "string", "description": "e.g. Dynasty Music, Dynasty Public Domain, Dynasty Contributor" },
        "model": { "type": "string", "description": "Commercial model, e.g. 'Dynasty Free Music'." },
        "shelf": { "type": "string", "enum": ["dynasty-music", "public-domain-cohorts", "contributor-music"] },
        "era": { "type": "string", "description": "Cohort/era label used for K-D-Y-N block selection, e.g. '2026', '1923', '1960s'." },
        "source_type": { "type": "string", "enum": ["dynasty-original", "public-domain", "public-domain-derivative", "contributor"] },
        "rights": {
          "type": "object",
          "required": ["status"],
          "properties": {
            "status": { "type": "string", "enum": ["dynasty-owned", "public-domain-verified", "rights-review-pending", "contributor-licensed"] },
            "note": { "type": "string" },
            "verified_on": { "type": "string", "format": "date" }
          }
        },
        "status": { "type": "string", "enum": ["live", "pending", "draft", "archived"], "default": "pending" },
        "lead_track_id": { "type": "string", "description": "Track id used by the 'Play Track 1' control." },
        "runtime_summary": { "type": "string" },
        "track_count_summary": { "type": "string" },
        "cover_image": { "type": "string" },
        "cover_alt": { "type": "string" },
        "cover_tagline": { "type": "string" },
        "description": { "type": "string", "description": "Liner notes. Rendered under the cover block." },
        "audio_base_url": { "type": "string", "description": "Owned audio rail (Cloudflare R2). Track audio_url values should resolve against this." },
        "tracks_source": { "type": "string", "description": "Path to the tracks file for this album." },
        "lane": {
          "type": "object",
          "properties": {
            "lane": { "type": "string" },
            "department": { "type": "string" },
            "shelf": { "type": "string" },
            "asset": { "type": "string" },
            "path": { "type": "string" }
          }
        },
        "dkyn_eligible": { "type": "boolean", "default": true, "description": "False blocks the album from all radio rotations regardless of block filters." }
      }
    },
    "tracks_file": {
      "type": "object",
      "required": ["album_id", "tracks"],
      "properties": {
        "album_id": { "type": "string" },
        "audio_base_url": { "type": "string" },
        "tracks": { "type": "array", "items": { "$ref": "#/definitions/track" } }
      }
    },
    "track": {
      "type": "object",
      "required": ["id", "number", "title", "duration", "role_tag", "theme_tags", "blurb", "audio_url"],
      "properties": {
        "id": { "type": "string", "description": "Unique within the album. Referenced as '<album_id>:<track_id>' by K-D-Y-N blocks.", "pattern": "^[a-z0-9-]+$" },
        "number": { "type": "integer", "minimum": 1 },
        "title": { "type": "string" },
        "duration": { "type": "string", "description": "Display duration, m:ss. Empty string allowed while unmeasured." },
        "duration_seconds": { "type": "integer", "description": "Machine duration. Required for K-D-Y-N block fill math." },
        "role_tag": { "type": "string", "description": "Functional tag rendered as a chip: LEAD, EXPOSE, EMPOWER, SYSTEM, PAIN, BROKER, VALUES, PORTAL, CLOSE, BONUS, STANDARD, INSTRUMENTAL." },
        "theme_tags": { "type": "array", "items": { "type": "string" } },
        "blurb": { "type": "string" },
        "bonus": { "type": "boolean", "default": false },
        "audio_url": { "type": "string" },
        "original_work_id": { "type": ["string", "null"], "description": "Link to the public-domain source work (Library catalog PUB-#### id, or an external identifier) when this track derives from one." },
        "original_work": {
          "type": "object",
          "description": "Optional denormalized source detail for public-domain cohorts.",
          "properties": {
            "title": { "type": "string" },
            "composer": { "type": "string" },
            "year": { "type": "integer" },
            "source_url": { "type": "string" }
          }
        }
      }
    },
    "dkyn_block": {
      "type": "object",
      "description": "A radio block. References catalog IDs only — never its own copy of a tracklist.",
      "required": ["id", "name", "source"],
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "daypart": { "type": "string", "enum": ["morning-drive", "midday", "afternoon-drive", "evening", "late-night", "overnight"] },
        "hours": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 23 }, "description": "Local hours (America/Chicago) this block owns." },
        "days": { "type": "array", "items": { "type": "string", "enum": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] } },
        "dj": { "type": "string" },
        "bumper_copy": { "type": "string" },
        "rotation": { "type": "string", "enum": ["album-order", "shuffle", "weighted"], "default": "album-order" },
        "source": {
          "type": "object",
          "description": "One of: album_ids, track_refs, or a filter. Resolved at play time against the catalog.",
          "properties": {
            "album_ids": { "type": "array", "items": { "type": "string" } },
            "track_refs": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9-]+:[a-z0-9-]+$" } },
            "filter": {
              "type": "object",
              "properties": {
                "shelf": { "type": "string" },
                "era": { "type": "string" },
                "source_type": { "type": "string" },
                "role_tags": { "type": "array", "items": { "type": "string" } },
                "theme_tags": { "type": "array", "items": { "type": "string" } },
                "include_bonus": { "type": "boolean", "default": false }
              }
            }
          }
        }
      }
    }
  },
  "oneOf": [
    { "$ref": "#/definitions/album" },
    { "$ref": "#/definitions/tracks_file" }
  ]
}