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.

• 📋 JSON-based DSL for describing protocol flows
• 🗂️ Scenarios: one file holds a protocol's roles and an ordered list of journeys, with shared fragments drawn as labeled boxes
• 🔢 Consistent ordering: roles, scenarios and steps follow the file's order in every diagram, table and outline
• 📑 Overview outputs: roles-by-scenario matrix, token table, and an ordered outline for guides and slide decks
• 🖥️ Walkthrough viewer: a self-contained HTML page that steps through each scenario, highlighting the active roles and message and showing example requests, responses and decoded tokens
• 🌍 Embeddable viewer: @grokify/pidl-viewer loads from a CDN with one script tag and shows any walkthrough file, inline or by URL
• 🧾 Walkthrough format: pidl-walkthrough/v1, the processed form viewers read, with a JSON Schema and TypeScript types
• 💻 Code samples and cURL: each request as HTTP, a generated curl command, or SDK code taken from tested source files; each implementation can keep its samples in its own sample set, so the protocol document names none
• 🎙️ Narration: spoken text by language, scenario briefings and pronunciations, for audio and narrated video
• 🔭 Observed runs: a real system's run beside the walkthrough's examples, matched to its steps by rules in the document and a deployment binding, with tokens decoded and raw values masked
• 📮 Postman collections: a runnable collection per protocol, with values chained between requests, checks on every response, and signed requests sent through a signing proxy
• 🎨 Multiple output formats: PlantUML, Mermaid, Graphviz DOT, D2, SVG
• 🎬 Animated SVG with CSS flow visualizations and moving dots
• 🌐 Network boundary diagrams for trust zone visualization
• 🎭 SVG templates: default, minimal, sketch, blueprint, dark, high-contrast
• ♿ Accessibility: WCAG AA compliant high-contrast template
• 📦 Phase boxes: Visual grouping of flows by phase with color-coded depth
• 🔀 Alternative badges: ALT indicators on flows with alternative paths
• ✨ Interactive SVG: Hover effects on participants, messages, and flow dots
• 💫 Animation effects: Pulse and glow for error/warning/highlight presets
• 📚 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
• 🔄 State model with entity states and state transitions
• 📈 State diagrams via Mermaid stateDiagram-v2 output
• 🔐 Security annotations with requirements (token, encryption, mTLS, signature)
• 🛡️ Trust levels for entity classification (trusted, semi_trusted, untrusted, authoritative)
• 🎫 Token definitions with issuer, audience, and binding
• 🔄 Protocol composition with imports and inheritance
• ▶️ Protocol simulation with state tracking and execution traces
• 🔍 Protocol comparison (diff) for change detection
• 🐛 Interactive debugger for step-through protocol execution
• 🛡️ Security analysis with built-in attack surface detection rules
• 🔎 Flow verification provenance with evidentiary tiers (reported/corroborated/reproduced) for incident attack-flows, renderer badges, and an analyzer rule
• 🔄 Process specifications for data pipelines and AI workflows
• 📊 Infographic renderer for LinkedIn and datasheet visuals
• 📈 Data lineage tracking for tracing data flow through process steps
• ⚡ Parallel execution modeling with fork/join, race, and scatter/gather patterns
• 💰 Cost tracking for LLM tokens, API calls, and time-based pricing
• 🔌 Workflow exports to Temporal (Go), Prefect (Python), and BPMN 2.0
• 🔧 IDE integration: VS Code extension with syntax highlighting and preview
• 🚀 CI/CD integration: GitHub Action for validation in pipelines
• 📖 MkDocs plugin for rendering PIDL diagrams in documentation

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

pidl examples

# 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

# SVG sequence diagram
pidl generate -f svg oauth2_pkce

# Animated SVG with flow dots
pidl generate -f svg-animated --theme=dark oauth2_pkce

# SVG with template
pidl generate -f svg --template=sketch oauth2_pkce

# Network boundary diagram
pidl generate -f svg-network oauth2_pkce

# Mermaid state diagram (for entities with states)
pidl generate -f mermaid-state oauth2_with_states

# State diagram for specific entity
pidl generate -f mermaid-state --entity=client oauth2_with_states

# Infographic for social media
pidl generate -f infographic --size=linkedin-square --title="OAuth Flow" oauth2_pkce

# Compact infographic for datasheets
pidl generate -f infographic --size=datasheet-tile --theme=minimal etl_pipeline

# Create from scratch
pidl init my-protocol.json

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

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

PIDL supports process specifications for modeling data pipelines and AI workflows. Process specs use step types to classify processing stages:

{
  "protocol": {
    "id": "etl-pipeline",
    "name": "ETL Pipeline",
    "kind": "process"
  },
  "entities": [
    {"id": "extract", "name": "Extract", "type": "server", "step_type": "deterministic"},
    {"id": "transform", "name": "Transform", "type": "server", "step_type": "llm"},
    {"id": "review", "name": "Human Review", "type": "server", "step_type": "human"},
    {"id": "load", "name": "Load", "type": "server", "step_type": "external"}
  ],
  "flows": [
    {"from": "extract", "to": "transform", "action": "send"},
    {"from": "transform", "to": "review", "action": "review"},
    {"from": "review", "to": "load", "action": "approve"}
  ]
}

