Edifact.Eancom 1.0.0-preview.6

Edifact.Eancom

Reads the EANCOM implementation guides published by GS1 and writes them as overlay documents. Part II gives the positions a subset does not use, the entries it promotes to required, and the code values it restricts elements to; Part III gives the code values EANCOM publishes that the base UN/EDIFACT directory does not.

No part of the EANCOM publication is included in this package. This is a reader; you supply a working copy — packs/sources/EANCOM/README.md says more about where one comes from and what its licence permits. The 1997 edition is mirrored at GS1's own archive, https://ref.gs1.org/standards/eancom/archive; the 2002 edition has no equivalent public link and is obtained through GS1's own (subscription-gated) channels.

What it writes — code values and structure, none of GS1's names or definitions — is a Permitted Work under section 4.D(2) of the GS1 IP Policy, which grants Implementers a royalty-free, perpetual, irrevocable copyright licence for exactly that. The repository's NOTICE quotes the grant and records its two limits: it is non-sublicensable, and it is granted solely for implementing the standard.

Install

dotnet add package Edifact.Eancom --prerelease

net8.0 and net10.0, no external dependencies.

Why Part II

EANCOM is published in three parts, and only one of them restricts anything.

Part III is the data element directory — what a code means wherever it is used. Against it EANCOM is a superset of UN/EDIFACT: it publishes code values the UN directory does not, and a guide drawn from it can only extend. Layering one stops valid EANCOM traffic being reported as invalid, and does not make a report agree with EANCOM.

Part II is the per-message implementation guide, and it is the restrictive half. It names the positions the subset uses, marks conditional entries required or not used, and cuts code lists down to the values that mean something in that message. A guide built from Part II is the one that states the agreement.

Use it

var ingestion = EancomIngester.Ingest(
    "…/ean02s3/part2/orders",
    pack,                                   // the release it is layered over
    new EancomOptions(
        SyntaxVersion.V3,
        "eancom-2002-s3-part2-orders-d01b",
        "EANCOM 2002 S3 Part II ORDERS",
        Underlays: [partThreeGuide]));

File.WriteAllText(path, OverlayJson.Serialise(ingestion.Document));

Or one command, with the edifact CLI:

edifact ingest-guide packs/sources/EANCOM/2002/ean02s3/part2/orders \
    --pack untdid-d01b --over eancom-2002-s3-orders-d01b.json --out orders-guide.json

Underlays / --over is not optional in practice. EANCOM restricts some elements to values the UN directory does not publish, and a restriction to a value nothing beneath permits is a widening the composer refuses — so the Part III guide goes underneath, and a restriction that still cannot be satisfied is reported rather than written.

EancomMessagePairIngester does the derivation, the Part III read and the layered Part II read in one call — --for (below) followed by this, written out once — and throws EancomPairException rather than returning a document if either read reports a gap in EancomIngestionReport.BlockingGaps: an unplaced row, an unknown indicator, a disagreement between occurrences, or a restriction to a code nothing beneath permits. The edifact CLI exposes it as one verb:

edifact ingest-eancom packs/sources/EANCOM/2002/ean02s3/part2/orders \
    --pack untdid-d01b --out-dir packs/overlays

Part III, the half underneath

That underlay is read by this package too. EancomDirectoryIngester is pointed at the publication's part3 folder and asked which message to gather for, and writes the code values EANCOM publishes that the base directory does not:

var codes = EancomDirectoryIngester.Ingest(
    "…/ean02s3/part3",
    pack,
    new MessageKey("ORDERS", "D", "01B", "UN"),
    new EancomDirectoryOptions(SyntaxVersion.V3, "eancom-2002-s3-orders-d01b", "…"));

edifact ingest-codes packs/sources/EANCOM/2002/ean02s3/part3 \
    --pack untdid-d01b --message ORDERS:D:01B:UN --out codes.json

The document it writes has policy: Extending and only ever adds to a code list, because Part III says what a code means wherever it is used and against it EANCOM is a superset. It says one thing at every path in the message where the element is reachable — 26 of them for the five elements of D.01B ORDERS — so a guide layered over it stops valid EANCOM traffic being reported as invalid.

Three of the publication's own legend rules decide what is available, and each matters:

Reading the old-code column as though it held codes is how BCO and SCO — retired in favour of LF and LG — reached an earlier draft of the guide.

Every page in the directory is read even though one message needs five of them, because each code carries an anchor naming the element it belongs to and the publication's index has pointed at the wrong page before. A mismatch is refused rather than written out.

What is read, and what is not

Only structure and code values. The status indicator is read from its own table cell and the code values from the fragment of each anchor into Part III; no name, definition or note GS1 wrote is carried into the output. That is the same line NOTICE draws for the UN directories, and it is what keeps the output a Permitted Work — a compiled embodiment made to implement the standard — rather than a copy of the publication.

Four things Part II says become four things the overlay model can state:

A row without the * restriction indicator restricts nothing. The publication's legend is explicit: an open element's listed codes "may be given as examples", and the available set is whatever Part III publishes. Reading those as the permitted set is the mistake that turns a subset guide into one that rejects valid traffic, and it is not a hypothetical — the eight party qualifiers EANCOM prints against 3035 in ORDERS carry no restriction indicator.

A (advised), D (dependent) and O (optional) all leave an entry conditional. D's condition is written in an explanatory note, in prose this library does not read.

What it cannot state

Everything read is either carried into the document or recorded in EancomIngestionReport, which is what makes the output reviewable rather than trusted. Reading ORDERS records nothing at all; the gaps that recur elsewhere in the publication:

• A restriction to a code nothing beneath permits, where the Part III guide does not cover that element.
• A restriction indicator with no code values, where what it restricts to is stated only in prose.

Licence

Apache-2.0. See NOTICE for what is not covered by it.