PIDL v0.5.0 Release Notes

Release Date: 2026-07-12

This release introduces advanced process specification features, integrations, and new protocol examples. Major additions include data lineage tracking, parallel execution modeling, cost and latency budget tracking, JSON Schema validation, workflow engine exports, and integrations for MkDocs, GitHub Actions, and VS Code.

Highlights

• Process specifications for modeling workflows with step types and data ports
• Data lineage tracking for tracing data flow through process steps
• Parallel execution modeling with fork/join, race, and scatter/gather patterns
• Cost and latency budget tracking with SLI analysis
• JSON Schema validation for data ports with registry support
• Workflow engine exports for Temporal, Prefect, BPMN, and AWS Step Functions
• Infographic renderer with size presets and themes for social media
• MkDocs plugin for rendering PIDL diagrams in documentation
• GitHub Action for CI/CD validation
• VS Code extension with syntax highlighting and live preview
• New protocol examples: SAML 2.0, WebAuthn/FIDO2, SCIM

What's New

Data Lineage Tracking

Track data flow through process specifications with lineage analysis:

import "github.com/grokify/pidl"

// Analyze data lineage
lineage := pidl.AnalyzeDataLineage(protocol)

// Find upstream/downstream connections
upstream := lineage.GetUpstream("transform", "input")
downstream := lineage.GetDownstream("extract", "output")

// Impact analysis - what's affected if this entity changes?
impacted := lineage.GetImpactedEntities("transform")

// Data provenance - where does this entity's data come from?
sources := lineage.GetDataProvenance("load")

// Sensitive data path tracking
if lineage.HasSensitiveDataFlow() {
    for _, path := range lineage.SensitiveDataPaths {
        // Handle sensitive data paths
    }
}

Features:

• Automatic port-to-port connection inference
• Explicit data mappings via flow.data_mappings
• Sensitive data path tracking
• Impact analysis (downstream effects)
• Provenance analysis (upstream sources)

Parallel Execution Modeling

Model parallel execution patterns in process specifications:

{
  "entities": [
    {
      "id": "fork_point",
      "name": "Fork",
      "step_type": "parallel",
      "parallel": {
        "mode": "fork_join",
        "join_condition": "all",
        "branches": [
          {"id": "b1", "entity_id": "worker_1"},
          {"id": "b2", "entity_id": "worker_2"}
        ]
      }
    }
  ]
}

// Analyze execution graph
graph := pidl.AnalyzeExecutionGraph(protocol)

// Get execution stages (parallelizable groups)
for _, stage := range graph.Stages {
    fmt.Printf("Stage %s: %v\n", stage.ID, stage.Steps)
}

// Find critical path
fmt.Println("Critical path:", graph.CriticalPath)

// Check if two entities can run in parallel
if pidl.CanExecuteInParallel(protocol, "stepA", "stepB") {
    // Execute concurrently
}

// Get maximum parallelism
maxParallel := pidl.GetMaxParallelism(protocol)

Parallel modes:

Mode	Description
fork_join	Execute branches in parallel, wait for all
race	Execute branches in parallel, first wins
scatter	Distribute work across instances
gather	Collect results from parallel branches

Cost Tracking

Estimate and track execution costs for process specifications:

{
  "entities": [
    {
      "id": "llm_step",
      "step_type": "llm",
      "processing": {
        "cost_model": {
          "type": "token_based",
          "input_token_cost": 0.003,
          "output_token_cost": 0.015,
          "estimated_input_tokens": 1000,
          "estimated_output_tokens": 500,
          "cost_unit": "USD"
        }
      }
    }
  ]
}

// Analyze process costs
analysis := pidl.AnalyzeProcessCosts(protocol)

// Total estimated cost
fmt.Printf("Expected cost: $%.4f\n", analysis.TotalEstimate.ExpectedCost)

// Cost by step type
for stepType, cost := range analysis.CostByType {
    fmt.Printf("%s: $%.4f\n", stepType, cost)
}

// Calculate actual execution cost
metrics := pidl.ExecutionMetrics{
    InputTokens:  1500,
    OutputTokens: 750,
    Duration:     30 * time.Second,
}
actualCost := pidl.CalculateExecutionCost(entity, metrics)

