bmm-publisher

CLI tool that reads openEHR BMM (Basic Meta-Model) schemas and generates class documentation for the openEHR specifications website.

The BMM is a formal model used to define the type systems behind the openEHR Reference Model, Archetype Model, and related components. Each component's classes, properties, functions, and type relationships are expressed as P_BMM JSON schema files.

This tool processes those schemas and produces:

• AsciiDoc tables and class diagrams — class definitions, effective (flattened) views, cross-referenced type links, and class diagrams referenced from the tabs partial via image::ROOT:uml/classes/<name>.svg[] macros (no Kroki / asciidoctor-diagram dependency at site-build time); rendered SVGs (per-class and per-package overviews) are committed under output/Adoc/<schema>/images/uml/{classes,diagrams}/
• PlantUML sources — .puml files for the same diagrams, kept alongside the generated partials as the source of truth
• YAML — machine-readable serialisation of each schema
• Per-type JSON — individual class files with links back to the relevant specification page

Extend it for your own use

Because BMM formally describes the complete openEHR type system — classes, inheritance, properties, generics, functions, constraints — it can serve as the source of truth for many downstream artefacts beyond documentation. If you need something this tool doesn't produce out of the box, fork the repo and add your own writer. Each writer is a single callable class that receives the loaded schemas and writes output. Examples of what you could generate:

• Code skeletons — PHP, Java, C#, Python, or TypeScript class stubs with typed properties and method signatures derived from the BMM definitions
• JSON Schema / OpenAPI — formal validation schemas for REST APIs that exchange openEHR data structures
• GraphQL types — type definitions for GraphQL APIs backed by the Reference Model
• Database schemas — DDL for relational or document stores, mapping BMM classes to tables or collections
• Alternative documentation formats — Markdown, HTML, Docusaurus pages, Confluence wiki markup, or any other publishing format
• Diff reports — compare two BMM versions and produce a changelog of added, removed, or changed classes and properties
• Conformance test data — generate test fixtures or validation datasets based on the type constraints

The architecture is intentionally simple: BmmSchemaCollection loads and indexes all schemas, your writer iterates them and produces files.

Quick start (Docker)

The production image ships with all openEHR BMM schemas and the plantuml CLI, and runs bmm-publisher as its entrypoint — just pass a command. The asciidoc command is self-contained: it writes the tables, renders every class diagram to SVG, and publishes them under output/Adoc/<schema>/images/uml/{classes,diagrams}/ in one invocation.

docker run --rm -v ./my-output:/app/output ghcr.io/openehr/bmm-publisher asciidoc all

See docs/install.md for all invocation options — your own schemas, single-schema runs, BMM_OUTPUT_DIR overrides, host-user mapping, and -v/-vv logging.

Commands

Command	Aliases	Description
asciidoc	adoc	Convert BMM JSON schemas to AsciiDoc tables, with class/package diagrams pre-rendered as standalone SVGs under images/uml/{classes,diagrams}/ and referenced from the tabs partial via image::ROOT:uml/classes/<name>.svg[]
legacy-adoc		Generate the legacy docs/UML/classes layout — flat per-class definition tables only (-o <dir> to choose the output directory)
plantuml	uml, puml	Generate the standalone PlantUML source tree (output/PlantUML/<schema>/...) — useful when you want only the .puml files
embed-svg		Re-run only the SVG sanitise + publish step against existing .svg files (debugging / surgical re-renders)
yaml		Convert BMM JSON schemas to YAML format
split-json		Split latest BMM JSON of each component into per-type files
odin		Convert BMM JSON schemas to ODIN .bmm schema files (the native openEHR BMM schema format)

Pass schema name(s) without .bmm.json extension (or .bmm.json paths), or all to process every schema in the input directory. asciidoc, legacy-adoc, and plantuml accept repeatable -d <schema> dependencies (loaded for cross-references, not exported).

Input / output

• Input: BMM schemas in resources/ (.bmm.json files, shipped with the image)
• Output: generated artefacts in output/ — mount a volume to retrieve them

For BMM_OUTPUT_DIR overrides, mounting your own schemas, and running as the host user (uid/gid), see docs/install.md.

Development

Requires Docker. The development image includes xdebug and Composer.

make install        # Install PHP dependencies
make ci             # Run full CI checks (lint, PHPCS, PHPStan, tests)
make sh             # Interactive shell in dev container
make build-prod     # Build production image locally

Inside the dev container:

./bin/bmm-publisher asciidoc openehr_rm_1.2.0 openehr_base_1.3.0
composer test
composer check:phpstan

See docs/development.md for full Composer scripts and tooling reference.

See AGENTS.md for project structure, standards, and architecture.

License

Apache-2.0