Schema Guide (v1.0)

Human-readable guide to PromptPack v1.0 entities and their properties. For the auto-generated technical reference, see Schema Reference.

Current Version

This documents the v1.0 schema. For the latest version with multimodal support, see the v1.1 Schema Guide.

Root Properties

The root object of every PromptPack file. Required fields are id, name, version, template_engine, and prompts.

Field	Type	Required	Description
$schema	string	No	JSON Schema reference for validation and IDE support. Default: https://promptpack.org/schema/v1/promptpack.schema.json
id	string	Yes	Unique identifier for the pack. Lowercase with hyphens only. Pattern: ^[a-z][a-z0-9-]*$ (1–100 chars).
name	string	Yes	Human-readable display name for the pack (1–200 chars).
version	string	Yes	Pack version following Semantic Versioning 2.0.0. Optional v prefix. Examples: "1.0.0", "v2.1.3".
description	string	No	Detailed description of the pack’s purpose. Supports markdown (max 5000 chars).
template_engine	TemplateEngine	Yes	Template engine configuration shared across all prompts.
prompts	object<string, Prompt>	Yes	Map of task type keys to prompt definitions. Must contain at least one entry.
fragments	object<string, string>	No	Shared template fragments. Keys are fragment names, values are fragment content strings.
tools	object<string, Tool>	No	Tool definitions that prompts can reference. Keys are tool names, values are tool specs.
metadata	Metadata	No	Optional pack-level metadata for categorization and discovery.
compilation	Compilation	No	Information about when and how the pack was compiled. Generated by packc.

Collections are keyed maps, not arrays

prompts, fragments, and tools are all objects (keyed maps), not arrays. Each key serves as the identifier for the entry. For example, prompts maps task type strings like "support" or "billing" to their Prompt definitions.

Minimal Example

{
  "$schema": "https://promptpack.org/schema/v1/promptpack.schema.json",
  "id": "my-pack",
  "name": "My Pack",
  "version": "1.0.0",
  "template_engine": {
    "version": "v1",
    "syntax": "{{variable}}"
  },
  "prompts": {
    "greeting": {
      "id": "greeting",
      "name": "Greeter",
      "version": "1.0.0",
      "system_template": "You are a friendly assistant for {{company}}."
    }
  }
}

---

Template Engine

Configuration for how variables are substituted and fragments are resolved across all prompts.

Field	Type	Required	Description
version	string	Yes	Template engine version (e.g., "v1").
syntax	string	Yes	Variable substitution syntax pattern (e.g., "{{variable}}").
features	string[]	No	Supported template features. Allowed values: "basic_substitution", "fragments", "conditionals", "loops", "filters".

"template_engine": {
  "version": "v1",
  "syntax": "{{variable}}",
  "features": ["basic_substitution", "fragments"]
}

---

Prompt

A single prompt configuration within a pack. Each prompt represents a specific task type (e.g., "support", "sales") with its own template, variables, tools, and validation rules. Prompts can evolve independently with their own version numbers.

Field	Type	Required	Description
id	string	Yes	Unique identifier, typically matching the map key. Pattern: ^[a-z][a-z0-9_-]*$.
name	string	Yes	Human-readable name.
version	string	Yes	Prompt version following Semantic Versioning, independent from the pack version.
system_template	string	Yes	The system prompt template. Use template syntax (e.g., {{variable}}) for variable substitution.
description	string	No	Detailed description of the prompt’s purpose and behavior.
variables	Variable[]	No	Variable definitions for template placeholders.
tools	string[]	No	List of tool names this prompt can use. Tools must be defined in the pack-level tools map.
tool_policy	ToolPolicy	No	Policy governing how tools can be used.
pipeline	PipelineConfig	No	Pipeline configuration defining processing stages and middleware.
parameters	Parameters	No	LLM generation parameters (temperature, max_tokens, etc.).
validators	Validator[]	No	Validation rules (guardrails) applied to LLM responses.
tested_models	TestedModel[]	No	Model testing results documenting performance across different models.
model_overrides	object<string, ModelOverride>	No	Model-specific template modifications. Keys are model names (e.g., "claude-3-opus", "gpt-4").

