Edifact.Cli 1.0.0-preview.6

Edifact.Cli

The edifact command line tool: ingest a UN/EDIFACT directory distribution into a pack, inspect what a pack holds, and validate or project an interchange against it.

No generated code, no message types compiled in — everything it knows comes from a directory you ingested and, optionally, implementation guides you wrote.

Install

dotnet tool install --global Edifact.Cli --prerelease

net8.0 and net10.0; dotnet tool install picks whichever the machine can run.

Start here

The tool ships the ISO 9735 syntax definitions — no ingestion can produce them, and an installed tool has nowhere else to get them — but no directory data, because a compiled pack is a derivative of the UN Directory and shipping one would make every consumer a redistributor of it. Download a release from UNECE (https://unece.org/trade/uncefact/unedifact/download), expand its top-level archives once, and ingest it:

edifact ingest ~/Downloads/D96A --out ~/edifact/packs/compiled
export EDIFACT_PACKS=~/edifact/packs/compiled

edifact inspect untdid-d96a
edifact validate invoice.edi
edifact validate invoice.edi --tree --round-trip
edifact project invoice.edi

Ingesting D.96A gives 462 data elements, 161 composites, 127 segments, 207 code lists and 125 messages; D.01B gives 641, 295, 233, 268 and 208. Counts are exact, and an ingest that cannot account for a line refuses to write a pack unless you pass --no-strict.

ingest also leaves the syntax definitions in ~/edifact/packs/syntax, beside the pack it wrote. That is for the sake of the libraries rather than the tool — the tool finds its own copy beside the executable, but Edifact.Validation and the rest need a directory to point SyntaxPackSet at, and this is the one command that can put one there. Files already in that directory are left alone.

Commands

ingest <path-to-distribution>   Read a UNECE release directory into a compiled pack, and leave
                                the ISO 9735 definitions in a `syntax` directory beside it.
  --out <directory>             Where packs are written. Default: as resolved below.
  --syntax <directory>          Where the ISO 9735 definitions live.
  --no-strict                   Write a pack even if something went unaccounted for.
  --include-prose               Keep the directory's descriptive text. Writes to <pack-id>-prose.

ingest-guide <path-to-message>  Read an EANCOM Part II message guide into an overlay.
  --pack <pack-id>              Which release it is layered over. Required.
  --packs <directory>           Where packs live.
  --syntax <directory>          Where the ISO 9735 definitions live.
  --over <path>                 A guide this one will sit above. Repeatable. Needed where
                                EANCOM restricts to codes the UN directory does not
                                publish, which the Part III guide adds.
  --out <file>                  Write the guide there rather than to standard output.
  --id / --name / --edition     Override what the document calls itself.

ingest-codes <path-to-part3>    Read the EANCOM Part III directory into the code set
                                additions one message needs.
  --pack <pack-id>              Which release it is layered over. Required.
  --message <TYPE:V:R:A>        Which message to gather paths for. Required.
  --element <code>              A data element to cover. Repeatable. Default: the ten
                                the committed ORDERS guide covers.
  --for <path-to-part2>         Derive the element set from a Part II message folder's own
                                UnavailableCode gaps, instead of --element.
  --packs <directory>           Where packs live.
  --syntax <directory>          Where the ISO 9735 definitions live.
  --out <file>                  Write the guide there rather than to standard output.
  --id / --name / --edition     Override what the document calls itself.

ingest-eancom <path-to-part2>   Read one EANCOM message's Part II guide and the Part III
                                underlay it needs, in one step: derive the element set
                                --for would, write both documents, and write neither if
                                either read reports a gap this ingester could still act
                                on — see Edifact.Eancom's own README for which four gap
                                kinds those are.
  --pack <pack-id>              Which release both documents are layered over. Required.
  --out-dir <directory>         Where both documents are written. Required.
  --part3 <path>                The edition's part3 folder. Default: the part3 folder
                                beside the given part2 folder's edition.
  --packs <directory>           Where packs live.
  --syntax <directory>          Where the ISO 9735 definitions live.
  --edition <text>              Override what the Part II document calls the edition.

inspect <pack-id>               Print a compiled pack's manifest.
  --packs <directory>           Where packs live.

validate <path-to-interchange>  Read an interchange and report what is wrong with it.
  --pack <pack-id>              Which release to validate against. Default: whichever one UNH says
                                the interchange was written against.
  --packs <directory>           Where packs live.
  --syntax <directory>          Where the ISO 9735 definitions live.
  --guide <path>                An implementation guide to layer over the release. Repeatable;
                                the order is the precedence order.
  --tree                        Print each message's structure as well.
  --quiet                       Report only errors, not warnings.
  --round-trip                  Also write the interchange back out and report whether it is
                                reproduced character for character.

project <path-to-interchange>   Write each message of an interchange as a document.
project --message <key>         Write a message type and everything it names.
  --pack <pack-id>              Which release. Worked out from UNH for a file; required for
                                --message.
  --packs, --syntax, --guide    As for validate.
  --xml                         Write XML rather than JSON. Interchanges only.
  --out <directory>             Write one file per message there rather than to standard output.
                                Required for an interchange holding more than one message.

edifact validate invoice.edi --guide acme-invoic.json reports against the agreement as well as the directory, so a finding can say "'DP' is not permitted for 3035 by acme-invoic; the base untdid-d96a directory does permit it" rather than quoting a rule identifier. Guides are JSON documents — see Edifact.Overlays.

--round-trip writes the interchange back out and compares it with what arrived. When it diverges the tool names the first position where, with both sides shown and the whitespace made visible.

Where packs are found

--packs / --syntax, then $EDIFACT_PACKS / $EDIFACT_SYNTAX, then packs/compiled and packs/syntax beside the nearest Edifact.slnx or .edifact at or above the working directory, then the same two under the per-user application data directory, and last whatever shipped beside the executable — which is where an installed tool finds the syntax definitions, and never a compiled pack.

An option or a variable that is set is the answer: if it names nothing, the search stops and says so rather than quietly using somewhere else. Drop an empty .edifact file at the top of your own repository and the probe finds packs/compiled beside it without a path in every invocation.

When nothing answers, the tool prints every place it looked, in order.

Exit codes

The library

The tool is a thin layer over the nine packages it is built from — Edifact.Validation is the usual entry point for doing this in your own process, and Edifact.Untdid is ingest.

Full documentation, including a hosted validator and container images: https://github.com/101-semaphore/EDIFACT.

Licence

Apache-2.0. See the NOTICE in this package for what the wider project is derived from and under what terms.