Archetype Editorial style guide
Focus
The editorial focus in archetype design is on clear clinical content representation. Implementation and querying are important but less prioritized.
Archetypes define specific clinical concepts, clarifying what the data represents. Metadata and element descriptions provide guidance for implementers on how to use these archetypes in templates and forms; however, they are not intended for end users of electronic health records.
Instructions on data capture and interpretation are found in medical guidelines or literature, and can be referenced in the archetype’s Reference section. It can be challenging to differentiate between defining a measurement, and instructions on how to perform the measurement. As an inspiration, see OBSERVATION.head_circumference archetype, which describes “Head circumference” as “The measurement of the longest distance around the head” without detailing the measurement method. This is intentional to avoid serving as a medical textbook and to accommodate local variations. If necessary, users should document measurement methods in designated elements in the archetype's Protocol section.
Original language
All archetypes for upload or federation to the international openEHR CKM should have English (ISO-639-1 "en") as the original language. All translations are done from the original language, and using any language less common than English will likely lead to "chinese whispers" translation; distortion of the original semantics through translations of translations.
Metadata
All text should have a full stop or equivalent at the end of the description.
CKM will flag a style error on upload if the text has extra spaces at the beginning or end of a sentence, or if the text does not end with a full stop or equivalent.
Description | Example | |
|---|---|---|
Concept name | Succinct name that encompasses the scope and intent of the archetype. | Blood pressure |
INSTRUCTION archetype names will include the word 'order' or equivalent. Corresponding ACTION archetype names will just contain the concept, or a very specific scope for the archetype. | INSTRUCTION: "Service request" & ACTION: "Service" INSTRUCTION: "Medication order" & ACTION: "Medication management" | |
| When there is an abbreviation within the name of the archetype, the abbreviation should occur right after the words of which the abbreviation is made. | “Neurologic Assessment in Neuro-Oncology (NANO) scale”, and not “Neurologic Assessment in Neuro-Oncology scale (NANO).” |
| If the archetype is a local variant, either by country, region or hospital, or a preliminary version made by a project or a vendor in anticipation of a formal review process leading to a published state, it is highly recommended to use a suffix to the archetype name to be able to differentiate from the published archetype. |
|
Concept description | Definition of the 'Concept name'. The intent of the description is to define the concept as clinicians apply it in clinical practice, not the academic or dictionary definition of the concept. | "The local measurement of arterial blood pressure which is a surrogate for arterial pressure in the systemic circulation." |
Purpose | Preface with "To record "... or similar. | COMPOSITION wording needs to be a little different to other clinical content - for example ”a named container for information provided by an individual, to support clear separation of patient generated from clinically genereated health data.” |
Use |
| “Use to record all representations of systemic arterial blood pressure measurement, no matter which method or body location is used to record it.” |
| "This archetype has been specifically designed to be used in the 'Examination detail' SLOT within the CLUSTER.exam-mouth, CLUSTER.exam-cranial_nerves or OBSERVATION.exam archetypes, but can also be used within other ENTRY or CLUSTER archetypes, where clinically appropriate." | |
| 'Use to provide a framework in which CLUSTER archetypes can be nested in the 'Examination findings' SLOT to record additional structured physical examination findings." | |
|
| ‘Approximate values are not explicitly modelled in this archetype, as the openEHR Reference Model supports approximation for any Quantity data type by setting the |
Misuse | Preface with "Not to be used"... or similar, followed by a description of the specific use case the archetype isn’t to be used for. Finish with a separate sentence describing which archetypes to use for the specified use case. If the archetypes to be used haven’t been created yet, make the final sentence “Use a specific archetype for this purpose.” | “Not to be used for recording physiological reactions to physical agents, such as heat, cold, sunlight, vibration, exercise activity, by infectious agents or food contaminants. Use the EVALUATION.problem/diagnosis or CLUSTER.symptom/sign archetypes for this purpose.” “Not to be used to record reactions to transfusions of blood products. Use a specific archetype for this purpose.” |
| Proposal 2026 01 29 For Misuse statements for which no associated archetype yet exists, it is recommended that a consistent statement is included across all Misuse sections:
Be mindful that the addition of this statement will be informative but will require maintenance/updating as these archetypes are gradually developed and added to CKM |
|
References
References within published archetypes should be consistent with Citing Medicine, 2nd edition - | |
The National Library of Medicine provides an easy way to ensure consistent formatting through the use of a bibliography tool that can automatically configure citations for a variety of different publications. If the required citation is not found within the PubMed search then the link above will support manual formatting, eg for parts of websites. | |
References to other archetypes or parts of archetypes within CKM can be located on the 'Share with Colleague' tab for each archetype. | http://www.openehr.org/ckm/#showArchetype_1013.1.2741_SHAREWITHCOLLEAGUE |
CKM discontinued | For example: "Derived from: Employment summary, draft archetype [Internet]. Australian Digital Health Agency (NEHTA), ADHA Clinical Knowledge Manager. No longer available." |
Referencing a FHIR artifact |
|
Copyright
Copyright statement |
|
Content copyright
Guideline for communicating external content copyright requirements to users | If the copyright conditions are known, include this statement in the ‘Use’ section of the archetype, describing content copyright, formal copyright statement and access to information about permissions etc by the copyright holders.
If the exact copyright conditions are unknown, include this adapted statement in the 'Use' section of the archetype:
|
License
Content Licence |
|
|---|
IP Acknowledgement
SNOMED-CT | Until tooling evolves to allow this to occur through a standard interface, add manually via Notepad or equivalent directly to "other_details = <" section in the archetype ADL:
|
|---|
Data elements
All data element names should be represented in Sentence case - with the first letter uppercase and subsequent letters lowercase. Exceptions include proper nouns or acronyms.
All data element descriptions should have a full stop or equivalent at the end of the description.
Examples and other further explanations about how to use a specific data element should be noted in the “Comment” section of the data element. Use wording like “For example: [example 1]; [example 2]; or [example 3].”
CKM will flag a style error on upload if the data element has extra spaces at the beginning or end of a sentence, or if the description does not end with a full stop or equivalent.
Description | Example |
| |
|---|---|---|---|
<XYZ> tested/examined | Usually mandatory, as if the actual object of the test or examination is not identified, then any subsequent data is not clearly identified. | The ear(s) to which the test stimulus is being presented.
|
|
<XYZ> name | The name and/or code for a particular type of the real world concept the archetype is about. For example lab test, problem/diagnosis or medication. The intent of the description is to describe the element concept as clinicians apply it in clinical practice, not the academic or dictionary definition of the concept. | Description:
|
|
Clinical description | As per examination archetype pattern. |
|
|
<XYZ> commenced | Naming of a data element used to describe a start date for an activity or a duration for an age commenced. |
| |
<XYZ> ceased | Naming of a data element used to describe a stop date for an activity or a duration for an age ceased. |
| |
Category | Expression of a broader or less specific grouping, especially related to a named item. | Data element name: Intervention category Description: An overarching grouping for the intervention identified in 'Intervention name'. Comment: For example 'Cancer treatment', 'Psychosocial' or ‘Surgical’. |
|
Type | Expression of a narrower or more specific grouping, especially related to a named item. | Data element name: Intervention type Description: A more specific method or process for delivering the intervention identified in ‘Intervention name’. Comment: For example ‘Brachytherapy’, ‘Motivational interviewing technique’ or ‘Laparoscopic’. |
|
Multimedia representation | SLOT to carry the CLUSTER.multimedia archetype until the data type is updated to support all of the additional requirements explicitly modelled in the archetype. |
|
|
Comment | Last data element in many archetypes to catch data that may not yet be structured, nor fit into any other general narrative description data element. May have multiple occurrences, if necessary. |
|
|
Confounding factors |
|
| |
Any event | As a default, “Any event” should have “0..*” occurrences, in order to have multiple recordings within one instance of the archetype. |
|
|
Any point-in-time event |
|
|
|
Extension SLOT | Added to Protocol for every COMPOSITION or ENTRY archetype to allow for local extensions or potential alignment with other modelling paradigms. This have to be revised after the “Guidelines for developing PROM archetypes” are finished. | Description:
Comment:
ADL:
|
|
Dates, times and datetimes | Proposal In most cases, datetime should be used unless there is a clear reason why a date or time would never be appropriate for the data element. The element should be named according to conventions for the concept being modelled, with a preference for structuring like “XXXX date/time”, “YYYY date” or “ZZZZ time”. The description should in most use cases be phrased like “The date or datetime of …”. Generally avoid the phrase “The date and/or time of …”, as it would rarely be appropriate for the same data element to be represented by a date or time by itself. |
|
|
Partial dates and datetimes | Some date and datetime elements are intended to allow partial dates, for examples a year only. For these, a comment should be added to specify this. | Comment:
|
|
Body sites | The recording of body sites is normally modelled as the combination of a Text element named “Body site” and a SLOT named “Structured body site” for a CLUSTER archetype. The SLOT should normally include one or more of CLUSTER.anatomical_location, CLUSTER.anatomical_location_circle, or CLUSTER.anatomical_location_relative. | Name:
Description:
Comment:
|
|
Body site grouping | Proposal - makes the above ‘Body sites’ guidance redundant. Proposed changes are highlighted in blue. Until final approval ‘Body sites’ has been marked with strikethrough to support additional guidance for examination of findings that are not related to an identified body system structure. In some archetypes there are two patterns to describe the increasing levels of detail about a body site, ie a data element named ‘Body site’ AND a SLOT for ‘Structured body site’:
|
Body site: Description: Identification of the area of the body under examination. Consider updating Comment to: Coding of 'Body site' with a terminology, such as a precoordinated SNOMED CT term, is recommended. If the body site has been fully identified in the 'System or structure examined' data element, this data element becomes redundant. NOTE: it is proposed to remove the example as ‘an area of skin’ is not a relevant example in most specialisations. A specific example, relevant to the archetype concept could be added by specialising this data element in the archetype. / Structured body site {SLOT]: Description: A structured description of the area of the body under examination.
Body site: Description: Identification of the area of the body under examination. NOTE: A specific example, relevant to the archetype concept could be added by specialising this data element in the archetype. / Structured body site {SLOT]: Description: A structured description of the area of the body under examination. NOTE: The SLOT should include one or more of CLUSTER.anatomical_location, CLUSTER.anatomical_location_circle, or CLUSTER.anatomical_location_relative. |
|
‘Presence’ (on examination) | Consistent description phrasing for data elements identifying the presence or absence of a clinical finding on examination. | Description: |
|
Repeatable data elements and clusters | Proposal Any data element that is designated as repeatable, such as 1..* or 0..* will be named in the singular. Each instance of the data element is intended to have a single corresponding value. This principle is also applied to repeatable clusters. Add a comment explaining what the purpose is of making the element repeatable. | Name:
Comment:
|
|
Codeable data elements | Proposal Add a comment reflecting the intended strength of the recommendation to code the element using an external terminology. | Comment:
Note: Agreed that ‘external’ is redundant in these phrases in NO Editorial meeting 2026-03-26 |
|
Additional details SLOT | Proposal In most ENTRY archetypes it will be relevant to add an 'Additional details' SLOT to be able to extend its contents using CLUSTER archetypes. |
|
|
Rational vs justification | Proposal 2026 01 29
| Examples:
|
|
Scores and Scales
Description | Example | |
|---|---|---|
Concept name | Model as the full name of the score or scale. If the name is also used as an acronym, model the name in capitals, including the acronym in brackets. If the most common known name is an acronym, use the acronym as the name. |
|
| If the score or scale is a local variant, either by country, region or hospital, or a preliminary version made by a project or a vendor in anticipation of a formal review process leading to a published state, it is highly recommended to use a suffix to the archetype name to be able to differentiate from the published archetype. |
|
Archetype ID | Same as concept name but without the word 'scale' or 'score' - unless it is necessary to distinguish from another archetypes with a similar name. | See examples above. Also: |
Concept description | Record an explanation of the concept being recorded. |
|
Purpose | Record the reason for using this archetype to record data, not to describe the purpose of the score or scale itself. |
|
Use | Record how the archetype might be used in implementation, not how to perform the assessment. |