MMEL Authoring Guide

1.1. Creating a new model from scratch

A new MMEL model is created within a repository. The model is identified by a namespace that serves as a unique identifier across the system.

namespace BS6004

model BS6004 <1.0.0> {
  title "Electric cables — Thermoplastic insulated and sheathed cables
         for voltages up to and including 300/500 V"
  shortname "BS 6004"
  author "BSI"
  namespace BS6004
}

1.2. Converting an existing standard to a model

MMEL supports importing content from existing standards documents to accelerate the modeling process.

provision P_9_2_1_a {
  text "The organization SHALL conduct internal audits at planned intervals"
  modality SHALL
  reference BS202000_9_2_1
}

2.1. Model Editor interface

The Model Editor interface consists of the following areas:

2.2. Saving the model

The Model Editor provides multiple levels of saving:

3.1. Metadata

Model metadata is configured through the Model Editor under Model Settings > Metadata .

The metadata fields identify and describe the model:

3.2. Sections

Sections represent structural parts of the source document used for document generation. Each section has:

• An internal ID (unique within the model)
• A title
• Text contents

Sections correspond to clauses, subclauses, and annexes in the source standard.

section S_1 {
  id "1"
  title "Scope"
  text "This document specifies requirements for..."
}

3.3. Terms and definitions

Terms and definitions capture the terminology used in the source document.

Each term entry includes:

term T_cable {
  term "cable"
  admitted "cable assembly"
  definition "length of insulated conductor(s)..."
  note "Cables may include one or more conductors."
}

3.4. Roles

Roles represent the actors and approvers involved in the modeled processes. Each role has:

• A unique Role ID
• A display name

Roles are referenced by processes (as actors) and by approvals (as approvers).

role Organization {
  display_name "The organization"
}
role TopManagement {
  display_name "Top management"
}

A process references a role via the actor keyword:

process ConductAudit {
  actor Organization
}

An approval references both an actor and an approver:

approval ApproveAuditResults {
  actor Organization
  approver TopManagement
}

3.5. References

References link model elements to specific clauses in external standards or documents. Each reference specifies:

Batch insertion is supported, allowing multiple references to be created at once from a list of clause numbers.

reference BS202000_9_2_1 {
  document "BS 202000"
  clause "9.2.1"
  title "Internal audit"
}

3.6. Data registries

A data registry is a data store identified by an ID and display name. It is backed by a data class that defines its structure.

Each attribute in the registry has:

• Cardinality -- whether the attribute is singular or multiple (e.g., 1..1, 0..*)
• Modality -- the RFC 2119 modality if the attribute represents a requirement
• Type -- the data type of the attribute (see #attribute-types)

data_registry RiskPlan {
  display_name "Risk Plan"
  data_class RiskPlan#data
}

3.7. Attribute types

The following attribute types are available:

3.8. Data classes

Data classes define custom data structures. They differ from data registries in a key way:

• A data registry is a data store that persists data instances.
• A data class is a structural definition used to define the shape of data.

class RiskPlan#data {
  attribute name : String [1..1]
  attribute description : String [0..1]
  attribute approved : Boolean [1..1]
}

3.9. Enumerations

Enumerations define a drop-down list of possible values. They are used to constrain attribute values to a predefined set.

enum CableType {
  value "Single-core"
  value "Multi-core"
  value "Flexible"
}

3.10. Measurements and view profiles

Measurements define quantitative variables that can be used in process tests and gateway conditions.

For detailed instructions on creating and using measurements, refer to the MMEL Modeling Methodology Guide .

3.11. Tables

Tables serve dual purposes in MMEL:

• Visual tabular content -- displayed as part of the model documentation
• Internal database -- used to store structured data that can be queried by measurements

Tables can be viewed in two ways:

• Table view -- displays the data in a traditional tabular grid
• Class view -- displays the data structured according to its backing data class

Tables support CSV export and import for data exchange with external tools.

3.12. Multimedia

MMEL supports the following multimedia types:

4.1. Flow components

There are 7 flow components available for building diagrams:

4.2. Process

A Process is the primary component for representing activities in a flow.

process ConductAudit {
  actor Organization
  input_registry AuditRecords
  output_registry AuditReport
}

process ConductAudit {
  actor Organization
  validate_provision P_9_2_1_a
  note "Internal audits must be conducted at planned intervals."
}

process TestCable {
  measurement_test "[tm] <= 0.9 * [tn] - 0.1"
}

process ReviewResults {
  link URL "https://example.com/audit-guidance"
  link Repo "BS202000"
}

4.3. Approval

An Approval component represents a decision point where an actor seeks approval from an approver.

approval ApproveAudit {
  actor Organization
  approver TopManagement
  modality SHALL
}

The approval creates an approval record that documents the decision.

4.4. Start event

The Start event marks the beginning of a flow. Each diagram has exactly one Start event.

• No editing is required -- the Start event is automatically placed when a diagram is created.
• It cannot be deleted.

4.5. End event

The End event marks the termination of a flow. It is placed at the end of each path through the diagram.

• End events are deletable.
• A diagram may have multiple End events when different paths terminate independently.

4.6. Timer event

A Timer event represents a time-based trigger. Two modes are supported:

timer_event PlannedIntervals {
  mode REPEAT
  value "12 months"
}

4.7. Signal event

A Signal event captures an external signal that triggers a process. Signals are used to model event-driven behavior where a process waits for a specific external condition.

4.8. Gateway

Gateways provide conditional branching in the flow. They control which path(s) are taken based on conditions.

edge Gateway1_to_ProcessA {
  description "Conforms to requirements"
}

edge Gateway1_to_ProcessA {
  condition "[sterile] = 'true'"
}

4.9. Process reuse

A single process component can appear in multiple diagrams. This is achieved through referencing -- all instances of the process share the same definition.

5.1. Document import workflow

The document import workflow follows these steps:

1. Load the source document text into the editor
2. Review the loaded content and identify sections to convert
3. Select text elements and convert them to model components
4. Verify the imported components and adjust as needed

5.2. Loading text from reference documents

To begin, load the text of the reference document (the standard being modeled) into the Document Import interface. The editor parses the document structure, identifying:

• Clauses and subclauses
• Paragraphs and lists
• Tables and figures
• Terminology sections

The parsed content is presented for selection and conversion.

5.3. Selecting and converting text to model components

Select portions of the loaded text and choose the target component type. The supported conversions include:

5.4. Auto-creating references from clause numbers

When text is imported, any clause numbers detected in the content are automatically converted into references. For example, text containing "as specified in clause 9.2.1" will create a reference to clause 9.2.1 of the source document.

5.5. Importing provisions with auto-detected modality

Provisions are imported with their RFC 2119 modality keyword automatically detected from the source text:

The detected modality is assigned to the provision, and the provision is linked to the corresponding reference in the source document.

5.6. Suggestions for document import

The following practices help ensure accurate and efficient document import:

• Review each imported component -- auto-detection is helpful but may misinterpret context. Verify that each provision's modality and reference are correct.
• Import in logical order -- start with structural components (sections, terms), then import provisions. This ensures that references and terms are available when provisions are created.
• Use batch operations -- when multiple references or terms can be imported at once, use batch insertion to save time.
• Preserve original wording -- the text of imported provisions should maintain the exact wording from the source document. Do not paraphrase or summarize.
• Check coverage -- after import, verify that all requirements in the source document have corresponding provisions in the model. The coverage should be 100%.
• Verify cross-references -- ensure that all clause references detected during import are correctly linked to the appropriate reference entries.