Purpose

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openpresentation.org/schema/opf-purpose/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": "Purpose",
  "description": "Schema for purpose records. Each record names a presentation objective such as informing, aligning, persuading, driving a decision, or selling. Documents reference a purpose from 'purpose', which also accepts free-form text and inline Purpose objects.\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-purpose/v1",
      "description": "Identifies a published record file as a purpose record. Required in a published file; an embedded copy omits it."
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "The purpose'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": [
        "inform",
        "decide",
        "align",
        "persuade",
        "educate",
        "report",
        "pitch",
        "sell",
        "plan"
      ]
    },
    "name": {
      "type": "string",
      "description": "Human-readable purpose name shown in pickers.",
      "examples": [
        "Inform",
        "Drive a Decision",
        "Align",
        "Persuade"
      ]
    },
    "summary": {
      "type": "string",
      "description": "One-sentence positioning of the purpose — what this deck is trying to accomplish."
    },
    "description": {
      "type": "string",
      "description": "Longer prose describing when to use this purpose and how it should shape a deck."
    },
    "outcome": {
      "type": "string",
      "description": "Desired audience outcome after the presentation.",
      "examples": [
        "Approve the recommendation",
        "Understand the status",
        "Adopt the plan"
      ]
    },
    "successCriteria": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Observable signals that the deck accomplished this purpose."
    },
    "recommendedNarratives": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Soft cross-link: ids of narratives in the same catalog that work well for this purpose. Never resolved, embedded or validated as references."
    },
    "recommendedTones": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Soft cross-link: ids of tones in the same catalog that work well for this purpose. Never resolved, embedded or validated as references."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free-form labels for filtering and search."
    },
    "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."
        }
      }
    }
  }
}