Edifact.Validation 1.0.0-preview.6

Edifact.Validation

Validates an interchange against a directory and any implementation guides: envelope structure, segment and element cardinality, representation and code values — each finding carrying the rule that produced it, the authority that raised it, and where in the source it applies.

This is the usual entry point. It pulls in everything below it, so one package reference gets you the tokenizer, the directory model, the structure matcher and the overlay engine. Add Edifact.Projection to turn a validated message into JSON or XML, or Edifact.Acknowledgement to answer with a CONTRL.

Install

dotnet add package Edifact.Validation --prerelease

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

You supply the directory

No directory data ships in this package. A compiled pack is a derivative of the UN Directory, and shipping one would make every consumer a redistributor of it — a stronger claim than this project has made. Download a release from UNECE (https://unece.org/trade/uncefact/unedifact/download) and ingest it once:

dotnet tool install --global Edifact.Cli --prerelease
edifact ingest ~/Downloads/D96A --out ~/edifact/packs/compiled

That writes the pack to ~/edifact/packs/compiled/untdid-d96a, and puts the four ISO 9735 syntax definitions in ~/edifact/packs/syntax beside it — the two directories the example below reads. A directory release and a syntax version are independent axes and no ingestion can produce the service definitions, so those four are transcribed once per syntax version and ship inside the Edifact.Cli package. Files already in that directory are left alone.

Use it

using Edifact.Core.Diagnostics;
using Edifact.Overlays.Serialization;
using Edifact.Schema.Serialization;
using Edifact.Validation;

var syntax = new SyntaxPackSet("/home/me/edifact/packs/syntax");
var pack = PackReader.Read("/home/me/edifact/packs/compiled/untdid-d96a", syntax.For);

// Guides are optional and go in precedence order. Composed once here, so a broken one is heard
// about at start-up rather than on the first message of that type.
var guides = new[] { OverlayJson.ReadFile("acme-invoic-2024.json") };

// Build it once and keep it: compiled message definitions are cached inside.
var validator = new EdifactValidator(pack, guides, syntax.For);

var report = validator.Validate(File.ReadAllText("invoice.edi"));

Console.WriteLine($"{report.Interchange.Messages.Length} message(s), "
    + $"read as ISO 9735 version {(int)report.Syntax}");

foreach (var finding in report.Result)
{
    Console.WriteLine($"{finding.Severity} {finding.RuleId} at {finding.Span} {finding.Path}");
    Console.WriteLine($"  {finding.Message}");
    Console.WriteLine($"  raised by {finding.Origin.SourceId} ({finding.Origin.Kind})");

    foreach (var over in finding.Contributing) Console.WriteLine($"  over {over.SourceId}");
}

if (!report.IsValid) Environment.Exit(1);

report.Trees holds one MessageTree per message, in interchange order, for walking the structure; report.Interchange is the interchange taken apart into groups and messages, whether or not it was valid.

Three things worth knowing

Nothing on the read path throws. Not a truncated transmission, not a message type the directory has never heard of, not a file that is not EDIFACT at all. Every defect is a Finding with a position, a severity, a stable rule identifier and the authority that raised it, and a MessageTree always exists. The one exception is a guide that cannot be composed, which throws OverlayCompilationException from the constructor: an interchange is input, and a guide is configuration. To take guides from strangers too, compose them with OverlayCompiler first and read the findings.

Severity follows how much authority stands behind a rule. A code the directory does not publish is a warning, because a published list is advisory on its own — D.01B's own entry for 4053 lists two codes and then instructs the reader to use Incoterms it never enumerates. A code an agreement forbids is an error, because somebody signed it.

The syntax version comes from the interchange, not from the pack. A D.01B interchange written in version 3 syntax is legal and common, and it says so in UNB data element 0002. That is what the syntax.For argument is for; without it the pack's own version is used and the substitution is reported.

Where this sits

Edifact.Core       → nothing                the tokenizer, usable with no directory at all
Edifact.Schema     → Core                   what a release says
Edifact.Structure  → Core, Schema           matching a segment table
Edifact.Overlays   → Structure              what a guide says on top of a release
Edifact.Validation → Structure, Overlays    envelope, element and structural checks  ← you are here

The constraints this layer must honour are in DESIGN.md. 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.