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

> transactions.dev · by visibility.cloud — 2026-07-31
> Written for 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](/blog/the-three-parser-differential-harness/). 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](/blog/grammars-are-data-grammar-pins/) 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:

```json
{
  "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](/blog/the-three-parser-differential-harness/), the
[byte-exact round-trip](/blog/the-round-trip-law/), the compile to conformant
events, [reconcile](/blog/reconcile-is-a-verdict/) 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/](/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.

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