Skip to content

Conventions for StructureDefinitions

Jump to bottom
dtr-agency edited this page Dec 8, 2021 · 13 revisions

This page describes conventions and principles for StructureDefinitions in this repository.

Metadata conventions for StructureDefinitions

Element Include Conventions
id Y <resourcename>-<usecase>-<major version>, or <resourcename>-<usecase>-<usecase>-<major version>. See detailed conventions later on in this page.
language N Elements we shall not use yet as we don't have a good understanding of their use and processing in implementations.
url Y All Agency defined FHIR profiles and extensions SHALL include the canonical URL that always identifies the resource. The canonical URL for all Agency profiles shall be in the format <namespace>/<id>. The namespace is "http://ns.electronichealth.net.au/ci/fhir/3.0/StructureDefinition" See detailed conventions later on in this page.
identifier N We have no additional identifiers for structure definitions.
version Y X.Y.Z where X, Y and Z are non-negative integers and MUST NOT contain leading zeroes. Start with '1.0.0' - this is an aspirational version that SHALL NOT change until the StructureDefinition / ImplementationGuide is frozen for use. See detailed conventions later on in this page.
name Y The convention for name is that it starts with and is to be a natural language abbreviated description in upper camel case and with no white-spaces e.g. PatientIHI. See detailed conventions later on in this page.
title Y Title is a short, descriptive, user-friendly title for the artifact. The convention for title is to be a full human readable description in title case, that is grammatically correct, preferably with full expansion of any abbreviations included in the name unless those expansions are foreign to readers e.g. Patient with Mandatory IHI. See detailed conventions later on in this page.
status Y While in development and review it should be 'draft', and when published for use this should be 'active'.
experimental Y While in development and review it should be 'true', and when published for use this should be 'false'.
date F Should be populated when the StructureDefinition is published for approved use - otherwise can be poupulated while in dev but not required.
publisher Y 'Australian Digital Health Agency'
contact Y contact.telecom system 'email'; contact.telecom value 'help@digitalhealth.gov.au'
description Y To be populated as well formatted markdown: <purpose and description paragraph> e.g. The purpose of this profile is to provide a summary statement for a medication including asserting negation for a specific medication. It is intentional that detailed medication information have not been included; this is intended to be a short summary. <must support declarations>. See detailed conventions later on in this page.
useContext N Do not include.
jurisdiction N Do not include.
purpose N Do not include.
copyright Y 'Copyright © 2020 Australian Digital Health Agency - All rights reserved. This content is licensed under a Creative Commons Attribution 4.0 International License. See https://creativecommons.org/licenses/by/4.0/.' plus if the profile has a code that is a fixed value from SNOMED CT then the required copyright shall follow the Agency statement. If the profile has a code that is fixed value from LOINC then the required copyright shall follow the Agency statement.
keyword N Do not include.
fhirVersion Y '3.0.2'

legend for Include column:

Y - always include

F - include in final form of the artefact when published for use

N - never include

Additionally we do not intend to complete any meta elements - these are out of scope for authoring profile metadata. This content is maintained by the infrastructure and any manually provided values are expected to be overwritten by that infrastructure.

Version convention

All StructureDefinitions incl ImplementationGuide will be consistently versioned in accordance with the Semantic Versioning Specification.

Version number shall be a three digit number in the format X.Y.Z, where X, Y and Z are non-negative integers and MUST NOT contain leading zeroes.

X is the major version number, Y is the minor version number, and Z is the patch number. Each element must increment by an integer, i.e. add by one from their pre-increment state.

Example showing two sequential increments of the minor version number element: 1.9.0, 1.10.0, 1.11.0.

When a version content is released as 'Approved', it cannot be modified without incrementing the version number. Any modification must be released as a new version.

Major version increment

Major version increments every time an incompatible, breaking change is made. Every time the major version changes, minor and patch version must reset to 0. A breaking change is one where some possible instances that conform to the old specification do not conform to the new specification. Examples of major version changes are:

  • tightening a constraint on a data component,
  • adding a new constraint on a data component,
  • adding a mandatory data component,
  • removing values from a value set. Note that a new use case for a profile will require a new identity (new canonical URL).

Minor version increment

Minor version increments every time a backwards compatible, non-breaking change is made. Minor version resets to 0 every time the major version changes. A non-breaking change is one where every possible instance that conforms to the old specification also conforms to the new specification. Examples of minor version changes are:

  • relaxing a constraint on a data component,
  • adding an optional data component,
  • clarifying a definition.

Patch version increment

Patch version increments every time a backwards compatible, non-computable change is made. Patch number resets to 0 every time the minor or major version changes. An example of a patch version change is fixing typos.

All new StructureDefinitions in development shall have the major version one (1.y.z). New artefacts will start with the version number 1.0.0. This initial version number will remain the version until publication when the status is changed to 'active' and experimental is changed 'false'.

