Parcel is the canonical Excel workbook format for exchanging CDD content, defined by IEC 62656-1. It is what IEC’s ParcelMaker tool produces, what the cdd.iec.ch bulk-download endpoints serve, and what committee members exchange during standards development.

OpenCDD reads every Parcel shape ParcelMaker 5.2+ emits and writes xlsx that re-reads to a semantically equal database. This page explains the format and how to use the OpenCDD tooling to read and write it.

File extensions

.xls writing is intentionally unsupported — ParcelMaker itself stopped writing .xls after 5.2.1. Modern exchange uses .xlsx.

Workbook structure

A Parcel workbook is a single .xlsx file containing reserved sheets plus per-dictionary sheets.

Reserved sheets

Project

A single-row metadata sheet identifying the workbook:

sheetmap

The authoritative index of every parcel sheet in the workbook. One row per sheet:

pcls_LOCAL

A flat registry of dictionaries included in this workbook:

Per-dictionary sheets

Named <PARCEL_ID>_<TYPE>. For example, IEC62683_CLASS contains class definitions for the IEC 62683 dictionary. Each type maps to a CDD meta-class:

Sheet layout

Every per-dictionary sheet follows the same structure: a 12-row header block, then one data row per entity.

Class header (rows 1–5)

Anchors the sheet to its meta-class. Readers must match by label in column A, not by absolute row number — row positions drift between ParcelMaker versions.

Schema header (rows 6–12)

One column per property. Column A holds the directive label; columns B onwards hold per-property metadata. The column order is NOT normative — readers must map by property ID, not by position.

Additional directive rows may appear (DATATYPE, UNIT, VALUE_FORMAT, PATTERN, RELATION, DEFAULT_VALUE, etc.) depending on the sheet type.

Property ID mapping

ParcelMaker uses variant property IDs that differ from the canonical IEC 61360 identifiers. The OpenCDD tooling handles this mapping automatically:

Data rows (row 13+)

Each row from row 13 onward is one entity instance. Column positions match the schema header above. Multilingual cells use the <value>.<lang> convention within the cell, or separate columns per language (ParcelMaker variant-dependent).

A typical CLASS sheet has columns for:

MDC_P001_5 (code)     MDC_P002_1 (version)  MDC_P004_1 (pref name)
MDC_P005 (definition)  MDC_P010 (superclass) MDC_P011 (class_type)
MDC_P013 (is_case_of)  MDC_P014 (applicable) MDC_P090 (imported)

On-disk layouts

The OpenCDD tooling reads three physical layouts:

1. Single workbook (.xlsx)

The ParcelMaker default. One file, all sheets. Read with WorkbookReader:

wb = Opencdd::Parcel::WorkbookReader.from_path("IEC62683.xlsx")
db = Opencdd::Parcel::FlatDirReader.new(wb).to_database

2. Flat directory (legacy .xls)

Six separate .xls files (one per entity type) in a directory. Used by older IEC CDD exports. Read with FlatDirReader.

3. Sharded directory (harvester output)

Per-class subdirectories containing individual .xls exports from cdd.iec.ch. Each subdirectory is one entity’s raw export. Read with ShardedDirReader. This is the format used by the OpenCDD data pipeline.

4. Versioned directory (time-travel)

Per-entity version files in a versions/<code>/ subdirectory. Each file is a JSON snapshot of the entity at one point in time. Read with VersionedReader. This is what powers the browser’s version timeline and diff features.

Reading Parcel files

Ruby (opencdd gem)

require 'opencdd'

# Auto-detect layout (xlsx, flat-dir, or sharded-dir)
db = Opencdd::Database.load("path/to/parcel/")

# Read a specific xlsx file
wb = Opencdd::Parcel::WorkbookReader.from_path("IEC62683.xlsx")
reader = Opencdd::Parcel::FlatDirReader.new(wb)
db = reader.to_database

# Access entities
db.classes.each { |klass| puts "#{klass.code}: #{klass.preferred_name}" }
db.properties.each { |prop| puts "#{prop.code}: #{prop.preferred_name}" }

TypeScript (@opencdd/opencdd)

import { Parcel, Database } from "@opencdd/opencdd";

// Read an xlsx workbook
const reader = Parcel.WorkbookReader.fromPath("IEC62683.xlsx");
const db = reader.toDatabase();

// Access entities
for (const klass of db.classes) {
  console.log(`${klass.code}: ${klass.preferredName("en")}`);
}

Writing Parcel files

Ruby

Opencdd::Parcel::Writer.new(db).write(
  "output.xlsx",
  parcel_id: "MY_DICT",
  project_id: "MY_PROJECT",
  source_language: "en",
  translation_languages: %w[fr ja],
)

The writer produces a ParcelMaker-compatible .xlsx with the Project, sheetmap, and pcls_LOCAL sheets populated automatically. Each entity-type sheet includes the correct 12-row header and all data rows.

Relationship to CDDAL

Parcel and CDDAL are sibling formats — both represent the same in-memory model:

Parcel xlsx  ⇄  Ruby model  ⇄  CDDAL text
                   ⇅
                JSON wire format

• Parcel is the IEC standard exchange format (binary, committee-facing).
• CDDAL is the OpenCDD authoring format (plain text, developer-facing).
• JSON is the wire format used between tools (machine-readable).
• All three round-trip losslessly through the same model.

See the CDDAL documentation for the plain-text format specification.

The Parcel format is defined by IEC 62656-1. The OpenCDD tooling reads and writes it without modification. For the canonical format specification, see the IEC webstore.