Skip to content

PIDL v0.10.0 Release Notes

Release Date: 2026-10-27

This release puts real runs beside the walkthrough. A walkthrough explains a protocol with examples written to teach it; an observed run adds what a real system actually exchanged: the request each step sent, the response it got, the tokens it carried, and the messages the protocol does not describe, such as metadata and key fetches. A developer sees the concept and their own run side by side, and sees at once which steps their system performed, which it skipped and what it did in between.

Nothing in pidl knows any one protocol. The protocol document says how each step is recognized and where each token travels; a binding says how one deployment names its participants, hosts and paths.

Highlights

  • Observed runs: pidl generate --observation shows a real run beside the walkthrough's examples
  • Two new formats: pidl-observation/v1 for what a run exchanged and pidl-binding/v1 for one deployment, each with a JSON Schema
  • Protocol-agnostic matching: documents carry match rules and token carried_in places; pidl finds scenario instances in a capture and aligns their exchanges to the steps
  • Concept / Observed switch in the viewer, with timing, match strength and the extra exchanges between steps

What's New

Observed Runs

# Turn a capture into an observation
pidl observe import --from sandbox -o run.json trace.json

# Show it beside the document's steps
pidl generate -f viewer --observation run.json --binding deployment.json -o live.html protocol.json

generate finds each scenario instance in the capture and adds it as its own scenario entry, right after the scenario it is an instance of, named <scenario>.observed-<n>. Every step keeps its explanation and example and gains the exchange that was observed, with:

  • its status: matched, not seen, skipped, unmatchable (no rule to match by) or unobservable (it happens in a browser or out of band);
  • for a match, its strength: strong when a path, status, header or body test passed, or weak when only the participants and method agreed;
  • the tokens it carried, decoded but not verified.

Exchanges that matched no step are kept, each after the step it followed. A repeated step, such as a poll, takes every matching exchange and shows the last.

Options:

Option Does
--observation the observation to show
--binding the deployment's binding
--scenarios the scenarios to look for, in order (default: every scenario that is not a fragment)
--from, --to match only exchanges in a time range
--raw keep raw token, signature and credential values

generate reports the instances it found and warnings for the document's author, such as a match rule that names a literal identifier rather than a {param}.

Values Masked by Default

An observed run comes from a real system, so raw values are masked unless --raw is given: JWTs become [redacted:jwt], and carried token values, signatures, Authorization and cookies become [redacted]. Decoded token claims are kept, so the page still explains each token.

Observation and Binding Formats

  • pidl-observation/v1 records each exchange's time, the capturing tool's labels for sender and receiver, the request and response with headers in order, bodies as JSON, text or base64, and the tool's own annotations, such as assertion results.
  • pidl-binding/v1 maps a deployment to the document: participants by label and host, labels by path, path substitutions per step, URL rewrites for proxies, the roles a capture cannot see, and match rules for steps keyed by <scenario>/<step-id>, <defining-scenario>/<flow-id> or */<flow-id>, most specific first.

Both schemas are generated from the Go types and embedded as schema.ObservationSchemaJSON and schema.BindingSchemaJSON.

Match Rules and Token Carriage

A flow can say how its message is recognized:

{"id": "poll", "match": {"method": "GET", "path": "/pending/{id}", "status": 200, "repeat": true}}

A rule tests the method, a path template ({id}) or regular expression (^…), the status, headers (exact, prefix with *, or regular expression) and request body values by JSON pointer, and can mark a step repeat or optional. A rule in the binding overrides the document's for one deployment.

A token definition can say where the token travels, so pidl can find and decode it in a real message:

"carried_in": [{"in": "header", "name": "Signature-Key", "param": "jwt", "typ": "aa-agent+jwt"}]

A place is a header (with an optional structured-field parameter) or a body JSON pointer, and typ tells apart tokens that travel in the same place. Validation checks both.

Viewer

An observed entry shows a Concept / Observed switch. Concept shows the document's examples; Observed shows the run's exchanges in the same request, response and token panels, with the time of each exchange and the gap from the one before, its strength, the capturing tool's name for it and its assertion results. A step without an observed exchange says why. Extra exchanges are drawn in the diagram between the steps they followed.

The viewer is published as @grokify/pidl-viewer@0.10.0.

Library

  • observe.Apply adds observed entries to a walkthrough.
  • observe/match matches an observation to a walkthrough's scenarios: Match, NewResolver and the report types.
  • observe/adapter/sandbox reads the aauth-go sandbox trace.
  • WalkthroughJSONRenderer.Build returns the walkthrough, and its Transform field changes it before it is written.

Try It

The aauth-postman repository's make demo runs the AAuth Petstore flow against the aauth-go sandbox, captures it and writes the page: two scenario instances, every step matched strongly, and each AAuth token identified by its type.

Documentation

Dependencies

  • github.com/grokify/oscompat v0.9.0.

Installation

go install github.com/grokify/pidl/cmd/pidl@v0.10.0

<script src="https://cdn.jsdelivr.net/npm/@grokify/pidl-viewer@0.10.0/dist-lib/pidl-viewer.js"></script>