Cost model types:

Type	Description
fixed	Fixed cost per execution
token_based	Cost based on input/output tokens
time_based	Cost based on execution duration
api_call	Cost per API call
hybrid	Combined cost factors

Latency Budget Tracking

Define timing SLIs (Service Level Indicators) for process steps:

{
  "entities": [
    {
      "id": "llm_step",
      "step_type": "llm",
      "processing": {
        "latency_budget": {
          "p50": "2s",
          "p95": "8s",
          "p99": "15s",
          "max": "30s",
          "variance_class": "high"
        }
      }
    }
  ]
}

// Analyze process latency
analysis := pidl.AnalyzeProcessLatency(protocol)

// Total latency estimates
fmt.Printf("P50: %s, P95: %s, P99: %s\n",
    analysis.TotalLatency.P50,
    analysis.TotalLatency.P95,
    analysis.TotalLatency.P99)

// Critical path latency
fmt.Printf("Critical path: %v\n", analysis.CriticalPath)
fmt.Printf("Critical path P50: %s\n", analysis.CriticalPathLatency.P50)

// Parallel savings
fmt.Printf("Parallel savings: %s\n", analysis.ParallelSavings)

// Budget violations
for _, v := range analysis.BudgetViolations {
    fmt.Printf("%s: %s exceeded (budget: %s, estimated: %s)\n",
        v.EntityID, v.Metric, v.Budget, v.Estimated)
}

// Measure actual execution
measurement := pidl.CalculateActualLatency(entity, 5*time.Second)
if measurement.ExceedsP95 {
    // Handle SLI violation
}

Variance classes:

Class	Description
low	Consistent, predictable latency (deterministic steps)
medium	Moderate variance (external APIs, tools)
high	High variance (LLM, human tasks)

JSON Schema Validation

Validate data port inputs and outputs against JSON Schema:

// Create schema registry
registry := pidl.NewSchemaRegistry()
registry.SetBasePath("./schemas")

// Load and cache schemas
schema, _ := registry.LoadSchema("user.schema.json")

// Validate data against schema
result := pidl.ValidateData(data, schema)
if !result.Valid {
    for _, err := range result.Errors {
        fmt.Printf("%s: %s\n", err.Path, err.Message)
    }
}

// Validate entity inputs
validator := pidl.NewPortSchemaValidator()
validator.SetBasePath("./schemas")

result, _ := validator.ValidateEntityInputs(entity, inputs)
if !result.Valid {
    fmt.Println(result.Error())
}

Supported validations:

• Type checking (string, number, integer, boolean, array, object, null)
• Required fields
• Enum constraints
• Min/max for numbers
• MinLength/maxLength for strings
• Nested object validation
• Array item validation

Workflow Engine Exports

Export PIDL process specifications to workflow orchestration platforms:

import "github.com/grokify/pidl/export"

// Export to Temporal (Go)
temporal := export.NewTemporalExporter()
goCode, _ := temporal.Export(protocol)

// Export to Prefect (Python)
prefect := export.NewPrefectExporter()
pythonCode, _ := prefect.Export(protocol)

// Export to BPMN 2.0 (XML)
bpmn := export.NewBPMNExporter()
xml, _ := bpmn.Export(protocol)

// Export to AWS Step Functions (Amazon States Language)
stepfn := export.NewStepFunctionsExporter()
asl, _ := stepfn.Export(protocol)

Supported platforms:

Platform	Language	Features
Temporal	Go	Workflow + activity stubs
Prefect	Python	Async/sync flows + tasks
BPMN 2.0	XML	Standard interchange format
AWS Step Functions	JSON	Amazon States Language with Bedrock/Lambda

Step type mapping for AWS Step Functions:

PIDL Step Type	AWS Resource
deterministic	Lambda invoke
llm	Bedrock invokeModel
human	Activity (with heartbeat)
external	HTTP invoke
tool	Lambda invoke

MkDocs Plugin

Render PIDL diagrams directly in MkDocs documentation:

