Tone

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openpresentation.org/schema/opf-tone/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": "Tone",
  "description": "Schema for tone records. Each record names a presentation tone (e.g. 'formal', 'casual', 'inspirational') and carries voice cues, anti-patterns, and sample phrases that AI-driven generation uses to shape output. Documents reference a tone from 'tone'.\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-tone/v1",
      "description": "Identifies a published record file as a tone record. Required in a published file; an embedded copy omits it."
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "The tone'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": [
        "formal",
        "casual",
        "inspirational",
        "technical",
        "persuasive",
        "authoritative",
        "conversational"
      ]
    },
    "name": {
      "type": "string",
      "description": "Human-readable tone name shown in pickers.",
      "examples": [
        "Formal",
        "Casual",
        "Inspirational",
        "Technical",
        "Persuasive",
        "Authoritative",
        "Conversational"
      ]
    },
    "summary": {
      "type": "string",
      "description": "One-sentence positioning of the tone — when to reach for it.",
      "examples": [
        "Polished, restrained voice for board, investor, and regulator audiences.",
        "Warm, plain-spoken voice for internal updates and customer storytelling."
      ]
    },
    "description": {
      "type": "string",
      "description": "Longer prose describing the tone and the kinds of decks it suits.",
      "examples": [
        "Authoritative without being cold. Use third-person constructions, full sentences, and concrete numbers. Avoid hedges and humor that depend on shared in-jokes; rely on clarity and precision to land."
      ]
    },
    "voiceCues": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Short directives that shape AI generation toward this tone. Phrased as imperatives, e.g. 'use second-person', 'favor short sentences', 'lead with the recommendation'.",
      "examples": [
        [
          "Use third person.",
          "Lead with the recommendation, then evidence.",
          "Quote concrete numbers; avoid round-tripping ranges."
        ]
      ]
    },
    "avoid": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Anti-patterns that AI generation should not produce when this tone is active.",
      "examples": [
        [
          "Slang, idioms, or in-jokes.",
          "Hedging language ('maybe', 'sort of', 'I think').",
          "Marketing superlatives ('world-class', 'best-in-class')."
        ]
      ]
    },
    "samplePhrases": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Short example phrases that exemplify this tone. Used by picker UIs and as few-shot examples for AI generation.",
      "examples": [
        [
          "Q4 revenue grew 18% year over year, led by enterprise expansion.",
          "We recommend approving the Series B raise at $30M.",
          "Net retention was 124%; gross retention was 96%."
        ]
      ]
    },
    "recommendedNarratives": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Soft cross-link: ids of narratives in the same catalog this tone pairs well with. Used by picker UIs to suggest narratives once a tone is chosen. Never resolved, embedded or validated as references.",
      "examples": [
        [
          "board-meeting",
          "qbr",
          "scqa"
        ]
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free-form labels for filtering and search.",
      "examples": [
        [
          "business",
          "executive"
        ],
        [
          "internal",
          "warm"
        ],
        [
          "motivational",
          "keynote"
        ]
      ]
    },
    "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."
        }
      }
    }
  }
}