-
Notifications
You must be signed in to change notification settings - Fork 3
Conventions for StructureDefinitions
This page describes the current conventions and principles for StructureDefinitions in this repository.
This approach is under active review and development; material may be added or updated on a regular basis.
| Element | Include | Conventions |
|---|---|---|
| id | Y |
dh-<resourcename>-<usecase>-<major version>, or dh-<resourcename>-<usecase>-<usecase>-<major version>. |
| language | N | Elements we shall not use yet as we don't have a solid position on 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/???" |
| identifier | N | At this time we have no additional identifiers for conformance artefacts. |
| version | Y | X.Y.Z where X, Y and Z are non-negative integers and MUST NOT contain leading zeroes. Start with '0.0.1' and incremented until a product release is frozen at a major version number '1.0.0'. |
| name | Y | The convention for name is that it includes the and is to be a natural language abbreviated description in upper camel case and with no white-spaces e.g. DHPatientIHI. |
| 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. ADHA Patient with Mandatory IHI. |
| 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 '[email protected]' |
| 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>. |
| useContext | N | Do not include. |
| jurisdiction | N | Do not include. |
| purpose | N | Do not include. |
| copyright | Y | 'Copyright © 2023 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 | '4.0.1' |
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.
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 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 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 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 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.
- 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.
Currently in the format: dh-<resourcename>-<usecase>-<major version>, or dh-<resourcename>-<usecase>-<usecase>-<major version>.
The id is all lower case with no white spaces and ends on the major version integer.
<usecase> will be decided on a case by case base, it does not have to be a full word and can include meaningful abbreviations.
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: dh-extension-<context (resource/datatype)>-<purpose>, or dh-extension-<something meaningful>
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 has the resource type present.
Some examples are
- DHPatientIHI
- DHRelatedPersonIdent
- MedicationRequestPharmaceuticalBenefitsScheme
- ReferralVictoriaHealth
- DHExtensionDonationProvision
- DHCompositionSHS
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:
- ADHA Patient with Mandatory IHI
- ADHA RelatedPerson with Mandatory Identifier
- ADHA PBS Claim Prescription Data
- Victoria Health Jurisdictional Referral
- Organ Donation Provision
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.
Current Agency copyright statement is the following, however this is not the source of truth and care should be taken to keep materials up to date.
Copyright © 2021 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-2021, 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.
For a core resource 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
For a use case resource inv-dh-<abbreviated use case name using two to six letters>-xy
e.g.
- Shared Health Summary Document Composition profile invariant: inv-dh-shs-01
- Event Summary Document Composition profile invariant: inv-dh-es-01
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