Skip to content

PIDL v0.2.0 Release Notes

Release Date: 2025-04-18

This release adds significant new features to PIDL including annotations, alternatives, conditions, notes, nested phases, and the D2 diagram format.

Highlights

  • Add annotations, alternatives, conditions, notes, and nested phases to PIDL
  • Enhanced renderers with support for alt/else blocks, opt conditionals, and nested phase visualization
  • New D2 diagram format with sequence, flow, and architecture rendering styles
  • Comprehensive validation for phase hierarchies and new flow features

What's New

D2 Diagram Renderer

A new diagram format with three rendering styles:

  • d2 / d2-sequence - Sequence diagram style
  • d2-flow - Data flow diagram style
  • d2-arch - Architecture diagram style
pidl generate -f d2 oauth2_pkce
pidl generate -f d2-arch mcp_tool_invocation

Flow Extensions

New fields on Flow for richer protocol descriptions:

Field Description
condition Conditional execution (renders as opt block)
note Visible note in diagram
annotations Typed metadata (security, performance, etc.)
alternatives Alternative/error paths (renders as alt/else block)

Annotation Types

Six built-in annotation types for flow metadata:

Type Use Case
security Security considerations
performance Performance notes
deprecated Deprecation warnings
info General information
warning Warning messages
error Error conditions

Nested Phases

Phases can now have parent references for hierarchical grouping:

{
  "phases": [
    {"id": "auth", "name": "Authentication"},
    {"id": "mfa", "name": "MFA Challenge", "parent": "auth"}
  ]
}

Alternative Paths

Model error handling and branching flows:

{
  "from": "client",
  "to": "server",
  "action": "request",
  "alternatives": [
    {
      "condition": "error",
      "flows": [
        {"from": "server", "to": "client", "action": "error_response"}
      ]
    }
  ]
}

Renderer Enhancements

Mermaid

  • opt blocks for conditional flows
  • alt/else blocks for alternatives
  • note right of for flow notes and annotations
  • Colored rect blocks for nested phases

PlantUML

  • opt/alt/else blocks for conditionals and alternatives
  • Colored box containers for nested phases
  • OpenIconic icons for annotation prefixes

D2

  • Condition label prefixes
  • Grouped alternatives
  • Nested phase groups with hierarchy support

Graphviz DOT

  • Condition edge labels
  • Alternative edges with distinct styling

Validation

New validation rules:

  • Phase parent reference validation with cycle detection
  • Annotation type and text validation
  • Alternative condition and flows validation
  • Entity reference validation in alternative flows

Migration

Existing PIDL files remain compatible. New fields are optional.

Documentation

License

MIT License