# SVG with step type styling
pidl generate -f svg etl_pipeline

# Infographic for LinkedIn
pidl generate -f infographic --size=linkedin-square --title="ETL Pipeline" etl_pipeline

# Security analysis with process-aware rules
pidl analyze etl_pipeline

See Process Guide for detailed documentation.

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"}
  ]
}

PIDL models protocols as directed graphs where nodes are entities/components and edges are interactions/relationships.

Entity types are classified as client-side (initiators) or server-side (responders):

Entities can implement protocol-specific roles:

Components group entities into logical deployment units:

PIDL supports two types of edges: protocol flows (sequential actions) and trust relationships (static trust).

Flows are ordered interactions between entities that define protocol choreography. They are the primary edge type and generate sequence diagrams.

Protocols define the interaction patterns between entities:

Trust relationships define how entities establish trust:

Credentials exchanged in trust relationships:

PIDL generates multiple diagram types from the same protocol definition:

# Sequence diagrams (from flows)
pidl generate -f plantuml protocol.json    # PlantUML
pidl generate -f mermaid protocol.json     # Mermaid
pidl generate -f svg protocol.json         # SVG
pidl generate -f svg-animated protocol.json # Animated SVG

# Data flow diagrams (from flows)
pidl generate -f dot protocol.json         # Graphviz DOT
pidl generate -f d2-flow protocol.json     # D2 flow

# Architecture diagrams (from entities + flows)
pidl generate -f d2-arch protocol.json     # D2 architecture

# Network diagrams (from entities + trust levels)
pidl generate -f svg-network protocol.json # Network boundaries

# State diagrams (from entity states + flow mutations)
pidl generate -f mermaid-state protocol.json           # All entities
pidl generate -f mermaid-state --entity=client protocol.json  # Single entity

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"}
  ]
}

Entities can define states to track their lifecycle:

{
  "entities": [
    {
      "id": "client",
      "name": "Client",
      "type": "client",
      "states": [
        {"id": "idle", "name": "Idle", "initial": true},
        {"id": "authenticated", "name": "Authenticated"},
        {"id": "error", "name": "Error", "final": true}
      ]
    }
  ]
}

Flows can trigger state changes via the sets field:

{
  "flows": [
    {
      "from": "client",
      "to": "server",
      "action": "login",
      "sets": [
        {"entity": "client", "from": "idle", "to": "authenticated"}
      ]
    }
  ]
}

Entities can be assigned trust levels to indicate their security posture:

{
  "entities": [
    {
      "id": "client",
      "name": "Client",
      "type": "client",
      "trust_level": "semi_trusted"
    }
  ]
}

Trust levels are used by svg-network format to automatically infer network boundaries.

Flows can specify security requirements:

{
  "flows": [
    {
      "from": "client",
      "to": "server",
      "action": "api_request",
      "security": {
        "requires": ["token", "encryption"],
        "token": "access_token",
        "confidential": true,
        "description": "Bearer token required"
      }
    }
  ]
}

Protocols can define token types used in flows:

{
  "metadata": {
    "tokens": [
      {
        "id": "access_token",
        "name": "Access Token",
        "type": "jwt",
        "issuer": "auth_server",
        "audience": "resource_server",
        "binding": "bearer"
      }
    ]
  }
}

Flow security can also record signed_by (who signs the request), issues (tokens the flow delivers) and verifies (tokens the receiver checks), so pidl analyze can follow each token through a scenario.

pidl <command> [options] [arguments]

Commands:
  validate   Validate PIDL JSON files
  generate   Generate diagrams from PIDL files
  scenarios  List scenarios in a PIDL file, in output order
  samples    Resolve and check code samples from source repositories
  roles      List protocol roles
  components List deployment components
  trust      List trust relationships
  examples   List or show built-in examples
  init       Create a new PIDL file from template
  simulate   Run protocol simulation with state tracking
  diff       Compare two protocols and show differences
  debug      Interactive step-through protocol debugger
  analyze    Security analysis with attack surface detection
  resolve    Resolve protocol imports and inheritance
  version    Print version information
  help       Show help message

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

Options:
  -q    Quiet mode (only show errors)

pidl generate [options] <file>

Options:
  -f string         Output format (default "plantuml")
  -o string         Output file (default: stdout)
  --template        SVG template: default, minimal, sketch, blueprint, dark, high-contrast
  --template-dir    Path to custom SVG template directory
  --theme           SVG theme: light, dark, auto
  --boundary        Network boundary override (repeatable)
  --entity          Entity ID to filter (for mermaid-state format)
  --show-security   Show security annotations on flows (default true)
  --show-trust      Show trust levels and infer boundaries from trust (default true)
  --scenario        Scenario to render (files with scenarios)
  --expand          Show included fragments step by step instead of as boxes
  --all-scenarios   Render every main scenario to NN-<id><ext> in the -o directory
  --include-fragments  With --all-scenarios, also render fragments
  --observation     walkthrough-json and viewer: a run observed in a real system (pidl-observation/v1)
  --binding         With --observation: the deployment's binding (pidl-binding/v1)
  --scenarios       With --observation: scenario IDs to look for, in order (default: all but fragments)
  --from, --to      With --observation: match only exchanges in this RFC 3339 time range
  --raw             With --observation: keep raw tokens and signatures instead of masking them

