Reference Architecture, published by WHO. This guide is not an authorized publication; it is the continuous build for version 0.2.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/costateixeira/smart-ra/tree/glossary and changes regularly. See the Directory of published versions

Architecture principles

Methodology Principles

This publication offers reference architecture content to support stakeholders in their journey toward interoperability and system design. While it does not prescribe an implementation methodology, it reflects internal architectural practices and principles that guide the structure, clarity, and reusability of the content presented here.

The following principles describe how this architecture is developed and maintained.

---

1. Architecture SHALL be accessible to its stakeholders

Architecture is not just a technical asset — it must be understandable by those who use and depend on it.

In particular, Business Architecture SHALL be accessible to business readers, without requiring prior knowledge of TOGAF, ArchiMate, or technology frameworks.

---

2. Architecture SHOULD be structured and maintainable

Architecture must evolve over time. To support this, it must be described using consistent concepts, patterns, and layers.

Models and documentation SHALL avoid fragmentation and support maintenance by design.

---

3. Architecture SHOULD be machine-readable where applicable

To support analysis, reuse, validation, and automation, architecture descriptions SHOULD be represented in structured, parseable formats (e.g., text-based representations, structured diagrams, linked models).

---

4. Architecture elements SHOULD be reusable across contexts

Capabilities, data structures, and processes SHALL be described in a way that allows reuse across multiple country or organizational implementations.

---

5. Architecture descriptions SHALL promote alignment, not prescription

This publication does not prescribe implementation. It provides a reference model to support alignment and inspiration.

Consumers may adapt, extend, or specialize the content to their own context.

---

6. Architecture SHALL support integration with established standards

Where possible, architectural elements SHALL align with existing standards (e.g., FHIR, IHE, SNOMED CT, ISO) to promote interoperability and semantic clarity.

---

7. Visual models SHOULD follow recognized modeling notations

Diagrams and views SHALL be expressed using standard visual languages, such as ArchiMate, to support understanding, tool compatibility, and consistency.

---

8. Architecture SHALL reflect real-world workflows and needs

Models and examples SHALL be grounded in practical, real-world scenarios, not abstract theory. This ensures relevance to health systems, implementers, and decision-makers.

---

9. Documentation SHALL separate views by stakeholder concern

Not all readers need all views. Business, application, technical, and information views SHALL be clearly separated and targeted to their intended audiences.

---

10. Guidance SHALL be descriptive, not prescriptive

This work provides definitions, reusable content, and examples, not mandates. It supports implementers by offering shared structure and vocabulary, not enforcing a specific process.

---

Summary

These principles guide how we document and share architectural content. They reflect an approach that prioritizes clarity for stakeholders, consistency across views, and alignment with real-world standards and needs.

While we do not prescribe how others must structure their architecture, we hope these principles help inform and inspire good practices.