"prompts": {
  "support": {
    "id": "support",
    "name": "Support Bot",
    "version": "1.0.0",
    "system_template": "You are a {{role}} assistant for {{company}}.\n\nHelp resolve their issue.",
    "variables": [
      { "name": "role", "type": "string", "required": true, "example": "support agent" },
      { "name": "company", "type": "string", "required": true, "default": "TechCo" }
    ],
    "tools": ["lookup_order", "create_ticket"],
    "parameters": { "temperature": 0.7, "max_tokens": 1500 }
  }
}

---

Variable

A template variable definition with type information and validation rules.

Field	Type	Required	Description
name	string	Yes	Variable name used in templates (e.g., {{name}}). Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$.
type	string	Yes	Data type. One of: "string", "number", "boolean", "object", "array".
required	boolean	Yes	Whether this variable must be provided at runtime.
default	any	No	Default value when the variable is not provided.
description	string	No	Human-readable description of the variable’s purpose.
example	any	No	Example value showing expected format and content.
validation	Validation	No	Validation rules applied to the variable value at runtime.

Validation

Rules applied to variable values at runtime.

Field	Type	Description
pattern	string	Regular expression pattern (for string types).
min_length	integer	Minimum string length. Minimum value: 0.
max_length	integer	Maximum string length. Minimum value: 1.
minimum	number	Minimum numeric value (for number types).
maximum	number	Maximum numeric value (for number types).
enum	any[]	List of allowed values.

{
  "name": "priority",
  "type": "string",
  "required": true,
  "description": "Support ticket priority level",
  "validation": {
    "enum": ["low", "medium", "high", "urgent"]
  }
}

---

Tool

A tool definition following the function calling convention. Tools enable the LLM to call external functions. Tools are defined at the pack level and referenced by name in each prompt’s tools array.

Field	Type	Required	Description
name	string	Yes	Tool name. Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$.
description	string	Yes	What the tool does. The LLM uses this to decide when to call it.
parameters	object	No	JSON Schema object defining the tool’s input parameters (see below).

Tool Parameters (JSON Schema Format)

Tool parameters use standard JSON Schema format. The parameters object must have type: "object" with a properties map and an optional required array.

Field	Type	Required	Description
type	string	Yes	Must be "object".
properties	object	Yes	Map of parameter names to their JSON Schema definitions.
required	string[]	No	List of required parameter names.

"tools": {
  "create_ticket": {
    "name": "create_ticket",
    "description": "Create a support ticket with title, description, and priority",
    "parameters": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "description": "Ticket title"
        },
        "priority": {
          "type": "string",
          "enum": ["low", "medium", "high", "urgent"]
        }
      },
      "required": ["title"]
    }
  }
}

---

Tool Policy

Governance policy for tool usage. Controls when and how tools can be called by the LLM.

Field	Type	Required	Description
tool_choice	string	No	"auto" (LLM decides), "required" (must use tools), or "none" (tools disabled). Default: "auto".
max_rounds	integer	No	Maximum number of LLM-tool-LLM cycles per turn. Minimum: 1. Default: 5.
max_tool_calls_per_turn	integer	No	Maximum tool calls allowed in a single turn. Minimum: 1. Default: 10.
blocklist	string[]	No	Tool names that are not allowed for this prompt (overrides the tools list).

---

Parameters

LLM generation parameters controlling the model’s behavior and output characteristics.

Field	Type	Required	Description
temperature	number	No	Sampling temperature (0–2). Higher values increase randomness.
max_tokens	integer	No	Maximum number of tokens to generate. Minimum: 1.
top_p	number	No	Nucleus sampling parameter (0–1). Alternative to temperature.
top_k	integer or null	No	Top-k sampling. null means no limit. Minimum: 1.
frequency_penalty	number	No	Penalty for token frequency (-2 to 2). Positive values reduce repetition.
presence_penalty	number	No	Penalty for token presence (-2 to 2). Positive values encourage new topics.

"parameters": {
  "temperature": 0.7,
  "max_tokens": 1500,
  "top_p": 0.9
}

