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:
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:
Schema Validation: The DSL document is validated against the PromptDSL JSON Schema to ensure all required fields are present and correctly formatted.
Dependency Resolution: All referenced modules are resolved, and a dependency graph is constructed to ensure all requirements are satisfied.
Template Parsing: The template string is parsed into an abstract syntax tree (AST) that identifies all variable references, conditionals, loops, and module invocations.
Output Schema Validation: The output schema is checked for validity against JSON Schema standards.
Optimization: The compiled template is optimized for efficient execution, including pre-computation of static sections and caching of repeated expressions.
Serialization: The validated and optimized prompt module is serialized to a canonical format suitable for on-chain storage.
IPFS Pinning: The complete PromptDSL definition is pinned to IPFS for decentralized storage and content-addressed retrieval.
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.
Last updated