MN 113-7: MMEL Documentation Models

1.1. General

MMEL models capture not only process flows, data structures, and compliance requirements, but also the document content that accompanies these definitions. Document content in MMEL includes tables, figures, multimedia elements, sections, and Supplementary Document Content (SDC) files.

These documentation constructs enable MMEL models to serve as a single source of truth that combines normative text, structured data, visual diagrams, and process definitions.

1.2. Document content types

MMEL supports the following document content types:

1.3. Publication component types

MMEL documentation constructs map to the following publication component types:

1.4. Relationship to processes

Document content is associated with processes through property references:

process RiskManagementProcess {
  name "Risk management process"
  actor Manufacturer
  validate_provision {
    Provision1
  }
  note {
    Note1
    Note2
  }
  figure {
    Figure1
  }
  table {
    PermittedVoltages
    TestSchedule
  }
  subprocess Page2
}

Processes can reference multiple tables, figures, and notes. This association provides traceability from the normative document content to the process that implements or describes it.

2.1. General

Tables define structured tabular data with rows and columns. They capture normative tables from standards documents (e.g. cable specifications, test schedules, permitted voltage ratings) and store them in a format that can be referenced by processes and used for validation.

2.2. Syntax

table <TableID> {
  title "Table title"
  columns "<number>"
  display "<display-format>"
  domain {
    "<column-constraints>"
  }
  data {
    "<col1>" "<col2>" ... "<colN>"
  }
}

1. Human-readable table title.
2. Number of columns as a quoted string.
3. Display format template, or ” undefined “ if no special format.
4. Column constraint definitions -- each string constrains valid values for the corresponding column.
5. Row data -- each line contains space-separated quoted column values.

2.3. Table view and Class view

MMEL tables can be interpreted in two modes:

Table view

The table is rendered as a traditional grid of rows and columns, preserving the visual layout from the normative document. The columns field specifies the column count, and the data field contains the raw cell values in row order.

Class view

The table is interpreted as a structured data definition, where the first row defines field names and subsequent rows define data records. This view is activated when the display field uses a format template with bracketed column names (e.g. ”[Cable]: [Specification]“).

The display field determines which view is used:

• ” undefined “ -- Table view (default).
• ” [ColName1]: [ColName2] “ -- Class view, where the bracketed names identify the key columns for record identification.

2.4. Domain constraints

The domain section defines validation constraints for each column. Each string entry corresponds to a column (in order) and constrains what values are valid for that column:

domain {
  ""                // Column 1: no constraint
  ""                // Column 2: no constraint
  ""                // Column 3: no constraint
  ",1,2"            // Column 4: values "1" or "2"
  ""                // Column 5: no constraint
  ""                // Column 6: no constraint
  ""                // Column 7: no constraint
  ""                // Column 8: no constraint
  ",1,2"            // Column 9: values "1" or "2"
  ""                // Column 10: no constraint
  ""                // Column 11: no constraint
  ""                // Column 12: no constraint
  ""                // Column 13: no constraint
  "true,false"      // Column 14: boolean
  "3,4,5,6"         // Column 15: table group enumeration
}

2.5. Display format syntax

The display field uses bracketed column names to define how records are identified and displayed:

• ” undefined “ -- No special display format.
• ” [ColName1]: [ColName2] “ -- Display each record as ” Col1Value: Col2Value “ , where ColName1 and ColName2 match the column headers in the data.

The display format also signals that the table should be treated as a structured data source (Class view), enabling tools to query individual records by key fields.

2.6. Example: PermittedVoltages table

A simple reference table with no domain constraints:

table PermittedVoltages {
  title "Maximum permitted voltages against rated voltage of cable"
  columns "5"
  display "undefined"
  domain {
  }
  data {
    "Rated voltage of cable" "Maximum permanent permitted operating voltage of the system" "" "" ""
    "" "a.c." "" "d.c." ""
    "U_0 / U (V)" "Conductor-earth U_0max (V)" "Conductor-conductor U_m V" "Conductor-earth V" "Conductor-conductor V"
    "300/500" "320" "550" "410" "820"
  }
}

This table has 5 columns, no display format, and 4 rows of data including a multi-row header.

2.7. Example: TestSchedule table

A test schedule table with structured rows:

