Skip to main content

Anatomy of a complete data module

Creating your first data module describes the two halves of a data module and then stops where s1kd-newdm stops: at an empty, schema-valid skeleton. This page picks it up from there and shows a filled-in one, so you can see what the elements described in the abstract actually look like carrying real content.

The example is a procedural module — a battery replacement on a small unmanned aircraft. Procedures are the best case to read first, because they exercise the parts of S1000D that descriptive modules never touch: safety requirements, nested steps, and closing conditions.

Illustrative example — read this before you copy it

The SkyHawk RQ-7 is a fictional aircraft, and this module is a teaching example, not a conformant deliverable. Two specific differences from a real project module:

  • No schema binding. A real data module declares the S1000D schema it validates against, and s1kd-validate needs that declaration. This one is plain XML so the structure stays readable.
  • No brexDmRef. As Creating your first data module notes, every real data module points at the BREX that governs it. s1kd-newdm fills that in from your .defaults.

Use it to learn the shape. Generate real modules with s1kd-newdm.

The code before the content​

Before reading a line of it, the filename tells you what this module is:

DMC-SHK-A-31-00-00-00A-520A-A_001-00_EN-US.XML

Decode it with the DMC decoder and it reads: model SHK, system 31, information code 520 — a remove procedure — issue 001, in-work 00, US English. The same fields appear again inside the file as attributes on <dmCode>, which is the point of the scheme: the identity is addressable from the filename and from the content, and the two must agree.

Spot the compromise: 520 is remove, not remove-and-install

This module contains removal and installation, but 520 means remove only — installation is the 720 family (assemble, install, connect). A real project would usually publish these as two data modules so a maintainer can reference "how do I install it" independently of "how do I take it off".

Bundling them is a common shortcut in small projects and a reasonable thing to see in the wild — but it is a shortcut, and the information code is the thing that gives it away. This is exactly the kind of drift a BREX rule is written to catch.

The metadata half​

identAndStatusSection answers which module is this and what state is it in.

<identAndStatusSection>
  <dmAddress>
    <dmIdent>
      <dmCode
        modelIdentCode="SHK"  systemDiffCode="A"
        systemCode="31"       subSystemCode="0"    subSubSystemCode="0"
        assyCode="00"         disassyCode="00"     disassyCodeVariant="A"
        infoCode="520"        infoCodeVariant="A"  itemLocationCode="A"/>
      <language languageIsoCode="en" countryIsoCode="US"/>
      <issueInfo issueNumber="001" inWork="00"/>
    </dmIdent>
    <dmAddressItems>
      <issueDate year="2024" month="01" day="15"/>
      <dmTitle>
        <techName>Battery Pack</techName>
        <infoName>Removal and Installation</infoName>
      </dmTitle>
    </dmAddressItems>
  </dmAddress>
  <dmStatus>
    <security securityClassification="01"/>
    <responsiblePartnerCompany><enterpriseName>TechWriter Demo</enterpriseName></responsiblePartnerCompany>
    <originator><enterpriseName>TechWriter Demo</enterpriseName></originator>
    <applic>
      <displayText><simplePara>All SkyHawk RQ-7 variants</simplePara></displayText>
    </applic>
    <qualityAssurance><firstVerification verificationType="tabtop"/></qualityAssurance>
  </dmStatus>
</identAndStatusSection>

Two details worth pausing on:

  • <dmTitle> is split in two. techName is the thing ("Battery Pack") and infoName is what you are being told about it ("Removal and Installation"). Publication tools compose page titles and tables of contents from the pair, so writing the whole title into techName breaks downstream output.
  • <applic> carries applicability. Here it is prose covering every variant. On a real fleet this is where "only aircraft with mod 4471 embodied" is expressed — see Applicability.

The content half​

content holds the information, and its allowed shape depends on the schema the information code selected. A 520 resolves to the procedural schema, which has three parts in a fixed order.

1. Preliminary requirements — what must be true first​

<preliminaryRqmts>
  <reqCondGroup><noConds/></reqCondGroup>
  <reqSupportEquips><noSupportEquips/></reqSupportEquips>
  <reqSupplies><noSupplies/></reqSupplies>
  <reqSpares><noSpares/></reqSpares>
  <reqSafety>
    <safetyRqmts>
      <warning>
        <warningAndCautionPara>
          Make sure that the aircraft is powered off before you remove the battery.
          The propellers can cause serious injury if the motors start.
        </warningAndCautionPara>
      </warning>
      <caution>
        <warningAndCautionPara>
          Do not drop the battery.
          A damaged battery can catch fire.
        </warningAndCautionPara>
      </caution>
    </safetyRqmts>
  </reqSafety>
</preliminaryRqmts>

The empty elements are not filler. <noConds/>, <noSupportEquips/>, <noSupplies/>, <noSpares/> are explicit assertions that nothing is required — different from omitting the element, which would mean the question was never answered. In a safety-critical document that distinction matters, and BREX rules routinely require the positive form.

Note the placement: warnings and cautions sit in preliminaryRqmts, before any step. A hazard that applies to the whole task belongs here, not buried at step 6.

2. Main procedure — nested steps​

<proceduralStep>
  <title>Removal</title>
  <para>Do this procedure to remove the battery pack.</para>

  <proceduralStep>
    <para>Make sure that the power switch is in the OFF position.</para>
    <note><notePara>The power switch is on the rear of the fuselage.</notePara></note>
  </proceduralStep>

  <proceduralStep>
    <para>Pull the battery pack down and out of the battery bay.</para>
    <caution>
      <warningAndCautionPara>
        Support the battery as you remove it.
        Do not let the battery fall.
      </warningAndCautionPara>
    </caution>
  </proceduralStep>
</proceduralStep>

proceduralStep nests, and the nesting is the numbering — a publication tool derives 1, 1.1, 1.2 from the tree rather than from numbers you type. A step-local <caution> attaches to the step it sits inside, which is how a hazard that only applies to one action is scoped.

3. Closing requirements — how you know it worked​

<closeRqmts>
  <reqCondGroup>
    <reqCondNoRef><reqCond>Battery is securely installed</reqCond></reqCondNoRef>
    <reqCondNoRef><reqCond>Battery latch is engaged</reqCond></reqCondNoRef>
  </reqCondGroup>
</closeRqmts>

The verifiable end state. A procedure that stops after the last action leaves the maintainer with no defined way to confirm success — closeRqmts is where that is written down.

The prose is Simplified Technical English​

Read the step text again and note what it does not do. Sentences are short. Every instruction is imperative — Make sure, Pull, Hold, Push. Nothing is passive. There is no utilize, ensure, prior to, or adjacent to.

That is ASD-STE100 applied, and it is the norm for this kind of content — S1000D governs the structure, STE governs the words inside it. Paste any step above into the STE checker and it will come back clean; paste an ordinary technical rewrite of the same instruction and it will not.

Download it​

DMC-SHK-A-31-00-00-00A-520A-A_001-00_EN-US.XML

Open it beside Creating your first data module and Validating against schema & BREX. Remember it has no schema binding, so s1kd-validate will not accept it as-is — that is the first thing to add if you want to take it further.

Sources​

Last updated on