openEHR Specification Document Authoring

Use this skill to create and edit openEHR specification documents: the AsciiDoc sources that live in specifications-XX repositories (RM, AM, BASE, LANG, PROC, SM, QUERY, CDS, CNF, TERM, ITS-*).

Note: In specifications-ITS-REST, the OpenAPI YAML and Markdown sources are covered by the its-rest skill. The AsciiDoc specs under its docs/ (for example simplified_formats, smart_app_launch) follow this skill.

Related Skills

• content-patterns — prose writing patterns for spec chapters (overview, semantics, design rationale, etc.)
• amendment-record — dedicated guide for amendment record authoring
• review — checklist-driven quality review of spec documents (the spec-reviewer subagent runs it over a whole spec or component)
• its-rest — for OpenAPI YAML and Markdown in the ITS-REST repo
• governance — release management, change requests, lifecycle governance
• class-generation — regenerate the class-definition tables and UML diagrams in docs/UML/ from BMM via bmm-publisher
• bmm-authoring — write or change the component's BMM schema (classes, attributes, functions, invariants) and check it

For attribute naming patterns, read references/cross-references.md. To verify that every {openehr_*} attribute and deep-link anchor resolves, dispatch the xref-auditor subagent.

Repository Layout

Each specification component lives in its own repo: specifications-XX (e.g., specifications-RM). The shared infrastructure repo specifications-AA_GLOBAL provides boilerplate, styles, references, and publishing scripts used by all components.

specifications-XX/
├── manifest.json              # Component metadata, specs, releases, Jira links
├── docs/
│   ├── index.adoc             # Component index page
│   ├── <spec-id>/             # One directory per specification
│   │   ├── master.adoc        # Main entry point
│   │   ├── manifest_vars.adoc # Per-spec variables
│   │   ├── master00-amendment_record.adoc
│   │   ├── master01-preface.adoc
│   │   ├── master02-*.adoc ... masterNN-*.adoc
│   │   ├── diagrams/          # SVG/PNG diagrams
│   │   └── images/            # Other images
│   ├── UML/                   # BMM-generated class docs + diagrams (do NOT hand-edit; see class-generation skill)
│   └── common/                # Shared content within component