table TestSchedule {
  title "Schedule of tests"
  columns "4"
  display "undefined"
  domain {
  }
  data {
    "Test" "Requirements given in clause" "Test method" "Test category"
    "Conductor construction" "Clause 6" "BS EN 60228" "S"
    "Insulation:" "" "" ""
    "  material" "7.1" "BS EN 50363-3" "T"
    "  application" "7.2" "Visual examination and manual test" "S"
    "  thickness" "7.3" "BS EN 50396, 4.1" "S"
    "Conductor resistance" "14.2" "BS EN 60228" "R"
    "Voltage withstand" "15.4" "Annex E" "S"
  }
}

2.8. Example: Data table with Class view

A large data table with domain constraints and class view display format:

table data {
  title "Data"
  columns "15"
  display "[Cable]: [Specification]"
  domain {
    ""
    ""
    ""
    ",1,2"
    ""
    ""
    ""
    ""
    ",1,2"
    ""
    ""
    ""
    ""
    "true,false"
    "3,4,5,6"
  }
  data {
    "Cable" "Specification" "Cross-section area" "Class" "Insulation" "Sheath" "Min resistance" "CPC area" "CPC class" "Dim 1 lower" "Dim 2 lower" "Dim 1 upper" "Dim 2 upper" "Circular?" "Table group"
    "6181Y" "1 x 1.0" "1" "1" "0.6" "0.8" "0.011" "" "" "3.7" "" "4.5" "" "true" "3"
    "6181Y" "1 x 1.5" "1.5" "1" "0.7" "0.8" "0.011" "" "" "4.2" "" "5" "" "true" "3"
    "6192Y" "2 x 1.0" "1" "1" "0.6" "0.9" "0.011" "" "" "3.9" "6.1" "4.8" "7.4" "false" "3"
    "6192Y" "2 x 2.5" "2.5" "1" "0.8" "1" "0.01" "" "" "5.1" "8.4" "6.2" "10.1" "false" "3"
  }
}

In this example, the display "[Cable]: [Specification]" format indicates Class view, where each record is identified by its Cable and Specification column values. The domain constraints restrict the Class column to values "1" or "2", the Circular column to "true" or "false", and the Table group column to one of "3", "4", "5", or "6".

2.9. Export and Import CSV

MMEL-compliant tools SHOULD support exporting table data to CSV (Comma- Separated Values) format and importing CSV data into table constructs.

The CSV export format:

1. The first row contains column headers.
2. Subsequent rows contain data values.
3. Values containing commas, quotes, or newlines are enclosed in double quotes.

The CSV import process:

1. The first row is treated as column headers.
2. Subsequent rows populate the data section.
3. The columns field is set to the number of columns in the CSV.

3.1. General

Figures define images or diagrams embedded in the model as base64-encoded data. They capture visual content from normative documents (e.g. process flow diagrams, schematic representations) and store them directly within the model file.

3.2. Syntax

figure <FigureID> {
  title "Figure title"
  data "<base64-encoded-data>"
}

1. Human-readable figure title or caption.
2. Base64-encoded image data (typically PNG format).

3.3. Description

Figures store diagrammatic content from normative documents directly within the model file. The data field contains the complete base64 encoding of the image. In practice, this field can be very long (thousands of characters) as it encodes the entire binary image.

Figures are declared as top-level constructs in the .mmel file and are referenced by processes via the figure { } property.

3.4. Figures as process properties

Processes reference figures through the figure { } property block:

process GeneralRequirementsForRiskManagement {
  name "General requirements for risk management"
  actor Manufacturer
  validate_provision {
    Provision7
  }
  note {
    Note1
    Note2
  }
  figure {
    Figure1
  }
  subprocess Page1
}

A process may reference multiple figures. The association provides traceability from the process to its visual documentation.

3.5. Example

The following example is from the ISO 14971 risk management model:

figure Figure1 {
  title "Figure 1 -- A schematic representation of the risk management process"
  data "iVBORw0KGgoAAAANSUhEUgAAAnIAAAUWCAYAAAAW7F5X..."
}

3.6. Image format

The base64-encoded data typically represents a PNG image. MMEL-compliant tools:

1. SHALL support PNG image decoding for figure data.
2. SHOULD display figures inline in process documentation views.
3. MAY support other image formats (JPEG, SVG) if identified by the base64 header bytes.

4.1. General

MMEL is designed to support a range of multimedia content types beyond static figures. This clause describes the planned multimedia support and current implementation status.

4.2. Supported content types

The following multimedia content types are planned for MMEL:

4.3. Figure (implemented)

Figures are the only multimedia type currently implemented in MMEL. They use the figure construct with base64-encoded image data. See figures for full specification.

4.4. Video (future)

Video support is planned to enable embedding of instructional content, process demonstrations, and animated diagrams within MMEL models. The planned syntax would follow a similar pattern to figures:

