MN 113-6: MMEL Cross-model Mapping

1.1. General

Cross-model alignment is a fundamental capability of MMEL that enables traceability between different standards, regulations, and organizational implementation models. A single organization typically needs to demonstrate compliance with multiple standards simultaneously, and MMEL provides the mechanisms to express how processes in one model correspond to processes in another.

This document specifies the two mechanisms MMEL provides for cross-model alignment:

1. Inline constructs within `.mmel` files -- the link construct and map_profile construct embedded directly in model definitions.
2. External `.map` files -- separate JSON files that define comprehensive process-to-process mappings with descriptions and justifications.

1.2. Reference model and implementation model

In the MMEL ecosystem, models fall into two broad categories:

Reference model

A model that represents a standard, regulation, or specification as published by a standards body. It defines the "what" -- the requirements and processes that conforming organizations must fulfil. Reference models use provisions with modality keywords and normative references to express mandatory and recommended requirements.

Implementation model

A model that represents how a specific organization implements one or more reference standards. It defines the "how" -- the concrete processes, data registries, and organizational roles that the organization uses to comply. Implementation models use map_profile or .map files to declare which of their processes satisfy which reference model processes.

The mapping relationship is directional: implementation model processes are mapped to reference model processes, indicating that fulfilling the implementation process implies fulfilling the reference requirement.

+---------------------+          +---------------------+
| Implementation      |          | Reference           |
| Model (.mmel)       |          | Model (.mmel)       |
|---------------------|          |---------------------|
| role Org { }        |          | role Manufacturer   |
| process Procurement |  <=====  | process SCM { }     |
|   map_profile { }   |  .map   | provision P1 { }    |
|   links { }         |  file   | reference R1 { }    |
+---------------------+          +---------------------+
         |                                |
         | workspace (.sws)               | SDC (.sdc)
         v                                v
  +-------------+                  +-------------+
  | Runtime     |                  | Normative   |
  | Evidence    |                  | Source      |
  +-------------+                  +-------------+

1.3. Toolchain overview

The MMEL cross-model mapping toolchain supports the following workflow:

1. Author reference models and implementation models as .mmel files.
2. Define cross-model mappings using either map_profile blocks within .mmel files or separate .map files.
3. Validate mapping completeness using coverage analysis (see mapping-coverage).
4. Discover implicit mappings through transitive and inherited mapping logic (see auto-mapping).
5. Generate compliance reports using the report template system with Liquid templates (see report-templates).

MMEL-compliant tools SHALL be able to parse both map_profile blocks and .map files. Tools SHOULD be able to perform coverage analysis and auto-mapping discovery. Tools MAY support report template generation.

1.4. Normative references

• RFC2119, Key words for use in RFCs to Indicate Requirement Levels, March 1997.
• RFC8174, Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words, May 2017.

2.1. General

The link construct defines a cross-model reference, allowing a process to point to a related external model, repository, or web resource. Links are declared as top-level elements in a .mmel file and referenced by processes via the links { } property.

Links provide a lightweight mechanism for declaring that a process has a relationship to an external model or resource, without specifying the detailed element-to-element correspondence that map_profile or .map files provide.

2.2. Syntax

link <LinkID> {
  title "Link title"
  description "Link description"
  link "target-identifier"
  type REPO | URL
}

1. Human-readable title for the link.
2. Description of the linked resource.
3. The target identifier. Interpretation depends on the link type.
4. The link type, which determines how the link field is interpreted.

2.3. Link types

MMEL defines the following link types:

2.4. Link type: REPO

The REPO link type is used to reference another MMEL model. The link field contains the namespace identifier of the target model as declared in its metadata.namespace field.

This is the primary link type for cross-model navigation, enabling tools to resolve and load the referenced model.

link Link1 {
  title "ISO 13485 Clause 7"
  description "Medical devices -- Quality management systems -- Requirements for regulatory purposes"
  link "BS13485"
  type REPO
}
link Link2 {
  title "ISO 13485 clause 8.2"
  description "Medical devices -- Quality management systems -- Requirements for regulatory purposes"
  link "BS13485"
  type REPO
}

