Audience

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openpresentation.org/schema/opf-audience/v1",
  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
  "title": "Audience",
  "description": "Schema for audience records. Each record names an audience archetype (e.g. 'executive', 'engineering-team', 'investor') and carries seniority, technical-fluency, decision-power, and attention-budget hints used by AI-driven generation. Documents reference an audience from 'audience', which also accepts free-form text.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
  "type": "object",
  "required": [
    "$schema",
    "id",
    "name"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "const": "https://openpresentation.org/schema/opf-audience/v1",
      "description": "Identifies a published record file as a audience record. Required in a published file; an embedded copy omits it."
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "The audience's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
      "examples": [
        "executive",
        "board",
        "engineering-team",
        "investor",
        "customer",
        "sales",
        "marketing",
        "all-hands",
        "candidates",
        "regulatory"
      ]
    },
    "name": {
      "type": "string",
      "description": "Human-readable audience name shown in pickers.",
      "examples": [
        "Executives",
        "Board of Directors",
        "Engineering Team",
        "Investors",
        "Customers",
        "Sales Team",
        "Marketing Team",
        "All Hands",
        "Candidates",
        "Regulators"
      ]
    },
    "summary": {
      "type": "string",
      "description": "One-sentence positioning of the audience — who they are and what they care about.",
      "examples": [
        "Senior leaders who need the recommendation up front, the evidence behind it, and the ask.",
        "Practitioners building the system; they want depth, mechanism, and tradeoffs."
      ]
    },
    "description": {
      "type": "string",
      "description": "Longer prose describing the audience archetype and how to address them.",
      "examples": [
        "Executives are time-poor and decision-oriented. Lead with the recommendation, support it with three claims and one number per claim, and end with a clear ask. Avoid drilling into mechanisms unless invited; offer to follow up rather than including everything in the deck."
      ]
    },
    "seniority": {
      "type": "string",
      "enum": [
        "ic",
        "manager",
        "director",
        "vp",
        "c-suite",
        "mixed"
      ],
      "description": "Typical seniority level of the audience. Engines use this as a hint for default depth and pacing."
    },
    "technicalFluency": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high",
        "mixed"
      ],
      "description": "Typical technical fluency of the audience. AI generation uses this to decide whether to expand or assume technical terminology."
    },
    "decisionPower": {
      "type": "string",
      "enum": [
        "informational",
        "advisory",
        "decision-maker"
      ],
      "description": "Whether the audience is expected to be informed, to advise, or to actually decide. Shapes the strength of the closing ask."
    },
    "attentionBudgetMinutes": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Realistic upper bound on this audience's focused attention for a single presentation, in minutes. Used as a hint when comparing against duration and the resolved narrative's duration range."
    },
    "recommendedNarratives": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Soft cross-link: ids of narratives in the same catalog that work well for this audience. Used by picker UIs to suggest narratives once an audience is chosen. Never resolved, embedded or validated as references.",
      "examples": [
        [
          "scqa",
          "board-meeting",
          "qbr"
        ]
      ]
    },
    "recommendedTones": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Soft cross-link: ids of tones in the same catalog that work well for this audience. Never resolved, embedded or validated as references.",
      "examples": [
        [
          "formal",
          "authoritative"
        ]
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free-form labels for filtering and search.",
      "examples": [
        [
          "leadership",
          "external"
        ],
        [
          "internal",
          "engineering"
        ],
        [
          "external",
          "customer"
        ]
      ]
    },
    "preview": {
      "type": "object",
      "description": "Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional.",
      "properties": {
        "src": {
          "type": "string",
          "format": "uri",
          "description": "Main preview image (PNG/JPG)."
        },
        "thumbnailSrc": {
          "type": "string",
          "format": "uri",
          "description": "Smaller thumbnail preview suited to dense grid views."
        },
        "vectorSrc": {
          "type": "string",
          "format": "uri",
          "description": "SVG / vector preview for crisp scaling at any size."
        }
      }
    }
  }
}