# mkdocs.yml
plugins:
  - pidl:
      default_format: mermaid
      default_theme: bold

<!-- In your markdown -->
```pidl format=infographic theme=dark
{
    "id": "my-protocol",
    ...
}

```pidl file=protocols/oauth2.pidl.json format=mermaid

Installation:

pip install mkdocs-pidl

GitHub Action

Validate PIDL files in CI/CD pipelines:

- name: Validate PIDL files
  uses: grokify/pidl/integrations/github-action@main
  with:
    files: '**/*.pidl.json'
    security: 'true'

Outputs:

• valid: Whether all files passed
• file_count: Number of files validated
• errors: JSON array of validation errors

VS Code Extension

Full IDE support for PIDL files:

• Syntax highlighting for .pidl.json files
• Real-time validation with error diagnostics
• Diagram preview (Mermaid webview)
• Export to Mermaid and SVG
• Security analysis command
• Context menu integration

Commands:

Command	Description
PIDL: Validate Current File	Validate the current file
PIDL: Preview Diagram	Open diagram preview
PIDL: Export as Mermaid	Export to Mermaid format
PIDL: Export as SVG	Export to SVG image
PIDL: Run Security Analysis	Run security analysis

New Protocol Examples

Three new comprehensive protocol examples:

SAML 2.0 Web Browser SSO

SP-initiated Single Sign-On with full flow:

pidl generate -f mermaid examples/saml2_sso.json

WebAuthn/FIDO2 Registration

Passwordless credential registration:

pidl generate -f mermaid examples/webauthn_registration.json

SCIM User Provisioning

User lifecycle management:

pidl generate -f mermaid examples/scim_provisioning.json

New Protocol and Credential Constants

Extended protocol support:

Protocol	Description
saml	SAML 2.0
webauthn	WebAuthn/FIDO2
fido2	FIDO2
oidc	OpenID Connect

New credential types:

Credential	Description
x509_certificate	X.509 certificate
attestation_certificate	WebAuthn attestation
bearer_token	Bearer token
saml_assertion	SAML assertion
session_cookie	Session cookie

Go Library

New packages and functions:

import (
    "github.com/grokify/pidl"
    "github.com/grokify/pidl/export"
)

// Data lineage
lineage := pidl.AnalyzeDataLineage(protocol)
upstream := lineage.GetUpstream(entityID, portName)
impacted := lineage.GetImpactedEntities(entityID)

// Parallel execution
graph := pidl.AnalyzeExecutionGraph(protocol)
blocks := pidl.DetectParallelBlocks(protocol)
canParallel := pidl.CanExecuteInParallel(protocol, "a", "b")
maxParallel := pidl.GetMaxParallelism(protocol)

// Cost tracking
costAnalysis := pidl.AnalyzeProcessCosts(protocol)
cost := pidl.CalculateExecutionCost(entity, metrics)

// Latency budget tracking
latencyAnalysis := pidl.AnalyzeProcessLatency(protocol)
measurement := pidl.CalculateActualLatency(entity, duration)
report := pidl.FormatLatencyReport(latencyAnalysis)

// JSON Schema validation
registry := pidl.NewSchemaRegistry()
result := pidl.ValidateData(data, schema)
validator := pidl.NewPortSchemaValidator()
result, _ := validator.ValidateEntityInputs(entity, inputs)

// Workflow exports
temporal := export.NewTemporalExporter()
prefect := export.NewPrefectExporter()
bpmn := export.NewBPMNExporter()
stepfn := export.NewStepFunctionsExporter()
code, _ := temporal.Export(protocol)

Migration

Existing PIDL files remain fully compatible. New fields are optional:

• flow.data_mappings: Explicit data port mappings
• entity.parallel: Parallel execution configuration
• entity.processing.cost_model: Cost tracking configuration
• entity.processing.latency_budget: Latency SLI configuration
• data_port.schema: JSON Schema reference for validation

Documentation

• CLI Reference - Full command documentation
• Library Reference - Go library usage
• Process Guide - Process specification guide
• Workflow Exports - Workflow engine export guide
• Extending PIDL - Custom renderers, rules, exporters
• Changelog - Full change history

License

MIT License