Skip to content

PIDL v0.9.0 Release Notes

Release Date: 2026-10-22

This release takes the walkthrough beyond one HTML file. The walkthrough is now a documented format that any page can show with one script tag from a CDN. Each request can be read as HTTP, as a curl command or as SDK code from tested source files, and each implementation of a protocol can keep its own code samples, so the protocol document stays independent of any of them. Steps can be narrated in several languages for audio and video, and the same examples drive a runnable Postman collection.

Highlights

  • Embeddable viewer: @grokify/pidl-viewer shows any walkthrough from a CDN with one script tag
  • Walkthrough format: pidl-walkthrough/v1, with a JSON Schema and TypeScript types
  • Code samples and cURL: each request as HTTP, a generated curl command, or SDK code from tested source files; sample sets keep each implementation's code apart from the protocol
  • Postman collections: a runnable collection per protocol, with values chained between requests, checks on every response, and signed requests sent through a signing proxy
  • Narration: spoken text by language, scenario briefings and pronunciations
  • A worked OAuth 2.0 example that exercises all of it

What's New

Embeddable Viewer

<div id="walkthrough"></div>
<script src="https://cdn.jsdelivr.net/npm/@grokify/pidl-viewer@0.9.0/dist-lib/pidl-viewer.js"
        data-pidl-target="#walkthrough"
        data-pidl-src="api.walkthrough.json"></script>

The script shows a walkthrough from inline JSON (data-pidl-data), a URL (data-pidl-src) or the page's ?src= parameter, so one page can show any walkthrough. PidlViewer.mount(element, {src | data}) does the same from JavaScript.

  • The viewer renders inside a shadow root: the page's styles do not change it, and its styles do not leak into the page.
  • Several viewers can share a page. Each takes the step keys only while it has focus.
  • ?src= loads only https: URLs or the page's own origin, and fetches without cookies.

pidl generate -f viewer still writes one self-contained HTML file for offline use. See Embedding the Viewer.

Walkthrough Format

pidl generate -f walkthrough-json writes pidl-walkthrough/v1, the processed form viewers read: every scenario with fragments expanded, each step's example, generated curl command, samples and narration, and analyzer findings. The format is now documented and versioned:

  • schema/walkthrough.schema.json is generated from the Go types and embedded as schema.WalkthroughSchemaJSON, with a test that it is current and that every built-in example validates.
  • The viewer's TypeScript types are generated from the schema, and ship in the npm package.
  • A reader accepts any v1 walkthrough, including one with fields it does not know, and refuses another major version.

See the walkthrough format reference.

Code Samples and cURL

Every example request now has an equivalent curl command. A signed request's command replays the example's signature headers and says so.

Steps can also show code samples, ideally taken from a region between pidl:begin and pidl:end markers in a tested file, at a tag or commit. In the viewer, each request and response has a tab for HTTP, cURL and every sample language. A step where nothing goes over HTTP, such as a person approving in a browser, can show code alone.

Sample sets keep samples out of the protocol document. An implementation keeps a set (pidl-samples/v1) beside its tested code, attaching each sample to a step by its address, and generation joins any number of sets:

pidl samples resolve --repo-dir . sdk-go.pidl-samples.json            # record the code and its hash in the set
pidl samples check --repo-dir . --protocol api.json sdk-go.pidl-samples.json   # in the SDK's CI
pidl generate -f viewer --samples sdk-go.pidl-samples.json --samples sdk-ts.pidl-samples.json -o api.html api.json

An address that names no step is an error, so a set cannot fall silently behind the protocol. Samples can also be written inline on a step's example, with a lock file beside the document. The set format has its own schema, schema/samples.schema.json. See Code Samples and cURL.

Postman Collections

pidl generate -f postman --signer proxy -o api.postman_collection.json oauth2_api_access

A folder for each scenario holds a request for each step the client role sends. Values a response delivers are passed to the requests that reuse them, including string parameters of headers, such as the scope of a WWW-Authenticate challenge. Each response is checked against its example, and deferred responses are polled.

  • --signer proxy sends requests with HTTP message signatures through a signing proxy, which creates the signature; Signature-Key tells it the scheme and, for the jwt scheme, the chained token to present. Unsigned requests are sent directly.
  • --mock saves the example responses for a Postman mock server.
  • -f postman-environment writes an environment for a named target, with per-scenario overrides.

See Postman Collections.

Narration

Scenarios and steps can carry narration keyed by BCP 47 language, with the protocol's source language as the fallback. Scenarios can carry a briefing, steps can override their narration for the HTTP, cURL or code view, and pronunciations tell text-to-speech tools how to say terms. The walkthrough carries all of it for audio and video tools; the viewer does not play narration yet. See Narration.

Scenario Structure

  • Groups order scenarios into sections.
  • Variants pair alternative forms of one journey and follow their base.
  • Step IDs name steps, as <include>.<id> inside fragments, so links such as #client-credentials/call.api-request keep working when steps are added, and sample sets can address them.

Worked Example

oauth2_api_access walks through calling an API with OAuth 2.0, with messages drawn from the RFCs: the authorization code grant with PKCE, client credentials, a variant after a Bearer scope challenge, an asynchronous export answered 202 and polled, and a request signed with HTTP Message Signatures and Content-Digest. It has shared fragments, decoded JWT access tokens, step IDs, narration, a briefing and pronunciations, and it is the example the guides use.

Library

  • Protocol.WithSampleSet, ParseSampleSet and CheckoutSourceReader for sample sets.
  • ResolveOptions.FS resolves the documents that extends and imports name from an fs.FS.
  • Built-in examples apply their sample lock and resolve their extends when loaded.

Removed

  • The aauth_protocol and aauth_petstore examples, with the AAuth example's Go sample lock. pidl's built-in examples describe no single protocol in depth and carry no implementation's code; protocol documents and their walkthroughs belong with the protocol, and code samples with each implementation.

Fixes

  • Sample source paths are checked the same way on every platform. The check used filepath.IsAbs, which does not treat /etc/passwd as absolute on Windows, so a test failed there. pidl now uses ValidateSlashPath from oscompat v0.8.0, its first dependency, which depends only on the standard library.

Documentation

Installation

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

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