PromptG Specification

An open standard JSON format for prompts, templates, and prompt packs

Overview

PromptG defines a standardized JSON format for storing, versioning, and sharing prompts, templates, and prompt packs. This specification enables tool-agnostic prompt management with support for variables, metadata, and extensibility.

Includes JSON Schemas, conformance tests, and a standardized .promptg/ on-disk layout.

Design principles:

• Simple: Core format is minimal and portable
• Extensible: x-* fields allow tool-specific metadata
• Interoperable: Works with any JSON Schema validator
• Local-first: No cloud dependencies required

Quick Links

• Specification - Normative specification (RFC 2119)
• File Store Layout - Standard .promptg/ on-disk layout
• JSON Schemas - Machine-readable schemas
• Conformance Tests - Validation fixtures for implementations
• Examples - Human-friendly examples
• Implementation Guide - How to implement PromptG
• Contributing - How to contribute

Ecosystem

• You are in promptg/spec: the canonical PromptG standard (spec text, schemas, conformance tests).
• Reference implementation: https://github.com/promptg/cli (CLI + UI).
• Starter packs: https://github.com/promptg/starter-packs
• Website: https://promptg.io (landing page, hosted schemas, pack mirror).

Routing:

• Spec/schema issues: https://github.com/promptg/spec/issues
• CLI bugs/features: https://github.com/promptg/cli/issues

PromptG documents use schemaVersion: "1".

Document Types

Prompt (kind: "prompt")

A ready-to-use prompt instance.

{
  "kind": "prompt",
  "schemaVersion": "1",
  "name": "code-review",
  "content": "Review this {{language}} code for {{focus}}"
}

Template (kind: "template")

A reusable blueprint for creating prompts.

{
  "kind": "template",
  "schemaVersion": "1",
  "name": "pr-review",
  "displayName": "PR Review",
  "description": "Review a pull request diff",
  "prompt": {
    "kind": "prompt",
    "schemaVersion": "1",
    "name": "pr-review",
    "content": "Review this PR: {{diff}}"
  }
}

Pack (kind: "pack")

A versioned bundle of prompts and templates.

{
  "kind": "pack",
  "schemaVersion": "1",
  "name": "dev-essentials",
  "version": "1.0.0",
  "templates": [...]
}

JSON Schemas

All formats have JSON schemas for validation:

• prompt.schema.json
• template.schema.json
• pack.schema.json

Schema URLs:

• https://promptg.io/schemas/v1/prompt.schema.json
• https://promptg.io/schemas/v1/template.schema.json
• https://promptg.io/schemas/v1/pack.schema.json

Implementations

Reference Implementation

• @promptg/cli - TypeScript CLI (official)

Features

Variable Interpolation

{
  "content": "Review {{language}} code for {{focus}}",
  "defaults": {
    "language": "TypeScript",
    "focus": "security"
  }
}

Variables use {{variableName}} syntax. Missing variables are left unchanged.

To emit a literal placeholder, use {{!name}} which renders as literal {{name}} (and is ignored as a variable occurrence during rendering).

Extensibility

{
  "kind": "prompt",
  "x-my-tool-metadata": { "customField": "value" },
  "x-promptg-interactive": {
    "language": {
      "question": "What programming language?",
      "required": true
    }
  }
}

Use x-* fields for tool-specific extensions. The x-promptg-* namespace is reserved.

Standard Extensions (Stable in v1.0)

• x-promptg-interactive - Interactive prompting metadata
• x-promptg-time - Timestamp metadata

Validation

Node.js: CI runs on Node 20; Node 20+ is recommended for running this repo's validation and test scripts.

Node.js (ajv)

npm install ajv ajv-formats

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv);

const schema = await fetch('https://promptg.io/schemas/v1/prompt.schema.json').then((r) =>
  r.json()
);

const validate = ajv.compile(schema);
const valid = validate(promptData);

if (!valid) console.error(validate.errors);

Python (jsonschema)

pip install jsonschema requests

import json
import requests
from jsonschema import validate

schema = requests.get('https://promptg.io/schemas/v1/prompt.schema.json').json()
validate(instance=prompt_data, schema=schema)

Repository Structure

.
|---- spec/                    # Normative specification
|   `---- promptg-spec.md
|---- schemas/v1/              # JSON Schemas
|   |---- prompt.schema.json
|   |---- template.schema.json
|   `---- pack.schema.json
|---- examples/                # Human-friendly examples
|   |---- prompts/
|   |---- templates/
|   `---- packs/
|---- conformance/             # Conformance test suite
|   |---- valid/               # Valid test cases
|   |---- invalid/             # Invalid test cases (should fail)
|   `---- semantics/           # Semantic test vectors (render/extract/instantiate)
|---- docs/                    # Supporting documentation
|   `---- guide.md
`---- .github/workflows/       # CI validation

Contributing

We welcome contributions! See CONTRIBUTING.md for:

• How to propose schema changes
• RFC process for major changes
• Code of conduct

Governance

See GOVERNANCE.md for:

• Maintainer structure
• Decision-making process
• Versioning policy

License

Apache License 2.0 - See LICENSE for details.

---

PromptG: Prompts as code. Versioned, shareable, standard.