In this example, both links reference the BS13485 namespace, indicating that the processes using these links relate to the ISO 13485 model. The title and description fields provide context about which specific clauses are relevant.

2.5. Link type: URL

The URL link type references an external web resource. The link field contains the full URL.

link Link1 {
  title "Data Protection Notice Generator"
  description "Data Protection Notice Generator"
  link "https://apps.pdpc.gov.sg/dp-notice-generator/introduction"
  type URL
}

2.6. Link type: TABLE_REFERENCE

The TABLE_REFERENCE link type references an internal table within the current model. The link field contains the identifier of the referenced table construct.

link TableLink1 {
  title "Reference to permitted voltages table"
  description "Cross-reference to voltage ratings table"
  link "PermittedVoltages"
  type TABLE_REFERENCE
}

2.7. Link usage in processes

Processes reference links via the links { } property block. A process may reference multiple links:

process IncorporateProductRealization {
  name "Incorporate product realization process"
  validate_provision {
    Provision6
  }
  links {
    Link1
  }
}
process ProductionAndPost-productionInformation {
  name "Production and post-production information"
  actor Manufacturer
  validate_provision {
    Provision5
    Provision84
  }
  links {
    Link2
  }
  subprocess Page15
}

The links property does not imply a mapping; it merely declares an associative relationship. For detailed element-to-element alignment, use map_profile or .map files.

3.1. General

The map_profile construct defines element-to-element mappings from the current model to another model, embedding cross-model alignment directly within the .mmel file. This provides an inline alternative to external .map files for cases where the mapping is simple or where it is convenient to co-locate the mapping with the model definition.

3.2. Syntax

map_profile <TargetNamespace> {
  mapping {
    from <SourceElementID>
    to <TargetElementID>
  }
  mapping {
    from <SourceElementID>
    to <TargetElementID>
  }
  // ... additional mapping blocks
}

1. The source element ID. May use cross-model Namespace#ElementID notation to reference elements from an external model.
2. The target element ID in the target model (identified by <TargetNamespace>).

3.3. Description

The map_profile identifier is the namespace of the target model. Each mapping block within the profile defines a single element-to-element correspondence. The from field specifies the source element, and the to field specifies the corresponding element in the target model.

Multiple map_profile blocks may appear in a single .mmel file, each targeting a different namespace.

3.4. Cross-model namespacing in from fields

The from field supports the Namespace#ElementID notation for referencing elements that originate from another model. This is particularly useful in implementation models that import elements from a reference model and then map them to local processes.

When the from field uses Namespace#ElementID notation:

