Creating your first data module

A data module (DM) is the atomic unit of S1000D. It is a self-contained XML file. It holds its own identification and status metadata, plus the content itself. Each data module has a unique Data Module Code (DMC).

The s1kd-tools toolchain creates new data modules with the s1kd-newdm command. This page walks through one creation and explains what the generated XML skeleton contains.

Commands are illustrative

The command lines below are examples. They match the s1kd-tools documentation, but exact codes, options, and output names depend on your project. Always check the tool reference for your installed version.

Set up project defaults (once)

s1kd-newdm does not require every value on the command line. Information you do not pass is read from two project configuration files:

File	Used by	Purpose
.defaults	all s1kd-new* tools	Default metadata values (security, originator, language, country, and so on).
.dmtypes	s1kd-newdm	Maps information codes to info names and content schemas.

You initialize both files once, at the root of your CSDB folder:

# Example: create starter .defaults and .dmtypes files
s1kd-defaults -i

The CSDB can be a plain folder

The Common Source Database (CSDB) stores every information object. For a small project it can be a simple folder on your computer. The .defaults and .dmtypes files live at that folder's root.

Create the data module

Use s1kd-newdm and pass the data module code with the -# (or --code) option. The DMC- prefix is optional.

# Example command (illustrative DMC)
s1kd-newdm -# MYPRJ-A-00-00-00-00A-040A-D

This writes a new file to the current folder. The tool builds the file name from the code, issue, and language. For the example above it produces a file named like:

DMC-MYPRJ-A-00-00-00-00A-040A-D_000-01_EN-CA.XML

How the code maps to DMC fields

The DMC packs the data module's identity into a fixed structure. Reading the example code left to right:

DMC field	Example value	Meaning
Model Identification Code	MYPRJ	The project or product.
System Difference Code	A	Variant of the system.
Standard Numbering System (SNS)	00-00-00	System → subsystem → sub-subsystem.
Disassembly Code (+ variant)	00A	The assembly being described.
Information Code (+ variant)	040A	The kind of information. 040 is a description.
Item Location Code	D	Where the item sits for this information.

Information codes tell you the job

The information code is the heart of the DMC. 000 covers function and description, 200 servicing, 500 remove/disassemble, 700 install, and so on. See the Information Codes reference for the full set.

Useful options

A few common s1kd-newdm options:

Option	Long form	Effect
-#	--code	Set the data module code. Use - for a random code.
-i	--infoname	Set the info name.
-L	--language	Set the language ISO code.
-C	--country	Set the country ISO code.
-$	--issue	Choose the S1000D issue to target (default: 6).
-B	--generate-brex-rules	When creating a BREX data module, populate it with a basic set of rules from your .defaults and .dmtypes.

What makes a data module a BREX is its information code (022), resolved through .dmtypes — not the -B flag. The -B flag only seeds the new BREX with a starter rule set. For example, to create a BREX data module (the module that holds a project's business rules):

# Example: create a BREX data module
s1kd-newdm -B -# MYPRJ-A-00-00-00-00A-022A-D

What the XML skeleton contains

Every data module has two top-level parts: the identAndStatusSection (metadata) and the content (the information). s1kd-newdm generates both as an empty, schema-valid skeleton that you then fill in.

identAndStatusSection — the metadata

This section answers which module this is and what state it is in. It splits into two parts:

• dmAddress — the identity. It holds the dmCode (the DMC fields), the language, the issueInfo (issue and in-work number), the issue date, and the title (technical name and info name).
• dmStatus — the status. It holds the security classification, the responsible partner company, the originator, applicability, the reference to the governing BREX data module, and quality assurance state.

Every data module points at a BREX

The dmStatus part carries a brexDmRef. This links the data module to the BREX that defines the project's business rules. Content is later validated against that BREX. s1kd-newdm fills this reference from your .defaults.

content — the information

The content section holds the actual technical information. Its allowed structure depends on the schema the information code selects:

Module type	Typical content elements
Descriptive	Levelled paragraphs and titles (for example levelledPara, title).
Procedural	Ordered steps (for example proceduralStep).

The freshly created module starts with an empty content shell for its schema. You add the real text and structure next, in an XML editor or with other s1kd-tools.

Validate what you made

After you edit the module, check that it is still valid:

# Example: validate against the S1000D schema
s1kd-validate DMC-MYPRJ-A-00-00-00-00A-040A-D_000-01_EN-CA.XML

# Example: validate the content against the project BREX
s1kd-brexcheck DMC-MYPRJ-A-00-00-00-00A-040A-D_000-01_EN-CA.XML

s1kd-validate checks the file against its S1000D XML schema. s1kd-brexcheck checks it against the business rules in the referenced BREX.

Next steps

• Validating against a BREX — enforce your project's business rules.
• The Data Module Code (DMC) — a deeper look at each field.

Sources

• s1kd-tools — Usage examples (EXAMPLE) — s1kd-newdm -# …, .defaults/.dmtypes, s1kd-defaults -i, generated file names.
• s1kd-tools — GitHub repository — the open-source toolchain this site documents.
• s1kd-newdm reference (kibook/s1kd-tools) — s1kd-newdm options (-#/--code, -i/--infoname, -L/--language, -C/--country, -$/--issue with default issue 6, -B/--generate-brex-rules).
• s1kd-defaults reference (kibook/s1kd-tools) — s1kd-defaults -i initializes .defaults/.dmtypes.
• S1000D — Wikipedia — data module, DMC, and identification/content structure.