PIDL

Protocol Interaction Description Language - A JSON-based DSL for describing protocol choreography that compiles to diagrams.

PIDL models protocols as directed interaction graphs between entities, enabling generation of sequence diagrams, data flow diagrams, and other visualizations. It's designed for protocols where the primary concern is "who talks to whom, in what order" rather than message schemas or transport details.

Features

• 📋 JSON-based DSL for describing protocol flows
• 🎨 Multiple output formats: PlantUML, Mermaid, Graphviz DOT, D2
• 📚 Built-in examples: OAuth 2.0, PKCE, OIDC, MCP, A2A
• ⌨️ CLI tool for validation and diagram generation
• 📦 Go library for programmatic use
• 🔀 Conditional flows with condition field for when clauses
• 🔄 Alternative paths with alternatives for error handling and branching
• 📝 Annotations with typed notes (security, performance, deprecated, etc.)
• 📊 Nested phases with parent hierarchy support

Installation

go install github.com/grokify/pidl/cmd/pidl@latest

Or clone and build:

git clone https://github.com/grokify/pidl.git
cd pidl
go build -o pidl ./cmd/pidl

Quick Start

List available examples

pidl examples

Generate a diagram from an example

# PlantUML sequence diagram
pidl generate oauth2_authorization_code

# Mermaid sequence diagram
pidl generate -f mermaid oauth2_pkce

# Graphviz DOT data flow diagram
pidl generate -f dot mcp_tool_invocation

# D2 sequence diagram
pidl generate -f d2 oauth2_pkce

# D2 data flow diagram
pidl generate -f d2-flow oauth2_pkce

# D2 architecture diagram
pidl generate -f d2-arch oauth2_pkce

Create a new protocol file

# Create from scratch
pidl init my-protocol.json

# Copy from an example
pidl init -from oauth2_authorization_code my-oauth.json

Validate protocol files

pidl validate my-protocol.json
pidl validate *.json

PIDL Format

A PIDL document is a JSON file with three main sections:

{
  "protocol": {
    "id": "my-protocol",
    "name": "My Protocol",
    "version": "1.0",
    "description": "A sample protocol",
    "category": "auth"
  },
  "entities": [
    {"id": "client", "name": "Client", "type": "client"},
    {"id": "server", "name": "Server", "type": "server"}
  ],
  "phases": [
    {"id": "main", "name": "Main Flow"},
    {"id": "error_handling", "name": "Error Handling", "parent": "main"}
  ],
  "flows": [
    {
      "from": "client",
      "to": "server",
      "action": "request",
      "label": "Request",
      "mode": "request",
      "phase": "main",
      "condition": "token_valid",
      "note": "Requires valid token",
      "annotations": [
        {"type": "security", "text": "Validate token signature"}
      ],
      "alternatives": [
        {
          "condition": "token_expired",
          "flows": [
            {"from": "server", "to": "client", "action": "refresh_required", "mode": "response"}
          ]
        }
      ]
    },
    {"from": "server", "to": "client", "action": "response", "label": "Response", "mode": "response", "phase": "main"}
  ]
}

Entity Types

Type	Description
client	Application or service initiating requests
authorization_server	Issues tokens and handles authentication
resource_server	Hosts protected resources
user	Human actor
browser	User agent / web browser
agent	AI/LLM agent
tool_server	Exposes tools via protocol (MCP)
delegated_agent	Agent receiving delegated tasks (A2A)

Flow Modes

Mode	Description	Arrow Style
request	Synchronous request	Solid ->
response	Synchronous response	Dashed -->
redirect	HTTP redirect	Solid with annotation
callback	Callback/webhook	Solid with annotation
interactive	Human interaction	Solid
event	Asynchronous event	Dashed
tool_call	Tool invocation (MCP)	Solid with annotation
tool_result	Tool result (MCP)	Dashed with annotation

Flow Extensions

Field	Description
condition	Conditional execution clause (renders as opt block)
note	Visible note displayed on diagram
annotations	Array of typed annotations for tooling
alternatives	Alternative paths (renders as alt/else blocks)

Annotation Types

Type	Description
security	Security-related notes
performance	Performance considerations
deprecated	Deprecated functionality
info	General information
warning	Warning messages
error	Error conditions

Nested Phases

Phases support hierarchical nesting via the parent field:

{
  "phases": [
    {"id": "auth", "name": "Authentication"},
    {"id": "mfa", "name": "Multi-Factor Auth", "parent": "auth"},
    {"id": "token", "name": "Token Exchange", "parent": "auth"}
  ]
}

CLI Reference

pidl <command> [options] [arguments]

Commands:
  validate   Validate PIDL JSON files
  generate   Generate diagrams from PIDL files
  examples   List or show built-in examples
  init       Create a new PIDL file from template
  version    Print version information
  help       Show help message

validate

pidl validate [options] <file> [file...]

Options:
  -q    Quiet mode (only show errors)

generate

pidl generate [options] <file>

Options:
  -f string   Output format: plantuml, mermaid, dot, d2, d2-flow, d2-arch (default "plantuml")
  -o string   Output file (default: stdout)

D2 formats:

• d2 - Sequence diagram
• d2-flow - Data flow diagram with entity shapes
• d2-arch - Architecture diagram with entities grouped by type

examples

pidl examples [options] [name]

Options:
  -json   Show example JSON content

init

pidl init [options] <filename>

Options:
  -name string   Protocol name
  -from string   Initialize from example

Go Library

import (
    "github.com/grokify/pidl"
    "github.com/grokify/pidl/render"
    "github.com/grokify/pidl/examples"
)

// Parse a PIDL file
p, err := pidl.ParseFile("protocol.json")

// Validate
if errs := p.Validate(); errs.HasErrors() {
    log.Fatal(errs)
}

// Generate PlantUML
diagram, err := render.RenderString(render.FormatPlantUML, p)

// Use built-in examples
names := examples.List()
oauth, err := examples.GetProtocol("oauth2_authorization_code")

// Create a new protocol
p := pidl.NewMinimalProtocol("my-protocol", "My Protocol")
pidl.WriteProtocolFile("output.json", p)

Built-in Examples

Example	Protocol
oauth2_authorization_code	OAuth 2.0 Authorization Code Flow
oauth2_pkce	OAuth 2.0 with PKCE
oidc_authentication	OpenID Connect Authentication
mcp_tool_invocation	MCP Tool Invocation
a2a_agent_delegation	A2A Agent Delegation

Target Protocols

PIDL is designed for describing:

• Authentication/Authorization: OAuth 2.0, OpenID Connect, SAML
• Agent Protocols: MCP (Model Context Protocol), A2A (Agent-to-Agent)
• API Flows: Multi-party API choreography

Documentation

• Specification - Full language specification
• JSON Schema - Schema for validation

License

MIT License - see LICENSE for details.