◆ An open standard · IMDG Code

One open format for Dangerous Goods Declarations.

OpenDGD is a free, open standard for the data behind an IMDG dangerous goods declaration. Create the DGD once, and every system in the chain can read it, check it and print the same form.

Read the spec → Try the playground

Box 14 · Description of goods

Structured data in

"unNumber": "1090",
"properShippingName": "ACETONE",
"class": ["3"],
"packingGroup": "II",
"flashpoint": { "valueCelsius": -17 },
"packaging": { "numberOfPackages": 10,
  "kindOfPackages": "Steel drums" }

The same text out, on any system

UN 1090, ACETONE, Class 3, PG II, (-17°C c.c.), EmS F-E,S-D, 10 x 1A1 Steel drum.

Composed by the canonical rendering algorithm (rendering.md) Same input, same output

The problem

The form is standard. The data behind it is not.

The IMO Multimodal Dangerous Goods Form is used worldwide. Behind it, the same declaration lives in a dozen incompatible shapes: PDFs, spreadsheets, bespoke EDI, screen scrapes. The goods description, the part that matters most for safety, is free text that every system writes differently.

Re-keying

Typed in again at every handover

The same declaration gets re-entered at each step of the chain. Every re-key is another chance for an error on cargo that cannot afford one.

Mismatch

Descriptions that don't agree

No two systems build box 14 the same way, so one line of goods can read differently on the shipper's copy, the forwarder's and the carrier's.

Opacity

Nothing to check by machine

With no structured data underneath, a declaration cannot be validated automatically against the IMDG Code. Someone has to read it by eye.

What OpenDGD is

A shared data format, and one way to render it.

Three parts, all free and openly licensed. Put structured data in, and the same declaration comes out on any conforming system.

Part 01

JSON SCHEMA

The data model

A JSON Schema for a complete IMDG dangerous goods declaration. Every field maps to a numbered box on the IMO form.

opendgd.schema.json →

Part 02

ALGORITHM

Canonical rendering

A published algorithm for building box 14, so every implementation produces the same goods description from the same data.

rendering.md →

Part 03

THE FORM

One document out

The completed IMO form is the end product. The template and the algorithm are part of the standard, so the same declaration gives the same DOCX and PDF everywhere. A render library and API produce it.

openapi.yaml →

How it works

Describe it once. Check it. Get the form.

Three steps take a declaration from structured data to a finished document, with the same goods description at every stage.

Describe the consignment

Enter the parties, transport, container and each dangerous goods line as OpenDGD JSON, or build it in the playground below.

Check conformance

Check that it conforms to the standard for free, then validate against the full IMDG Code with a conforming validator.

Get the form

Get a completed IMO Multimodal Dangerous Goods Form as DOCX or PDF, the same document on every implementation.

◆ Why it's credible

Drawn from a production dangerous goods engine.

OpenDGD generalises a production IMDG dangerous goods declaration engine, the kind used across the industry, into an open format that anyone can implement. The data format and the rendering are the shared commons; how deeply an implementation validates against the IMDG Code is where products differ.

IMDG 42-24

Latest amendment

Boxes 1 to 22

Full IMO form

Open

Free to implement

Charter "The data format is a shared, open commons. How deeply you validate against the IMDG Code is where products compete." OpenDGD governance charter

In the repository ◆ v0.1 · draft

The standard, on paper.

Everything in the v0.1 draft: the schema, the rendering algorithm, the form template, the reference API, the render service, and worked examples. Each one checked.

opendgd / v0.1CC BY 4.0 spec · Apache 2.0 code

spec/opendgd.schema.jsonThe standard: a complete IMDG declaration as JSON Schema 2020-12.validates

spec/rendering.mdCanonical box 14 rendering algorithm, 35 ordered segments.normative

spec/form/opendgd-dgd-template.docxThe IMO form template. The rendered document is part of the standard.normative

spec/openapi.yamlReference API: schema, conformance, docx, pdf.parses

tools/render-dgdRender library, CLI and service: fills the form, returns DOCX and PDF.apache-2.0

Dockerfile · deploy/Container image and Kubernetes manifests for the render service.deploy

examples/acetone-un1090.jsonA flammable-liquid declaration, the worked example above.validates

examples/lithium-battery-un3480.jsonA Class 9 line that exercises the special-provision path.validates

examples/radioactive-un2915.jsonA Class 7 line with radionuclide, activity, category and transport index.validates

GOVERNANCE · LICENSE · CONTRIBUTINGStewardship, the dual licence, and how to propose changes.meta

Open and free

Open format. Competitive validation.

The format is free and locks in no one. What you pay for, if anything, is how thoroughly a declaration gets checked.

Openly licensed

CC BY 4.0 for the spec, Apache 2.0 for the code. Use it for anything, including commercial products.

No lock-in

The core API (schema, conformance, DOCX, PDF) needs no engine and no account. Host your own or use the reference service.

Public process

Proposals and changes happen in the open, with a route to neutral governance as more organisations adopt it.

Implementations

Anyone can build one. Here is where they are listed.

Read or write OpenDGD in any language. These are the implementations we know about, the open reference included.

OpenDGD referenceapi.opendgd.org

The open core service: schema, conformance, DOCX and PDF. No account, no engine.

Core · open

a conforming validatorOpenDGD

A conforming validator that checks a declaration against the full IMDG Code and returns a validated, QR-stamped PDF.

Extended

Your implementation here

Built something that reads or writes OpenDGD? Open a pull request to be listed.

Any

What a full validator addsExtended tier

The open core gives you a well-formed declaration. A full validator takes it the rest of the way, from correctly described to demonstrably compliant.

Search, don't type

Look up any entry by UN number and its proper shipping name, hazard class and packing group fill themselves in. No hand-keying PSNs and class numbers, and none of the errors that come with it.

Packaging confirmed

Checks that the inner and outer packaging on each line is permitted for the substance under the IMDG Code, not just plausible.

Loads checked end to end

Validates the whole consignment for segregation and stowage conflicts before it sails, across every line in the unit.

The result is a fully validated DGD, checked against the full IMDG Code.

Get involved

Help set the standard for dangerous goods declarations.

Read the spec → Try the playground

OpenDGD, an open standard. The IMDG Code governs.