Version numbers - where to include?

  1. version number SHALL be included in .version; for example, StructureDefinition.version. Only the major version integer will be part of the canonical URL for a profile via the id.
  2. version number SHALL NOT be included in .meta.versionId. This would be used if, for example, storing a StructureDefinition on a server, with a meta element version and a version specific URL to reference a particular version.

id convention

In the format: <resourcename>-<usecase>-<major version>, or <resourcename>-<usecase>-<usecase>-<major version>.

The id is all lower case with no white spaces and ends on the major version integer.

The id does not include a prefix or a publisher abbreviation "-dh" with the exception of base profiles which shall have "-dh-base", <usecase> will be decided on a case by case base, it does not have to be a full word and can include meaningful abbreviations.

Some examples of canonical URLS for profiles in this repository:

Note the id convention for extensions also follows the above pattern and is further refined to clearly identify an extension and it's context.

id is in the following format: extension-<context (resource/datatype)>-<purpose>, or extension-<something meaningful>

Some examples of canonical URLS for extensions in this repository:

Name convention

Name is a machine readable name identifying the artefact. The name is usable as an identifier of the structure. It does not have to be unique. It can include alpha-numeric characters to ensure it is computer friendly.

The convention for name is that it is to be a natural language abbreviated description in upper camel case and with no whitespaces. Name always beings with the with the resource/extension name first.

Some examples are

  • PatientIHI
  • RelatedPersonIdent
  • MedicationRequestPharmaceuticalBenefitsScheme
  • ReferralVictoriaHealth
  • ExtensionDonationProvision
  • CompositionSHS
  • ImplementationGuideSHS
  • ImplementationGuidePersonalHealthRecords

Title convention

Title is a short, descriptive, user-friendly title for the artefact.

The convention for title is to be a full human readable description in title case, that is grammatically correct, preferably with full expansion of any abbreviations included in the name unless those expansions are foreign to readers.

Some examples are:

  • Patient with Mandatory IHI
  • RelatedPerson with Mandatory Identifier
  • PBS Claim Prescription Data
  • Victoria Health Jurisdictional Referral
  • Organ Donation Provision
  • Shared Health Summary Implementation Guide
  • Personal Health Records Implementation Guide

Description convention

description is to be populated as well formatted markdown:

<purpose and description paragraph> e.g.

The purpose of this profile is to provide a summary statement for a medication including asserting negation for a specific medication. It is intentional that detailed medication information have not been included; this is intended to be a short summary.

<must support declarations> i.e.

&#xa;&#xa;#### Must Support&#xa;&#xa;In the context of this profile [Must Support](http://hl7.org/fhir/STU3/conformance-rules.html#mustSupport) SHALL be interpreted as follows:&#xa;&#xa;* The system SHALL be capable of including the element when authoring a resource where data is available&#xa;&#xa;* The system SHALL be able to store and retrieve the elements&#xa;&#xa;* The system SHALL be able to process resources containing the elements

Please note that the description including must support declarations with markdown formatting will need to be added to a profile via a manual editor e.g. oXygen, as Forge adds its own markdown to already existing markdown.

As " " is the HTML representation of a line feed (new line), in the IG Published output these Unicode characters will appear as an actual new line (the description will 'appear' stripped of these characters).

Copyright conventions

copyright is to have the following statement:

Copyright © 2019 Australian Digital Health Agency - All rights reserved. This content is licensed under a Creative Commons Attribution 4.0 International License. See https://creativecommons.org/licenses/by/4.0/.

If the StructureDefinition includes content from SNOMED CT then the following statement shall follow:

This resource includes SNOMED Clinical Terms™ (SNOMED CT®) which is used by permission of the International Health Terminology Standards Development Organisation (IHTSDO). All rights reserved. SNOMED CT®, was originally created by The College of American Pathologists. “SNOMED” and “SNOMED CT” are registered trademarks of the IHTSDO. The rights to use and implement or implementation of SNOMED CT content are limited to the extent it is necessary to allow for the end use of this material. No further rights are granted in respect of the International Release and no further use of any SNOMED CT content by any other party is permitted. All copies of this resource must include this copyright statement and all information contained in this statement.

If the StructureDefinition includes content from LOINC then the following statement shall follow:

This resource contains content from LOINC™ (http://loinc.org). The LOINC Table, LOINC Table Core, LOINC Panels and Forms File, LOINC Answer File, LOINC Part File, LOINC Group File, LOINC Document Ontology File, LOINC Hierarchies, LOINC Linguistic Variants File, LOINC/RSNA Radiology Playbook, and LOINC/IEEE Medical Device Code Mapping Table are copyright © 1995-2017, Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http://loinc.org/license.

Invariant key convention

inv-dh-<abbreviated resource name using first three letters of each capitalised term>-xy

e.g.

  • Immunization profile invariant: inv-dh-imm-01
  • RelatedPerson invariant: inv-dh-relper-03

Use the same abbreviation that the FHIR resource uses in invariants

Slice name convention

The FHIR standard defines rules on naming slices: http://hl7.org/fhir/elementdefinition-definitions.html#ElementDefinition.sliceName

Additionally, slice names in the our profiles will be in:

  • camel case starting with a lower case letter; for example, organDonationConsent, specificOrganOrTissue,
  • decided on a case by case basis, for a specific use case

STU3 FHIR IG JSON controller file conventions

This section outlines metadata for the JSON controller file.

Please refer to the standard documentation on the use of this file: http://wiki.hl7.org/index.php?title=IG_Publisher_Documentation

This file is described as:

When the IG publisher is executed, it is pointed at a control file. This is a json file that contains all the information that the publisher needs to publish the implementation guide.

Filename In the format of 'ig-'<implementationguide.name(lowercase)>'-1.json'

eg "ig-eventsummary-1.json"

JSON elements Element order JSON is indifferent to element order, however to ensure consistency across our IGs, it has been agreed that the order of elements in the JSON file will be as follows.

legend for Include column:

Y - always include

F - include in final form of the artefact when published for use

N - never include

Table of elements Element Include Conventions version Y '3.0.1' paths output Y 'output/'<ImplementationGuide.name> eg "output/EventSummary" pages Y 'pages/'<ImplementationGuide.name> eg "pages/EventSummary" resources Y '[ "resources", "examples" ]' temp Y 'temp' qa Y 'qa' specification Y 'http://hl7.org/fhir/STU3' txCache Y 'txCache' history N Not used (default = no page marked as history page)

sct-edition Y http://snomed.info/sct/32506021000036107'

This allows use of the Australian edition (with drug extension) of SNOMED CT. Documented in this page: https://confluence.ihtsdotools.org/display/DOC/List+of+SNOMED+CT+Edition+URIs

extraTemplates Y '["mappings","examples"]' source Y <ImplementationGuide.id>'.xml' , e.g. 'implementationguide-eventsummary-1.xml' npm-name Y 'au.electronichealth.'<ImplementationGuide.name(lowercase)>, e.g. 'au.electronichealth.eventsummary'

tool Y 'jekyll' license Y 'Apache-2.0' canonicalBase Y 'http://ns.electronichealth.net.au/ci/fhir/3.0' logging Y '["init", "progress", "context", "html", "tx" ]'

Note this only affects the verbosity of the terminal output of the IG publisher. Currently this JSON node contains an array, with all documented logging options to result in the most verbose logging. This is not a requirement, per se, and is only useful when there is a build failure as the verbose logging can assist troubleshooting.

dependencyList name Y 'aubase' package N Not used location Y 'http://hl7.org.au/fhir/base' version Y either: 'current-stu3' - for the current build of STU3, or for a static HL7 AU version, the specific version number (e.g. 1.1.0). See instructions here about updating for static versions.

source N Not used defaults Y "defaults": { "CapabilityStatement": {"template-base": "capst.html"}, "ValueSet": {"template-base": "vs.html"}, "Any": { "template-base": "base.html", "template-format": "format.html" }, "StructureDefinition": { "template-defns": "sd-definitions.html", "template-base": "sd.html", "template-examples": "sd-examples.html", "template-mappings": "sd-mappings.html" }, "StructureMap": {"template-base": "sm.html"}, "Basic": {"template-base": "ex.html"}, "CodeSystem": {"template-base": "codesys.html"}, "ConceptMap": {"template-base": "cm.html"} },

resources Y This is where the individualised contents of the Implementation Guide are included, i.e. all StructureDefinition files are listed. But there are no additional CI conventions imposed on this inclusion. Unused elements fixed-business-version N Not to be used. This imposes a group management of versioning of capability resources in an implementation guide, i.e. all capability resources must have this same fixed-business-version. At this time CI manages all resources individually. html-template N Not used (default = none)

suppressedWarningFile N Not used as no warnings are currently suppressed. (default = none)

suppress-qa N Not used as all QA output is necessary for the creation of high quality resources. (default = don't suppress)

npm-template N Not used (default - no npm template in use)

jurisdiction N Not used (default - no jurisdiction specified) language N Not used (default - no language specified) languages N Not used (default - no languages specified) pre-process N Not used (default - no pre-processing in use) no-inactive-codes N Not used (default = false)

broken-links N Not used (default = warning)

check-aggregation N Not used check-mustSupport N Not used append-slash-to-dependency-urls N Not used anyExtensionsAllowed N Not used - Default produces an 'information' message rather than errors

hintAboutNonMustSupport N Not used gen-examples N Not used do-transforms N Not used extension-domains N Not used spreadsheets N Not used bundles N Not used special-urls N Not used swagger N Not used

Clone this wiki locally