# 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: ```json { "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: ```typescript 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; // 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**: ```json { "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**: ```json { "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**: ```json { "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.