openEHR Class Documentation Generation (BMM)

openEHR specification class documentation — the per-class definition tables and the UML class/package diagrams embedded in specifications-XX documents — is generated, not hand-written. The source of truth is the component's BMM (Basic Meta-Model) schema, serialised as P_BMM JSON, and the generator is the bmm-publisher CLI tool.

Replaces MagicDraw. Class tables and diagrams were historically extracted from MagicDraw .mdzip UML models. That mechanism is retired; bmm-publisher is the current BMM-based generator.

Related Skills

• authoring — document scaffolding and repo layout; explains where generated class docs are included
• review — the ADOC-03 check enforces that class tables are generated, not hand-written
• content-patterns — prose around classes (semantics, rationale) that the generated tables do not cover

For the full command, option, and schema reference, see references/bmm-publisher.md.

When to Regenerate

Regenerate class documentation when:

• A component's BMM schema changes (new/renamed/removed classes, properties, functions, or types)
• A spec needs its docs/UML/classes/ tables refreshed before a release
• Class diagrams (SVGs) are stale relative to the model

Never hand-edit the generated output — change the BMM schema upstream and regenerate.

Installation

The tool is distributed as a Docker image that bundles all openEHR BMM schemas and the plantuml CLI. No local PHP, Composer, or checkout is required.

# Discover commands
docker run --rm ghcr.io/openehr/bmm-publisher list

For local development against a cloned bmm-publisher checkout, drive everything through its dev container (no host PHP): make install, make sh, make publish-all. See references/bmm-publisher.md.

Core Commands

Pass schema id(s) without the .bmm.json suffix (e.g. openehr_base_1.3.0), or all. Use repeatable -d <schema> for dependency schemas loaded for cross-references only (not exported), and -v/-vv for progress / detailed logging.

Output Layouts and How Specs Consume Them

bmm-publisher writes two layouts; pick the one the target component uses.

Legacy layout — docs/UML/classes/ (the include model)

legacy-adoc produces one .adoc table per class, named org.openehr.<component>.<package>.<class>.adoc (the class segment is lowercased, e.g. org.openehr.base.base_types.access_group_ref.adoc). These are placed in the component's docs/UML/classes/ directory and pulled into chapter files via the {uml_export_dir} attribute (which resolves to ../UML):

include::{uml_export_dir}/classes/{pkg}composition.adoc[]

This is the layout enforced by the review skill's ADOC-03 check.

Current layout — output/Adoc/<schema>/ (tables + rendered SVGs)

asciidoc produces classes/, effective/, definitions/, plantUML/, and rendered SVGs under images/uml/{classes,diagrams}/. Diagrams are referenced with Antora-style resource macros:

image::ROOT:uml/classes/COMPOSITION.svg[]

Typical Workflow

1. Identify the schema for the component and version, e.g. openehr_base_1.3.0, openehr_rm_1.2.0

(naming pattern: openehr_<component>_<version>).

1. Generate into a working directory, mapping ownership to the host user:

   docker run --rm --user $(id -u):$(id -g) \
     -v ./out:/app/output \
     ghcr.io/openehr/bmm-publisher asciidoc -v openehr_rm_1.2.0 -d openehr_base_1.3.0

1. Place the generated classes/*.adoc into the component's docs/UML/classes/ (legacy layout)

or wire the output/Adoc/<schema>/ content per the component's current convention.

1. Verify by publishing the spec (see the authoring skill) and confirming class tables and

diagrams render and cross-references resolve.

Guardrails

• Generated output is never hand-edited. Fix the BMM schema and regenerate.
• *`resources/.bmm.json` is upstream input** — do not modify it unless the task is specifically to

change the model.

• Provide cross-referenced dependency schemas with -d so type links resolve (e.g. RM depends on BASE).