PromptDSL Specification

PromptDSL (Prompt Domain-Specific Language) is the foundational schema language of PromptHub. It allows developers to define prompts not as ad hoc text strings, but as formally structured, machine-readable semantic contracts. Each PromptDSL module encapsulates a unit of prompt logic, including its inputs, parameters, dependencies, template structure, and outputs.

PromptDSL Visual Example

The diagram below illustrates how a PromptDSL module transforms from a raw prompt into a structured, executable asset:

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  【TRADITIONAL PROMPT】                                                      │
│  Analyze the following text and extract key people, places, and events      │
│  in JSON format                                                             │
│                                                                             │
│                              │                                              │
│                              │  STANDARDIZATION                             │
│                              ▼                                              │
│                                                                             │
│  【PROMPTDSL STRUCTURED MODULE】                                             │
│  ┌─────────────────────────────────────────────────────────────┐            │
│  │ {                                                           │            │
│  │   "id": "entity_extractor_v1.2",                           │            │
│  │   "name": "Entity Extractor",                              │            │
│  │   "description": "Extracts entities from text",            │            │
│  │   "author": "0x7F9a...3B2e",                               │            │
│  │   "version": "1.2.0",                                      │            │
│  │   "inputs": {                                              │            │
│  │     "text": { "type": "string", "required": true },        │            │
│  │     "entity_types": {                                      │            │
│  │       "type": "array",                                     │            │
│  │       "default": ["person", "location", "event"]           │            │
│  │     }                                                      │            │
│  │   },                                                       │            │
│  │   "template": "Analyze the following text and extract      │            │
│  │               {{entity_types}} entities. Return in JSON:   │            │
│  │               {{text}}",                                   │            │
│  │   "output_schema": {                                       │            │
│  │     "entities": {                                          │            │
│  │       "type": "object",                                    │            │
│  │       "properties": { ... }                                │            │
│  │     }                                                      │            │
│  │   },                                                       │            │
│  │   "dependencies": ["text_cleaner_v1"]                      │            │
│  │ }                                                          │            │
│  └─────────────────────────────────────────────────────────────┘            │
│                                                                             │
│                                                                             │
│                              │                                              │
│                              │  ON-CHAIN REGISTRATION                       │
│                              ▼                                              │
│                                                                             │
│  【ON-CHAIN ASSET】                                                         │
│  ┌─────────────────────────────────────────────────────────────┐            │
│  │ PromptVault                                                 │            │
│  │ • Module ID: entity_extractor_v1.2                          │            │
│  │ • IPFS Link: ipfs://Qm...                                   │            │
│  │ • Creator: 0x7F9a...3B2e                                    │            │
│  │ • License: CC-BY-SA                                         │            │
│  │ • Usage Fee: 0.01 $PHUB/call                                │            │
│  │ • Dependency Tree: [text_cleaner_v1]                        │            │
│  │ • Version History: v1.0 -> v1.1 -> v1.2                     │            │
│  └─────────────────────────────────────────────────────────────┘            │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

PromptDSL is designed to be:

• Deterministic: each prompt version yields reproducible results

• Composable: prompts can embed or call other prompts

• Modular: prompts can be assembled into larger DAG workflows

• Tokenizable: each prompt can be bound to ownership, licensing, and economics

1. PromptDSL Structure

A PromptDSL module is defined using a JSON-based schema with the following required and optional fields:

{
  "id": "extract_contract_clauses",
  "name": "Legal Contract Clause Extractor",
  "description": "Extracts key legal clauses from a commercial agreement",
  "version": "1.2.4",
  "author": "0xabc123...",
  "license": "CC-BY-SA-4.0",
  "inputs": {
    "document": {
      "type": "string",
      "required": true,
      "description": "The full text of the legal document"
    },
    "clause_types": {
      "type": "array",
      "items": { "type": "string" },
      "default": ["Termination", "Payment", "Confidentiality"],
      "description": "Types of clauses to extract"
    },
    "max_length": {
      "type": "number",
      "default": 200,
      "description": "Maximum length for each extracted clause"
    }
  },
  "template": "You are a legal expert analyzing contracts. Please extract the following clauses: {{clause_types}} from this document:\n\n{{document}}\n\nFor each clause, provide the section number, the relevant text (max {{max_length}} characters), and a brief explanation of its implications.",
  "output_schema": {
    "type": "object",
    "properties": {
      "clauses": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "type": { "type": "string" },
            "section": { "type": "string" },
            "text": { "type": "string" },
            "explanation": { "type": "string" }
          },
          "required": ["type", "text"]
        }
      }
    }
  },
  "dependencies": ["legal_terms_normalizer_v1"],
  "execution_settings": {
    "temperature": 0.2,
    "top_p": 0.9,
    "max_tokens": 1500
  },
  "tags": ["legal", "contracts", "clause-extraction"],
  "models": ["gpt-4", "claude-2", "mistral-large"]
}

Field descriptions:

Field	Type	Required	Description
id	String	Yes	Unique identifier for the prompt module
name	String	Yes	Human-readable name
description	String	Yes	Brief explanation of functionality
version	String	Yes	Semantic version (follows semver)
author	String	Yes	Creator's wallet address
license	String	Yes	License identifier (e.g., "MIT", "CC-BY-SA-4.0")
inputs	Object	Yes	Schema of input parameters
template	String	Yes	Template with variable placeholders
output_schema	Object	Yes	JSON Schema for expected output
dependencies	Array	No	Other prompt modules required
execution_settings	Object	No	Model-specific parameters
tags	Array	No	Categorical tags for discovery
models	Array	No	Compatible model providers

2. Input Parameter Specification

Each input parameter must define its data type and can include additional constraints:

interface InputParameter {
  type: "string" | "number" | "boolean" | "array" | "object";
  required?: boolean;        // Default is false
  default?: any;             // Default value if not provided
  description?: string;      // Human-readable description
  
  // Type-specific constraints
  // For strings:
  minLength?: number;        // Minimum length
  maxLength?: number;        // Maximum length
  pattern?: string;          // Regex pattern
  enum?: string[];           // Limited value set
  
  // For numbers:
  minimum?: number;          // Minimum value
  maximum?: number;          // Maximum value
  
  // For arrays:
  items?: InputParameter;    // Schema for array items
  minItems?: number;         // Minimum items
  maxItems?: number;         // Maximum items
  
  // For objects:
  properties?: Record<string, InputParameter>; // Object properties
  required?: string[];       // Required properties
}

3. Template Syntax and Context Injection

PromptDSL supports a rich templating syntax for parameter injection:

// Basic variable interpolation
{{variable_name}}

// Conditional sections
{{#if condition}}Text for true condition{{/if}}
{{#if condition}}Text for true condition{{else}}Text for false condition{{/else}}

// Iteration/loops
{{#each items}}
  Item: {{this}}
{{/each}}

// Formatting helpers
{{uppercase variable}}
{{lowercase variable}}
{{json variable}}

// Module references/composition
{{module "module_id@version" input1="value" input2=variable}}

This powerful templating system allows for dynamic content generation based on input parameters and conditional logic.

4. Embedding & Composition

PromptDSL supports modular composition through direct module references. This enables developers to create reusable utility prompts and compose complex chains from simple modules:

"template": "First, let's normalize the input text: {{module 'text_normalizer_v1' text=document}}\n\nNow, let's extract key information: {{module 'entity_extractor_v2' text=normalized_text entity_types=target_entities}}"

When executed, each referenced module's output becomes available to subsequent template sections, allowing for multi-step processing within a single prompt definition.

5. PromptDSL Validation & Compilation Process

The PromptDSL compilation pipeline consists of several stages:

1. Schema Validation: The DSL document is validated against the PromptDSL JSON Schema to ensure all required fields are present and correctly formatted.

2. Dependency Resolution: All referenced modules are resolved, and a dependency graph is constructed to ensure all requirements are satisfied.

3. Template Parsing: The template string is parsed into an abstract syntax tree (AST) that identifies all variable references, conditionals, loops, and module invocations.

4. Output Schema Validation: The output schema is checked for validity against JSON Schema standards.

5. Optimization: The compiled template is optimized for efficient execution, including pre-computation of static sections and caching of repeated expressions.

6. Serialization: The validated and optimized prompt module is serialized to a canonical format suitable for on-chain storage.

7. IPFS Pinning: The complete PromptDSL definition is pinned to IPFS for decentralized storage and content-addressed retrieval.

8. On-Chain Registration: A reference to the IPFS content hash, along with key metadata, is registered in PromptVault for verification and discovery.

6. Example Use Cases for PromptDSL

Enterprise Document Processing Pipeline:

{
  "id": "invoice_processor_v1",
  "name": "Invoice Processor",
  "inputs": {
    "invoice_text": { "type": "string", "required": true },
    "company_name": { "type": "string", "required": true }
  },
  "template": "Extract the following information from this {{company_name}} invoice:\n\n{{invoice_text}}\n\nProvide: invoice number, date, total amount, line items, and tax.",
  "output_schema": { /* Schema for structured invoice data */ }
}

Agent Reasoning Module:

{
  "id": "reasoning_chain_v2",
  "name": "Step-by-Step Reasoning",
  "inputs": {
    "problem": { "type": "string", "required": true },
    "reasoning_steps": { "type": "number", "default": 3 }
  },
  "template": "Solve this problem step-by-step using {{reasoning_steps}} clear reasoning steps:\n\n{{problem}}\n\nThink carefully and show your work.",
  "output_schema": {
    "type": "object",
    "properties": {
      "steps": { "type": "array", "items": { "type": "string" } },
      "conclusion": { "type": "string" }
    }
  }
}

Multi-Modal Prompt:

{
  "id": "image_analyzer_v1",
  "name": "Image Content Analyzer",
  "inputs": {
    "image": { "type": "image_url", "required": true },
    "analysis_type": { "type": "string", "enum": ["objects", "sentiment", "text", "composition"], "default": "objects" }
  },
  "template": "Analyze this image and describe all {{analysis_type}} visible in it.\n\n[IMAGE: {{image}}]",
  "output_schema": { /* Schema for image analysis results */ }
}

PromptDSL turns prompt authoring into software engineering—structured, composable, testable, and deployable across decentralized AI infrastructures.