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

Written for ED-3 — 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 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 — 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. The design insight — the guide as machine-checkable data rather than a PDF — is the same conviction this engine holds everywhere: grammars are data, partner rules are overlay data, 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, 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.
• 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 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 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 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. 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/ 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.

---

826 words. The access flow is at /get-access/; the family's event door is epcis.dev.