Prompt Metadata Schema

A prompt without metadata is an anonymous artifact. You cannot search for it effectively, cannot understand its history, cannot determine whether it is safe to use in production, and cannot find the person to ask when it behaves unexpectedly. Metadata is not documentation overhead — it is the index that makes the library functional.

The metadata schema is the specification for what you know about every stored prompt. The schema should be defined once, enforced consistently, and extended deliberately when the organization's needs evolve. Fields are either required (no prompt enters the library without them) or optional (contextual, provided when applicable). Required fields are non-negotiable. A prompt missing a required field is not a stored prompt — it is a draft.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "PromptRecord",
  "type": "object",
  "required": [
    "id", "name", "version", "author", "intent",
    "input_schema", "output_schema", "test_date",
    "status", "tags"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier. Format: {domain}-{task}-{sequence}. E.g., sales-summarize-001",
      "pattern": "^[a-z]+-[a-z]+-[0-9]{3}
quot;
    },
    "name": {
      "type": "string",
      "description": "Human-readable name. Sentence case, no abbreviations."
    },
    "version": {
      "type": "string",
      "description": "Semantic version. Major.minor.patch",
      "pattern": "^[0-9]+\.[0-9]+\.[0-9]+
quot;
    },
    "author": {
      "type": "string",
      "description": "Current owner (team or individual). Not the original creator — the current responsible party."
    },
    "intent": {
      "type": "string",
      "description": "One sentence: what does this prompt do and why does it exist."
    },
    "input_schema": {
      "type": "object",
      "description": "Required inputs and their types. Every variable in the prompt template must appear here.",
      "additionalProperties": { "type": "string" }
    },
    "output_schema": {
      "type": "object",
      "description": "Expected output structure. For structured outputs, this is the schema. For prose, describe the format.",
      "properties": {
        "format": { "type": "string", "enum": ["json", "markdown", "prose", "csv", "structured"] },
        "schema": { "type": "object" },
        "example": { "type": "string" }
      }
    },
    "parent_version": {
      "type": ["string", "null"],
      "description": "ID of the prompt this was derived from, if any. Null for original prompts."
    },
    "test_date": {
      "type": "string",
      "format": "date",
      "description": "Date this version was last validated against production inputs."
    },
    "known_failures": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Documented failure modes. E.g., 'Fails to extract dates from informal text.'"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "description": "Taxonomy tags. Must include at least one domain tag."
    },
    "status": {
      "type": "string",
      "enum": ["draft", "active", "deprecated"],
      "description": "draft: not production-ready. active: approved for production. deprecated: superseded, do not use."
    },
    "changelog": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["version", "date", "author", "change"],
        "properties": {
          "version": { "type": "string" },
          "date": { "type": "string", "format": "date" },
          "author": { "type": "string" },
          "change": { "type": "string" }
        }
      }
    }
  }
}