A thousand private PDFs — partner rules as an overlay you own

Written for ED-2 — the RFID systems-integrator / VAR practice — the practice lead who authors partner rules per client deployment and carries the margin.

One thesis: the real spec your client's 856 must satisfy is not the X12 standard but their hub's private implementation guide — a constraint layer no public corpus can ever cover — so partner rules live in a user-authored JSON overlay on the base grammar: validated like the grammar, pinned like the grammar, and never a per-partner code fork.

The problem shape: structurally uncoverable

Every hub — each mass retailer, each marketplace, each 3PL — publishes its own implementation guide constraining the same transaction sets differently: this REF is mandatory here, that qualifier is forbidden there, this segment's max use drops from twelve to one. The guides are private PDFs, distributed under supplier portals, revised on the hub's schedule.

That is why no vendor's test corpus can save you, including ours. A corpus can establish what a standard-valid 856 is. It cannot contain a thousand private documents it has no license to see. Any product that claims to "support" your partner's rules out of the box is describing a mapping team behind a curtain — which is precisely the business this layer refuses to be in, and precisely the work a practice like yours gets paid for. The design question is where that work lives: in a code fork you maintain forever, or in a data file you author once and pin.

The overlay format: constrain, require, restrict — never redefine

An overlay is a JSON file applied over the base self-authored grammar at validate time. Its vocabulary is deliberately closed to three operations:

• constrain — tighten what the base grammar allows: lower a max-use, narrow a length, make an optional segment situational.
• require — promote optional to mandatory: the hub wants a REF with its qualifier on every shipment-level loop, so absence is now a failure.
• restrict — shrink a value space: only these qualifiers, only this code, only this date-time convention.

What an overlay cannot do is redefine: it cannot add segments the base grammar lacks, reorder loops, or contradict the standard's structure. An overlay that tries is itself invalid — overlays are validated against the overlay schema exactly as documents are validated against grammars. This asymmetry is the safety property: a partner overlay can only ever make validation stricter, so a document that passes with the overlay passes the base standard too. Stricter-only is also what keeps the compile safe: events emitted from an overlay-validated document are the same conformant EPCIS 2.0 output as ever, and the superset context a hub's extra REFs carry rides along without ever costing conformance.

Authoring one from a public supplier guide

A worked overlay, authored from a publicly posted supplier routing guide — the shape is three rulings and a provenance block:

{
  "overlay": "hub-856-004010",
  "base": { "set": "856", "version": "004010",
            "grammarPin": "9f31c4…e2a8" },
  "provenance": { "source": "hub supplier guide rev 2026-04 (public URL)",
                  "authored": "2026-07", "author": "practice" },
  "rules": [
    { "require":  { "segment": "REF", "at": "HL-shipment",
                    "withQualifier": "BM" } },
    { "constrain": { "segment": "SN1", "at": "HL-item", "maxUse": 1 } },
    { "restrict": { "segment": "DTM", "element": 1,
                    "values": ["011", "017"] } }
  ]
}

Run the same synthetic file both ways and the delta is the point:

$ npx transactions.dev validate 856-test.edi
VALID  856/004010  base grammar 9f31c4…

$ npx transactions.dev validate 856-test.edi --overlay hub-856-004010.json
INVALID  2 findings
  overlay:require   REF(BM) absent at HL-shipment
  overlay:restrict  DTM01 "067" not in [011, 017]
$ echo $?
1

Same engine, same typed-verdict contract, one data file of difference. The findings name the overlay rule that fired, so the conversation with the client — or the hub — starts from a citation, not an opinion.

Pinned like everything else

Overlays enter the same governance as grammars: sha256-pinned, provenance block naming the guide revision they encode, changed by journaled ruling. When the hub revises its guide, the change is a new overlay version with a new pin — which means "which rules were we validating against in March" is answerable forever, a question every chargeback dispute eventually asks. And because the overlay pins the base grammar digest it was authored against, a grammar update can never silently change what a partner overlay means.

The margin this leaves where you want it

Read the division of labor. The engine owns the standard: base grammars, the differential harness, the byte-exact round-trip, the compile to conformant events, reconcile at the dock. You own the partner knowledge: each client deployment ships with overlays your practice authored from the guides your client is party to — billable, reusable across clients on the same hub, and maintained on the hub's revision cadence rather than a platform's release cadence. No mapping platform to babysit, no code fork per partner, and the acceptance artifact at go-live is a validation transcript citing your overlay by pin.

The access flow at /get-access/ asks whose partner guides you run, for whom, and in what form you hold them; a practice with three hubs' guides on the shelf is exactly the shape the overlay engine is sequenced for.

---

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