---

Validator

A validation rule (guardrail) applied to LLM responses.

Field	Type	Required	Description
type	string	Yes	Validation type. One of: "banned_words", "max_length", "min_length", "regex_match", "json_schema", "sentiment", "toxicity", "pii_detection", "custom".
enabled	boolean	Yes	Whether this validator is active.
fail_on_violation	boolean	No	If true, violations cause an error. Default: false.
params	object	No	Validator-specific parameters (e.g., word lists, character limits).

"validators": [
  {
    "type": "banned_words",
    "enabled": true,
    "fail_on_violation": true,
    "params": {
      "words": ["impossible", "can't help"]
    }
  },
  {
    "type": "pii_detection",
    "enabled": true,
    "fail_on_violation": true
  }
]

---

Tested Model

Documents which models have been tested with a prompt and their performance metrics.

Field	Type	Required	Description
provider	string	Yes	LLM provider name (e.g., "openai", "anthropic").
model	string	Yes	Specific model identifier (e.g., "gpt-4", "claude-3-opus").
date	string	Yes	Date tested in YYYY-MM-DD format.
success_rate	number	No	Success rate from test runs (0–1).
avg_tokens	number	No	Average tokens used per response.
avg_cost	number	No	Average cost per execution in USD.
avg_latency_ms	number	No	Average response latency in milliseconds.
notes	string	No	Additional observations about model performance.

---

Model Override

Model-specific template modifications. Allows customizing prompts for specific models without changing the base template.

Field	Type	Required	Description
system_template_prefix	string	No	Text prepended to the system template for this model.
system_template_suffix	string	No	Text appended to the system template for this model.
system_template	string	No	Complete replacement system template (overrides the base template entirely).
parameters	Parameters	No	Model-specific parameter overrides.

"model_overrides": {
  "claude-3-opus": {
    "system_template_prefix": "<thinking>\n",
    "parameters": { "temperature": 0.5 }
  }
}

---

Pipeline Config

Pipeline configuration defining processing stages and middleware.

Field	Type	Required	Description
stages	string[]	Yes	Ordered list of pipeline stages (e.g., ["template", "provider", "validator"]).
middleware	MiddlewareConfig[]	No	Middleware components applied in order.

Middleware Config

Field	Type	Required	Description
type	string	Yes	Middleware type identifier (e.g., "template", "provider", "validator").
config	object	No	Type-specific configuration.

---

Metadata

Optional pack-level metadata for categorization and discovery.

Field	Type	Required	Description
domain	string	No	Domain or category (e.g., "customer-service", "healthcare").
language	string	No	Primary language code (ISO 639-1, e.g., "en"). Pattern: ^[a-z]{2}$.
tags	string[]	No	Tags for categorization and discovery.
cost_estimate	object	No	Cost estimation with min_cost_usd, max_cost_usd, and avg_cost_usd.

---

Compilation

Compiler-generated information about when and how the pack was built.

Field	Type	Required	Description
compiled_with	string	Yes	Version of the packc compiler (e.g., "packc-v0.1.0").
created_at	string	Yes	ISO 8601 timestamp when the pack was compiled.
schema	string	Yes	Pack format schema version (e.g., "v1").
source	string	No	Source configuration file path.

---

Fragments

Fragments are shared, reusable template text blocks defined at the pack level. They are simple string values keyed by name.

"fragments": {
  "customer_context": "Customer: {{customer_name}}\nAccount Type: {{account_type}}",
  "greeting": "Hello! How can I help you today?",
  "escalation_notice": "I'm going to connect you with a specialist."
}

Prompts reference fragments in their system_template using template syntax: {{fragments.customer_context}}.

---

Data Types

Supported Variable Types

• string – Text data
• number – Numeric values (integers and floats)
• boolean – True/false values
• array – Ordered lists of values
• object – Key-value maps

Template Variables

Variables in templates use the syntax defined in template_engine.syntax. With the default {{variable}} syntax:

{{variable_name}}

Fragments are referenced similarly:

{{fragments.fragment_name}}