# If you're leaving Stedi's EDI platform, your Guides still work here

> transactions.dev · by visibility.cloud — 2026-07-31
> Written for the in-house supply-chain platform team — the engineering manager whose EDI stack sits on a platform now marketed to a different industry.

One thesis: **Stedi's Guide JSON is a proven, publicly documented,
JSON-Schema-first representation of X12 transactions, and transactions.dev
accepts it as an input format — so a team whose EDI stack was built on a
platform that has since committed itself to healthcare can migrate its guide
investment instead of rewriting it.**

## Credit first, because it is owed

Stedi built the best developer-facing EDI surface the supply-chain world has
seen: the [free public X12 reference](https://www.stedi.com/edi/x12) that this
site links for every segment-level question, and the Guides concept —
machine-readable implementation guides backed by a JSON Schema defining the
structure of the transaction. Their engineering set the craft benchmark this
family aims at. And their business went where the momentum was: the company is
today a healthcare clearinghouse — the whole story is in
[the landscape post](/blog/the-supply-chain-layer-is-open-ground/) — with the
general EDI platform's marketing and documented use cases now exclusively
healthcare X12.

Which leaves a specific population holding a specific asset: platform teams
who encoded years of trading-partner knowledge into Guides, on a platform
whose roadmap no longer points at their industry. The knowledge in those
files is yours — partner constraints, qualifier choices, field shapes. It
deserves a door, not a rewrite.

## What a Guide is, and why the format outlived its market

A Stedi Guide is an implementation guide as data: the transaction structure,
per-partner constraints, and a JSON Schema for the JSON shape their
translation produces and consumes. The Guide JSON format is publicly
documented in [Stedi's docs](https://www.stedi.com/docs/edi-platform/operate/transform-json/guide-json).
The design insight — the guide as machine-checkable data rather than a PDF —
is the same conviction this engine holds everywhere:
[grammars are data](/blog/grammars-are-data-grammar-pins/),
[partner rules are overlay data](/blog/partner-guides-as-overlays/), and data
has provenance. Good formats deserve to outlive the market strategy of their
origin, and this one does.

## The compatibility contract

Stated as an interop commitment, with its edges visible:

- **What is accepted.** Guide-shaped JSON documents are a first-class input:
  `parse` ingests them, maps them onto
  [the canonical JSON pivot](/blog/canonical-json-the-lossless-pivot/), and
  from the pivot every verb applies — `validate` against base grammar plus
  overlays, `emit` to wire bytes, `join` to conformant EPCIS 2.0 events with
  [`bizTransactionList` context](/blog/biztransaction-is-a-core-field/).
- **What guide knowledge maps to.** The constraint content of a guide —
  mandatory-ness, qualifier restrictions, usage tightening — corresponds to
  the overlay layer here, and the structural content to the base grammar; the
  ingestion records, per element, which of your guide's rules landed where.
- **What is not emulated.** This is not a re-implementation of Stedi's EDI
  platform — no trading-partner network, no SFTP/AS2 infrastructure
  emulation, no claim of behavioral equivalence with their translate APIs.
  Their reference stays linked as the segment authority it is; nothing of
  theirs is republished here.
- **Provenance, as always.** A document that arrived as Guide JSON carries
  that fact in its provenance trail, so an auditor can distinguish
  wire-parsed from bridge-ingested forever.
- **Licensing, unchanged.** The bridge ingests *your* guide files — your
  authored constraints, your partner knowledge. It changes nothing about
  [the X12 licensing posture](/blog/x12-licensing-stated-plainly/) of this
  surface: original prose, self-authored grammars, element detail linked at
  Stedi's licensed reference and reproduced nowhere.

## A worked migration, three steps

```
$ npx transactions.dev parse fulfillment-856.guide.json --from stedi-guide
PARSED  856/004010  via guide-json bridge → canonical 3d92f1…

$ npx transactions.dev emit 3d92f1… | npx transactions.dev parse - --fidelity
BYTE-EXACT  the bridge ingestion round-trips through wire form

$ npx transactions.dev join 3d92f1… --json
{ "type": "ObjectEvent", "bizStep": "shipping",
  "bizTransactionList": [
    { "type": "desadv", "bizTransaction": "urn:epc:id:gdti:0614141.00001.8560001" } ],
  ... }
```

Step one ingests the Guide-shaped document and pivots it. Step two proves the
pivot holds wire fidelity —
[the same round-trip law](/blog/the-round-trip-law/) every native parse
answers to, applied to the bridge. Step three is the part your previous
platform never had: the compile to a conformant EPCIS 2.0 event record,
validated against the pinned official schema, with the transaction context on
core fields. The migration does not merely re-house your EDI; it lands it on
the event spine the rest of the [family](https://visibility.cloud) reads.

## The posture, stated

Benchmark and bridge, not clone. The respectful reading of the situation is
that Stedi solved developer EDI, proved the market could be served with
craft, and then chose healthcare — leaving the supply-chain layer, and the
EDI-to-EPCIS join nobody built, as
[open ground](/blog/the-supply-chain-layer-is-open-ground/). Accepting their
format is how you honor good prior art: interoperate with it, credit it, and
extend the chain one layer further than it went.

If your team is holding a guide catalog and a migration question, the access
flow at [/get-access/](/get-access/) starts with an address and then asks
what you run today — "Stedi Guides, N of them, these transaction sets" is
exactly the answer that sequences the bridge work. Bring one guide and one
day of real traffic to the evaluation: the fidelity report and the validated
event output are the whole argument, and both are artifacts your
architecture review can hold, not claims it has to weigh.

---
Access: https://transactions.dev/get-access/ · All posts: https://transactions.dev/blog/ · Machine face: https://transactions.dev/llms.txt