// Planned syntax (not yet implemented)
video <VideoID> {
  title "Video title"
  data "<base64-encoded-video-data>"
  format "mp4"
}

Video content would be referenced by processes via a video { } property block, analogous to the figure { } block.

4.5. 3D model (future)

3D model support is planned for physical product visualization and spatial representation in engineering and manufacturing contexts. The planned syntax would follow a similar pattern:

// Planned syntax (not yet implemented)
model3d <ModelID> {
  title "3D model title"
  data "<base64-encoded-model-data>"
  format "glb"
}

3D models would be referenced by processes via a model3d { } property block.

4.6. Current limitations

As of this edition of the specification:

• Only the figure construct is functional. Video and 3D model constructs are not yet implemented.
• The data field for figures is limited to base64-encoded PNG images.
• There is no streaming or external referencing for large multimedia content -- all data is embedded inline in the .mmel file.
• Future editions may introduce external file references or URL-based loading for large media assets.

5.1. General

The sections construct defines document section entries used for document generation from MMEL models. Sections provide a structured way to organize document content with internal identifiers, titles, and text.

5.2. Syntax

The planned syntax for section definitions is:

section <SectionID> {
  title "Section title"
  text "Section text content"
}

1. Human-readable section title.
2. The text content of the section.

5.3. Properties

Section entries contain the following properties:

5.4. Current status

As of this edition of the specification, sections are stored in model files but do not yet have functional use in the toolchain. They are included in the model definition for future document generation capabilities.

Future editions of the specification may define:

• Section hierarchy (nested sections with parent-child relationships).
• Section ordering within generated documents.
• Section cross-referencing from processes, provisions, and notes.
• Section numbering aligned with normative document structure.
• Template-driven section rendering using Liquid templates (similar to report templates in mapping files).

5.5. Relationship to SDC files

Sections complement SDC (Supplementary Document Content) files. While SDC files store clause-level content extracted from external normative documents, sections store document content that is authored directly within the MMEL model.

6.1. General

Supplementary Document Content (SDC) files store clause-level content extracted from source normative documents. They use the .sdc file extension and provide a plain-text representation of the clauses, notes, examples, and definitions from external standards and regulations.

SDC files serve as the bridge between external normative documents and MMEL model elements, enabling traceability from provisions and references back to the original source text.

6.2. File format

An SDC file consists of two parts separated by a ### delimiter:

1. Header section -- metadata about the source document.
2. Body section -- clause-level content entries.

namespace#<NamespaceID>
title#<DocumentTitle>
version#<VersionString>
###

<clause-number>#<content-text>

6.3. Example

The following example shows an SDC file for the DPTM (Data Protection Trust Mark) certification requirements:

namespace#DPTM-doc
title#DPTM certification requirements
version#v1.0.0-dev1
###
1#Governance and Transparency
1.1#Establish data protection policies and practices
1.1.1#Governance and Transparency
1.1.1#Organisation shall have data protection policies and practices
1.1.1#approved by management,
1.1.1#setting out the organisation's approach to managing personal data (include management of special categories of personal data such as personal data of a sensitive nature) for
1.1.1#various stakeholders
1.1.1#such as:
1.1.1#- Employees - Internal data protection policy and notice
1.1.1#- Customers, Job applicants, visitors etc - External data protection notices
1.1.1#- Third party vendors - Third party agreement for management of the organisation's personal data
1.2#Establish queries, complaints and dispute resolution handling processes

In this example:

• The header declares the namespace DPTM-doc, the document title, and version.
• The ### separator divides header from body.
• Clause 1.1.1 has multiple content entries, representing the full text of that clause split across several lines.

6.4. Annotation types

Content entries may be prefixed with annotation keywords that classify the type of content:

5.1.3#NOTE This is a note providing additional context.
5.1.3#EXAMPLE This is an example illustrating the requirement.
5.1.3#DEFINITION A term being formally defined.

These annotation types correspond to the note types used in .mmel model files. The NOTE annotation maps to the note construct with type NOTE , the EXAMPLE annotation corresponds to examples in normative text, and the DEFINITION annotation corresponds to term definitions.

6.5. Relationship to note types in .mmel files

SDC annotations align with the note classification system in MMEL models:

When an SDC file is loaded alongside a model, tools can match clause content to model references, providing full traceability from provisions to their source text.

6.6. File encoding

SDC files SHALL use UTF-8 encoding. Content text is plain text (not formatted in any markup language). Line breaks within a single clause are represented as separate entries with the same clause number.