• The namespace prefix (before #) identifies the source model.
• The element ID (after #) identifies the specific element within that model.
• This indicates that the mapping originates from an element in the referenced model rather than a locally defined element.

When the from field uses a plain identifier (without # ):

• The element is assumed to be defined locally in the current model.
• The mapping indicates that the local element corresponds to the target model element.

3.5. Example

The following example is taken from an implementation model ( BS20400impl(mapped).mmel ) that maps its local processes to the BS 20400 reference model:

map_profile BS20400 {
  mapping {
    from totalCostOfOwnership
    to TotalCostOfOwnership
  }
  mapping {
    from BS20400#MonetizedExternalities
    to MonetizedExternalities
  }
  mapping {
    from GiveRating
    to PrequalifySuppliers
  }
  mapping {
    from SupplierExperience
    to PrequalifySuppliers
  }
  mapping {
    from SupplierFeedback
    to PrequalifySuppliers
  }
  mapping {
    from FormPanel
    to PrequalifySuppliers
  }
  mapping {
    from AwardContract
    to AwardContract
  }
  mapping {
    from GovernmentRequirement
    to ConsultStakeholders
  }
  mapping {
    from ReviewDemand
    to AdaptRecommendations
  }
  mapping {
    from ReviewDemand
    to EngageStakeholdersSupport
  }
  mapping {
    from Process1
    to AggregateDemand
  }
}

In this example:

• The map_profile targets namespace BS20400, indicating alignment with the BS 20400 reference model.
• from totalCostOfOwnership to TotalCostOfOwnership maps a local process to a process in the BS 20400 model.
• from BS20400#MonetizedExternalities to MonetizedExternalities uses cross-model namespacing to reference an element imported from the BS 20400 model.
• Multiple from entries can map to the same to target (e.g. GiveRating, SupplierExperience, SupplierFeedback, and FormPanel all map to PrequalifySuppliers), indicating that several implementation processes together satisfy one reference process.
• A single from entry can also map to multiple targets via separate mapping blocks (e.g. ReviewDemand maps to both AdaptRecommendations and EngageStakeholdersSupport).

3.6. Relationship to .map files

map_profile provides inline mappings within the model file itself, while .map files provide external mappings in JSON format. The two mechanisms are complementary:

• Use map_profile for simple, co-located mappings where the mapping is closely tied to the model definition.
• Use .map files for complex mappings that include descriptions, justifications, and report templates, or where the mapping is maintained separately from the model.

4.1. General

The .map file format is a JSON-based format for defining comprehensive process-to-process mappings between models. Unlike the inline map_profile construct, .map files support rich metadata including descriptions, justifications, and report template definitions.

.map files are the primary mechanism for expressing standards alignment and implementation traceability in MMEL. They are used when mappings need to be maintained separately from the model definition, or when additional metadata (descriptions, justifications, report templates) is required.

4.2. File extensions

MMEL mapping files use the .map extension by convention. Files with the .json extension containing MMEL_MAP format data are also accepted. The content structure is identical regardless of extension.

4.3. Structure

A .map file contains the following top-level fields:

4.4. mapSet structure

The mapSet object contains one entry per target model namespace. Each entry has the following structure:

{
  "mapSet": {
    "defaultns": {
      "id": "defaultns",
      "mappings": {}
    },
    "<TargetNamespace>": {
      "id": "<TargetNamespace>",
      "mappings": {
        "<SourceProcessID>": {
          "<TargetProcessID>": {
            "description": "...",
            "justification": "..."
          }
        }
      }
    }
  }
}

1. The defaultns entry is always present and represents the default (local) namespace. Its mappings are typically empty.
2. One entry per target model namespace.
3. The source model process ID.
4. The target model process ID.
5. Description of how the source process fulfils the target process requirement.
6. Justification evidence or references supporting the mapping.

4.5. Mapping entries

Each mapping entry maps a source process to a target process with supporting metadata:

A source process may map to multiple target processes, and multiple source processes may map to the same target process.

4.6. docs template entries

The docs field contains report template definitions used for document generation. Each template entry defines a Liquid template that generates a compliance document (e.g. Statement of Applicability) from the mapping data.

The structure of the docs field is:

{
  "docs": {
    "<template-id>": {
      "id": "<template-id>",
      "name": "",
      "datatype": "role",
      "title": "Document Title",
      "content": "<Liquid template content>"
    }
  }
}

See report-templates for detailed specification of the report template system.

4.7. Complete JSON example

The following is a complete .map file example from an ISO 27001 implementation:

{
  "@context": "https://bsi-ribose-smart.org",
  "@type": "MMEL_MAP",
  "id": "",
  "mapSet": {
    "defaultns": {
      "id": "defaultns",
      "mappings": {}
    },
    "ISOIEC27001": {
      "id": "ISOIEC27001",
      "mappings": {
        "CrimsonRequirements": {
          "UnderstandContext": {
            "justification": "Roles are defined in 4.1.6.",
            "description": "Yes. To establish, implement, operate, monitor, review, maintain and improve a documented ISMS that covers all relevant external and internal issues."
          },
          "RiskAndOpportunitiesActions": {
            "justification": "Defined in 6.1.",
            "description": "Yes. To determine the risks and opportunities that need to be addressed in the ISMS."
          }
        },
        "CrimsonContext": {
          "Understandneeds": {
            "justification": "Defined in 11.",
            "description": "Yes. To establish, implement, operate, monitor, review, maintain and improve a documented ISMS that covers all relevant needs and expectations of interested parties."
          },
          "ISMS": {
            "justification": "Defined in 7.2.",
            "description": "Yes. To establish, implement, operate, monitor, review, maintain and improve a documented ISMS in accordance with the requirements of ISO/IEC 27001:2013 Clauses 4 to 10."
          }
        },
        "SoA": {
          "DetermineScope": {
            "justification": "Defined in the Statement of applicability (SoA)",
            "description": "Yes. To determine the boundaries, applicability and scope of the ISMS."
          }
        }
      }
    }
  },
  "docs": {
    "applicability-main": {
      "id": "applicability-main",
      "name": "",
      "datatype": "role",
      "title": "ISO/IEC 27001:2013 Statement of Applicability",
      "content": "=== Statement of applicability\n\n..."
    }
  },
  "version": "v1.0.0-dev1"
}

4.8. .json files as alternative extension

Files with the .json extension may also contain MMEL_MAP format data, identical in structure to .map files. The .json extension is an acceptable alternative to .map for mapping files. The version field is required in all MMEL_MAP files regardless of file extension.

MMEL-compliant tools SHALL treat .map and .json files containing the @type: "MMEL_MAP" field identically.

5.1. General

This clause defines the formal semantics of MMEL mappings. Understanding these semantics is essential for correctly interpreting mapping data, performing coverage analysis, and generating compliance reports.

5.2. Mapping directionality

A mapping A => B means that fulfilling process A implies fulfilling ALL requirements of process B. The direction is from the implementation (source) to the reference (target):

Implementation Process A  ====>  Reference Process B
       "fulfils"                   "requires"

This means:

• If an organization performs process A in a compliant manner, it has satisfied the requirements of process B.
• The mapping assertion is a claim made by the implementer, supported by description and justification evidence.

5.3. Non-transitivity at model level

Mappings are NOT transitive at the model level. If model X maps process A to process B in model Y, and model Y maps process B to process C in model Z, it does NOT automatically follow that model X maps process A to process C.

Rationale: Each mapping is an independent claim with its own justification. Transitivity would combine justifications from different contexts without explicit validation.

Model X (Implementation)        Model Y (Standard)         Model Z (Regulation)
process A                       process B                  process C
    |                               |                          ^
    +-- X.map: A => B --+           |                          |
                               Y.map: B => C -----------------+
                               (does NOT imply X: A => C)

To create a valid mapping from A to C, an explicit mapping entry with its own justification MUST be created.

5.4. Transitivity at process level

While model-level mappings are non-transitive, transitivity DOES apply within a single model's process hierarchy at the process level:

If process A is mapped to process B, and process B is mapped to process C, and all three processes exist within the same model's process tree, then A => C holds at the process level.

Process A (mapped to B)
  |
  +-- subprocess containing B (mapped to C)
        |
        +-- implies A => C (within same model hierarchy)

This enables the auto-mapping discovery system (see auto-mapping ) to infer additional mappings from explicitly declared ones.

5.5. Many-to-many mappings

MMEL supports many-to-many mapping relationships:

• A single source process may map to multiple target processes.
• Multiple source processes may map to the same target process.
• Both patterns may occur simultaneously.

Source Process X  ==>  Target Process M
Source Process X  ==>  Target Process N
Source Process Y  ==>  Target Process M

In this example:

• Process X fulfils requirements of both M and N.
• Processes X and Y together fulfil the requirements of M.

5.6. Mapping scope

Mappings apply at the process element level. A mapping from process A to process B implies:

• The compliance obligations (provisions) of process B are addressed by process A.
• The data outputs of process A are relevant to the data requirements of process B.
• The actor assignments of process A are compatible with the role requirements of process B.

Mappings do NOT imply structural equivalence -- the subprocess diagrams, events, and gateways of process A and process B may differ significantly. The mapping asserts only that the outcomes of process A satisfy the requirements of process B.

6.1. General

Mapping coverage analysis determines the extent to which a reference model's processes are addressed by an implementation model's mappings. Coverage is a key indicator of compliance completeness.

6.2. Coverage types

MMEL defines four levels of mapping coverage for a reference model process:

6.3. Coverage determination

Coverage is determined by analysing the mapping data:

1. For each reference model process, identify all implementation model processes that map to it.
2. If at least one mapping exists, the process has at least minimal cover.
3. If the mapping descriptions and justifications indicate all provisions are addressed, the process has full cover.
4. If some but not all provisions are addressed, the process has partial cover.
5. If no mapping exists, the process has no cover.

6.4. Inherited coverage

When a parent process is mapped, its subprocesses are considered fully covered by inheritance. This reflects the hierarchical nature of MMEL processes: if a top-level process is mapped, all of its subprocess activities are implicitly covered.

Process A (mapped to Process B)          Process B (reference)
  |                                         |
  +-- Subprocess A1                        +-- Subprocess B1
  |                                         |
  +-- Subprocess A2                        +-- Subprocess B2
          |
          +-- Subprocess A3
Since A => B is mapped:
  A1, A2, A3 are considered fully covered (inherited from A)

Inherited coverage applies when:

• The parent process has an explicit mapping to a reference process.
• The subprocesses of the parent are not individually mapped (or their individual mappings are subsumed by the parent mapping).

If a subprocess has its own explicit mapping, that mapping takes precedence over inherited coverage.

6.5. Coverage indicators

Coverage is reported as a set of indicators for each reference model process:

6.6. Coverage summary

A coverage summary for a model mapping is expressed as:

Total reference processes: N
Full cover:      X (X%)
Minimal cover:   Y (Y%)
Partial cover:   Z (Z%)
No cover:        W (W%)

A mapping is considered complete when all reference processes have at least minimal cover. A mapping is considered comprehensive when all reference processes have full cover.

7.1. General

Auto-mapping discovery is a tooling feature that uses transitive and inherited mapping logic to infer additional mappings beyond those explicitly declared. This reduces the manual effort required to create comprehensive mappings and helps identify gaps in coverage.

7.2. Prerequisites

Auto-mapping discovery operates on a set of loaded models and their associated mapping data. The following prerequisites apply:

• All relevant models ( .mmel files) MUST be loaded and parsed.
• All relevant mapping files ( .map files and map_profile blocks) MUST be loaded.
• Models MUST share a common namespace for cross-referencing.

7.3. Discovery process

The auto-mapping discovery process follows these steps:

Load all reference models and implementation models into the tool's workspace.

Identify the bridge model -- the model whose processes serve as the intermediate link between two other models. The bridge model has mappings both from a source model and to a destination model.

Select the destination models for which auto-mappings should be discovered. These are models that are not directly mapped from the implementation model but can be reached through the bridge model.

Apply the following rules to discover implicit mappings:

• Transitive discovery: If the implementation model maps process A to bridge model process B, and the bridge model maps process B to destination model process C, then infer a mapping from A to C with a note that this is a transitive mapping.
• Inherited discovery: If a parent process P is mapped to reference process Q, then all subprocesses of P are considered mapped to the subprocesses of Q.
• Combine with explicit mappings: Merge discovered mappings with existing explicit mappings, with explicit mappings taking precedence.

7.4. Transitive discovery

Transitive discovery follows process-level transitivity (see mapping-semantics ):

Implementation Model          Bridge Model              Destination Model
process A                     process B                 process C
    |                             |                         ^
    +-- A => B (explicit)         |                         |
                                  +-- B => C (explicit) ----+
                                                             |
                          A => C (discovered, transitive) ---+

The discovered mapping A => C is marked as transitive and includes a reference to the intermediate mapping through B.

7.5. Inherited discovery

Inherited discovery propagates mappings from parent processes to their subprocesses:

Implementation Model                    Reference Model
process Parent (mapped to RefParent)
  |                                       |
  +-- subprocess ChildA                  +-- subprocess RefChildA
  |                                       |
  +-- subprocess ChildB                  +-- subprocess RefChildB
Since Parent => RefParent:
  ChildA => RefChildA (discovered, inherited)
  ChildB => RefChildB (discovered, inherited)

7.6. Discovered mapping metadata

Auto-discovered mappings are annotated with provenance metadata:

Discovered mappings are considered lower confidence than explicit mappings. Tools SHOULD present them differently (e.g. with a distinct visual indicator) and SHOULD allow users to validate or reject individual discovered mappings.

7.7. Limitations

Auto-mapping discovery has the following limitations:

• It does not create new descriptions or justifications -- these must be provided manually for discovered mappings that are accepted.
• Transitive discovery may produce false positives if the intermediate mapping does not imply full coverage.
• Inherited discovery assumes subprocess alignment between models, which may not always be structurally accurate.

8.1. General

The MMEL mapping system includes a report template mechanism that enables generation of compliance documents from mapping data. Report templates use the Liquid template language and are stored within the docs section of .map files.

8.2. Template language

Report templates use the Liquid template language ( https://shopify.github.io/liquid/ ). Liquid provides a safe, designer-friendly templating syntax with three core constructs:

• Objects -- {{ variable }} outputs the value of a variable.
• Tags -- {% tag %} provides logic (loops, conditionals).
• Filters -- {{ variable | filter }} transforms output.

8.3. Environment objects

The report template engine provides the following environment objects to templates:

8.4. Example: Statement of Applicability

The following example shows a Liquid template that generates a Statement of Applicability (SoA) in AsciiDoc format. This template is stored in the docs section of a .map file:

=== Statement of applicability
.SoA for main document
[cols="1,1,1,1"]
|===
|Clause
|Title
|Description
|Justification
{% for r in map %}
{% assign first = r.clause | slice: 0 %}
{% unless first == "A" %}
{% if r.justification.length == 0 %}
4+|Clause {{r.clause}} {{r.title}}
{% else %}
{% for just in r.justification %}
|{{r.clause}}
|{{r.title}}
|
|{{just}}
{% endfor %}
{% endif %}
{% endunless %}
{% endfor %}
|===
.SoA for Annex A
[cols="1,1,1,1"]
|===
|Clause
|Title
|Description
|Justification
{% for r in map %}
{% assign first = r.clause | slice: 0 %}
{% if first == "A" %}
{% if r.justification.length == 0 %}
4+|Clause {{r.clause}} {{r.title}}
{% else %}
{% for just in r.justification %}
|{{r.clause}}
|{{r.title}}
|{{r.description}}
|{{just}}
{% endfor %}
{% endif %}
{% endif %}
{% endfor %}
|===

This template:

1. Iterates over all mapping records using {% for r in map %}.
2. Separates main body clauses from Annex A clauses using the first character of the clause identifier.
3. Generates an AsciiDoc table with clause, title, description, and justification columns.
4. Handles unmapped clauses (those without justifications) by spanning them across all columns as section headers.

8.5. Input object specifications

The template engine provides the following input objects:

8.6. Template storage in .map files

Templates are stored in the docs field of .map files:

{
  "docs": {
    "applicability-main": {
      "id": "applicability-main",
      "name": "",
      "datatype": "role",
      "title": "ISO/IEC 27001:2013 Statement of Applicability",
      "content": "<Liquid template content as a string>"
    }
  }
}

The content field contains the Liquid template source as a single string (with \n for newlines). The title field provides a human-readable title for the generated document.

8.7. Template rendering

A MMEL-compliant tool that supports report templates:

1. SHALL parse the docs section of .map files.
2. SHALL provide the map, raw, imodel, and rmodel objects to the template engine.
3. SHALL render the template using a Liquid-compatible engine.
4. SHOULD support output in AsciiDoc format.
5. MAY support additional output formats (HTML, PDF, etc.).