The specifications-AA_GLOBAL repo (expected as a sibling checkout; if absent, read its files at https://github.com/openEHR/specifications-AA_GLOBAL) provides:

specifications-AA_GLOBAL/
├── docs/boilerplate/          # Shared AsciiDoc includes
│   ├── global_vars.adoc       # Global Asciidoctor attributes
│   ├── book_style_settings.adoc
│   ├── basic_style_settings.adoc
│   ├── full_front_block.adoc  # Full front matter (with block diagram)
│   ├── short_front_block.adoc # Short front matter (without block diagram)
│   ├── doc_id_block.adoc      # Release/status/revision table
│   └── licence_block.adoc     # Copyright and licence table
├── docs/references/
│   └── reference_definitions.adoc  # All cross-spec and external URLs
├── resources/css/             # Stylesheets
├── resources/logos/           # openEHR logos
└── bin/
    ├── spec_publish.sh        # Main publishing script
    └── do_spec_publish.sh     # Wrapper

The {ref_dir} Asciidoctor attribute resolves to the AA_GLOBAL repo root relative to the consuming spec document.

Creating a New Specification Document

Step 1: Create the spec directory

Choose the spec id (the SEC verifies identifier and placement for new specs; see the governance skill) and create specifications-XX/docs/<id>/. Use the same id in the manifest.json entry (Step 6).

Step 2: Create manifest_vars.adoc

Define the per-document Asciidoctor attributes that the boilerplate reads. The values below come from the EHR IM; replace them with the new spec's own:

:spec_title: EHR Information Model
:copyright_year: 2003
:spec_status: STABLE
:keywords: EHR, EMR, reference model, openehr
:description: openEHR EHR Information Model specification

Fields:

• `:spec_title:` — The document title, displayed after the openEHR logo
• `:copyright_year:` — Year of first publication (used in licence block)
• `:spec_status:` — One of: DEVELOPMENT, TRIAL, STABLE, PAUSED, SUPERSEDED, OBSOLETE, RETIRED. Use the state the SEC assigned (see the governance skill) and keep it identical to spec_status in manifest.json
• `:keywords:` — Comma-separated keywords for the HTML meta tag
• `:description:` — One-line description for the HTML meta tag

Step 3: Create master.adoc

Write master.adoc from this canonical template:

//
// ============================================ Asciidoc HEADER =============================================
//
include::{ref_dir}/docs/boilerplate/book_style_settings.adoc[]
include::manifest_vars.adoc[]
include::{ref_dir}/docs/boilerplate/global_vars.adoc[]

//
// ============================================ Asciidoc PREAMBLE =============================================
//

image::{openehr_logo}["openEHR logo",align="center"]

= {spec_title}

include::{ref_dir}/docs/boilerplate/full_front_block.adoc[]
include::{ref_dir}/docs/references/reference_definitions.adoc[]

//
// ============================================= Asciidoc BODY ===============================================
//

include::master00-amendment_record.adoc[leveloffset=+1]

//
// --------------------------------------------- Preface -----------------------------------------------
//

== Acknowledgements

=== Editor

* <Editor Name>, <Affiliation>.

=== Contributors

<List of contributors>

=== Trademarks

* 'openEHR' is a trademark of the openEHR Foundation

//
// --------------------------------------------- CHAPTERS -----------------------------------------------
//
:sectnums:

// `package_qualifiers` is set by the publisher's -q flag; :pkg: is the lower-case package prefix of the spec.
ifdef::package_qualifiers[]
:pkg: org.openehr.<component>.<spec>.
endif::[]

include::master01-preface.adoc[leveloffset=+1]
include::master02-overview.adoc[leveloffset=+1]
// ... additional chapters ...

//
// --------------------------------------------- REFERENCES -----------------------------------------------
//
:sectnums!:
== References

bibliography::[]

Keep the header includes in this order:

1. book_style_settings.adoc — sets doctype, syntax highlighter, TOC
2. manifest_vars.adoc — local spec variables
3. global_vars.adoc — global openEHR attributes

Front block choice:

• Use full_front_block.adoc for primary specifications (includes block diagram)
• Use short_front_block.adoc for secondary/overview documents (no block diagram)

Step 4: Create master00-amendment_record.adoc

= Amendment Record

[cols="1,6,2,2", options="header"]
|===
|Issue|Details|Raiser|Completed

|[[latest_issue]]0.1.0
|Initial writing.
|<Author Name>
|[[latest_issue_date]]<dd Mon yyyy>

|===

The [[latest_issue]] and [[latest_issue_date]] anchors are required — the doc_id_block.adoc references them to display revision and date in the front matter table.

For Jira references, version bumps, and release boundaries, see the amendment-record skill.

Step 5: Create chapter files

Name chapters sequentially: master01-preface.adoc, master02-overview.adoc, etc., and keep the numbering gap-free. Appendices use masterAppA-<name>.adoc. Start each chapter file with a = Chapter Title heading, and add a matching include::masterNN-<name>.adoc[leveloffset=+1] line to master.adoc.

Create master01-preface.adoc with a = Preface heading and these == sections in order: Purpose, Related Documents, Status, Feedback, then optionally Conformance, Tools, and Changes from Previous Versions. Use the Status and Feedback link patterns in references/cross-references.md.

Step 6: Update manifest.json

Add the new specification entry to the specifications array, with id, title, description, copyright_year, spec_status, and keywords matching manifest_vars.adoc. See references/manifest-spec-entry.md for the full field reference.

Step 7: Preview locally

Build a local HTML preview after creating or editing a spec. The user can run /openehr-specs:publish <component> (user-only; it wraps the command below), or run it from the parent directory that contains all specifications-* repos, with XX as the component (for example RM):

docker run --rm -u $(id -u):$(id -g) -v "$(pwd):/documents/" ghcr.io/openehr/asciidoctor development XX

The image bundles the toolchain, but the boilerplate and reference definitions are still read from the sibling specifications-AA_GLOBAL/ checkout. Its entrypoint is spec_publish.sh -f -r -v -t -q -l, so the first argument is the release. To use a locally installed toolchain instead, run ./specifications-AA_GLOBAL/bin/spec_publish.sh -f -q -v XX; always pass -q, because without it every {pkg} class-table include fails.

The build prints generated <file> and exits 0 even when includes are missing or asciidoctor failed. Check that each expected docs/<spec>.html has a later modification time than before the build and that the log has no ERROR or include file not found lines. The build rewrites the tracked docs/*.html artefacts; do not stage them. The preview does not tag or deploy a release; that is the governance skill's process.

Editing Existing Specifications

Conventions

• Chapter files: Edit masterNN-*.adoc files directly. Never edit files under docs/UML/ — those are generated from the component's BMM schema by bmm-publisher (see the class-generation skill); change the BMM (see the bmm-authoring skill) and regenerate.
• Cross-references within spec: Use <<anchor_name>> or <<anchor_name, display text>>.
• Cross-references to other specs: Use the URL attributes from reference_definitions.adoc:

  {openehr_rm_common}[Common IM^]
  {openehr_rm_data_types}#dv_quantity[DV_QUANTITY^]

• Cross-references to classes: Use {classes_url_root} for linking to the class index.
• Admonitions, code blocks, tables: follow references/asciidoc-syntax.md when adding a note, a code example, or a table.
• Jira ticket references: {spec_tickets}/SPECRM-87[SPECRM-87^]
• External references: Check reference_definitions.adoc first — it has hundreds of pre-defined URLs for HL7, W3C, ISO, IETF, Wikipedia, SNOMED, etc. If an attribute is missing, add it to specifications-AA_GLOBAL/docs/references/reference_definitions.adoc (a separate repo and commit) following the naming pattern, and tell the user the change spans two repos.

Global Variables and URL Patterns

Release-version attributes ({rm_release} and so on, defaulting to latest) and spec-link attributes follow fixed naming patterns; read references/cross-references.md before constructing one, and follow the pattern exactly when adding a new reference. To build a named release, pass the label to the publisher with -l <label> (see the governance skill).

Amendment Record Updates

Add an entry to the spec's amendment record for every change, following the amendment-record skill (entry order, anchors, version-bump table, Jira references). The user can also run /openehr-specs:amendment-record <SPECXX-NN[,SPECPR-NN] — summary> to have the entry added directly.

Diagrams

• Place hand-drawn SVG diagrams in <spec-id>/diagrams/. Generated UML diagrams use {uml_diagrams_uri}.
• Write each figure as a titled block:

  [.text-center]
  .Figure title
  image::{diagrams_uri}/<filename>.svg[id=<anchor_id>, align="center"]

• UML class and package diagrams are generated from the component's BMM schema by bmm-publisher (which renders them to SVG via PlantUML). This replaces the historical MagicDraw .mdzip extraction. See the class-generation skill to regenerate them.