Formats:

pidl observe import --from sandbox [-o <file>] <capture>

Converts a capture of a real run into an observation (pidl-observation/v1): sandbox reads the aauth-go sandbox's trace. Show it beside a document's steps with pidl generate -f viewer --observation <file> --binding <file> <document>.

pidl samples <resolve|check> [options] <file>

Options:
  --root <dir>       Directory holding repository checkouts at <root>/<repo> (default: $GOPATH/src)
  --lock <file>      A document's lock file (default: <file without .json>.samples.json)
  --repo-dir <dir>   Read every source from this checkout
  --protocol <file>  With a sample set, check every step address against this document

<file> is a document or a sample set (pidl-samples/v1). resolve records each sample's code and hash, in the document's lock file or in the set; check fails when a sample has fallen behind its source.

pidl examples [options] [name]

Options:
  -json   Show example JSON content

pidl init [options] <filename>

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

pidl simulate [options] <file>

Options:
  -steps int           Maximum steps to execute (0 = all)
  -v                   Verbose output with each step
  -json                Output trace as JSON
  --trace-format       Trace output format: text, json, svg, mermaid
  --trace-output       Write trace to file
  --show-states        Show entity states in trace
  --show-timings       Show timing information

pidl diff [options] <base-file> <new-file>

Options:
  -f, --format         Output format: text, json, markdown (default: text)
  -o, --output         Output file (default: stdout)
  --ignore-metadata    Ignore metadata differences
  -q, --quiet          Summary only

pidl debug <file>

Interactive Commands:
  step, s              Execute next flow
  continue, c          Run until breakpoint/completion
  break <idx> [cond]   Set breakpoint at flow index
  delete <idx>         Remove breakpoint
  breakpoints          List all breakpoints
  inspect              Show current state
  inspect entity <id>  Show entity details and state
  inspect flow <idx>   Show flow details
  list                 List flows with position marker
  set <entity> <state> Set entity state
  reset                Restart execution
  quit, q              Exit debugger

pidl analyze [options] <file>

Options:
  -f, --format         Output format: text, json, markdown (default: text)
  -o, --output         Output file (default: stdout)
  --min-severity       Minimum severity: critical, high, medium, low, info
  --category           Filter by category (repeatable)
  --fail-on            Exit with code 1 if risks at this severity
  -q, --quiet          Summary only

Built-in security rules:

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

// 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)

// Compare two protocols
diff := pidl.Compare(base, updated, pidl.DiffOptions{})
fmt.Println(diff.String())

// Run protocol simulation
executor := pidl.NewExecutor(p)
trace, err := executor.Execute()
fmt.Println(trace.String())

// Interactive debugging
session := pidl.NewDebugSession(p)
session.SetBreakpoint(2, "")
step, _ := session.Step()
state := session.Inspect()

// Security analysis
analysis := analyze.Analyze(p, analyze.DefaultAnalysisOptions())
fmt.Println(analysis.String())
if analysis.HasRisksAtOrAbove(analyze.SeverityHigh) {
    // handle high-severity risks
}

// Data lineage analysis
lineage := pidl.AnalyzeDataLineage(p)
upstream := lineage.GetUpstream("transform", "input")
impacted := lineage.GetImpactedEntities("extract")
sources := lineage.GetDataProvenance("load")

// Parallel execution analysis
graph := pidl.AnalyzeExecutionGraph(p)
canParallel := pidl.CanExecuteInParallel(p, "stepA", "stepB")
maxParallel := pidl.GetMaxParallelism(p)

// Cost tracking
costAnalysis := pidl.AnalyzeProcessCosts(p)
fmt.Printf("Estimated cost: $%.4f\n", costAnalysis.TotalEstimate.ExpectedCost)

// Workflow exports
import "github.com/grokify/pidl/export"
temporal := export.NewTemporalExporter()
goCode, _ := temporal.Export(p)
prefect := export.NewPrefectExporter()
pythonCode, _ := prefect.Export(p)
bpmn := export.NewBPMNExporter()
xml, _ := bpmn.Export(p)

PIDL is designed for describing:

• Authentication/Authorization: OAuth 2.0, OpenID Connect, SAML 2.0, WebAuthn/FIDO2
• Identity Management: SCIM provisioning, user lifecycle
• Agent Protocols: AAuth, MCP (Model Context Protocol), A2A (Agent-to-Agent)
• API Flows: Multi-party API choreography

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

MIT License - see LICENSE for details.