Skip to content

Conventions and principles for example resources

Jump to bottom
dtr-agency edited this page Jan 29, 2020 · 6 revisions

This page describes conventions and principles for example resources in this repository.

Principles

  • An example SHALL conform to the profile it is an example of. The below conventions are in addition to profile requirements
  • An example SHALL be valid FHIR
  • Examples SHOULD be semantically internally consistent as much as is possible
  • A profile / implementation guide SHOULD have greater than five examples
  • A set of examples for a profile / implementation guide SHOULD demonstrate multiple scenarios e.g. a composition with some empty sections and a composition without empty sections (assuming thats clinically reasonable)
  • A profile / implementation guide SHOULD have a mix of referencing (as long as it does not conflict with the profiles) e.g. bundle (mix of contained vs fullUrls), standalone, contained, use of logical ids as references, references on the 'server' i.e. the implementation guide
  • A profile / implementation guide SHOULD demonstrate a range of supplied data e.g. detailed structure, little structure, coded vs text etc.This page provides a description of the principles and conventions our artefacts.

Conventions for example files

Hyperlink text

The hyperlink for a document or list type should be in the convention <profile title> example <no.> (<type of referencing>), the no. only changes if the clinical content is different so there could be multiple instances of a no. 3 if there are different types of referencing displayed such as contained or bundle or reference by absolute uri. The numbers in <no.> will be used to match examples between the FHIR IG and CDA-IG so they have some significance.

Examples of hyperlink text:

  • Shared Health Summary example 1 (Bundle)
  • Shared Health Summary example 1 (Contained)
  • Shared Health Summary example 1 (References using logical ids)
  • Shared Health Summary example 1 (References using fullURLs)
  • Medicines List example 1 (Bundle)

Element inclusion

Element Include Conventions
id Y Should be a real world id for a FHIR resource instance (NOT an id with the word 'example' in it). Mix up the conventions a bit, e.g. uuids, oids, meaningful unique phrases such as in the NCTS value set ids or our profiles. The id should meet FHIR guidelines on resource ids.
meta Y Always include unless there is a strong usage scenario reason to not include, or the resource is contained and there is no profile requirement to include.
meta.versionId S Sometimes include, mix it up a bit from: a datetime, an integer, a uuid, an oid.
meta.lastUpdated S Sometimes include, has to be an instant and there are no other conventions.
meta.profile S Sometimes include if the resource doesn't have a profile it is required to conform to that governs this element - always conform to the profile.
meta.security N Do not include.
meta.tag N Do not include.
implicitRules N Do not include.
language S Sometimes include if the resource doesn't have a profile it is required to conform to that governs this element - always conform to the profile.
text S Almost always include, unless the resource is contained (contained resources aren't allowed to include text). This should most often be handcrafted but occasionally be generated.
identifier S here a resource, e.g. Observation or Composition, has an identifier element this should often, but not always, be populated. Mix up the conventions a bit including national or local identifiers and uuids vs oids vs meaningful unique phrases etc.
status Y Where a resource, e.g. MedicationStatement, has a status element this should always be populated even if the profile or resource do not mandate it.

legend for Include column:

Y - always include

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

N - never include

Conventions and guidance on example values

When producing contained examples

When producing 'contained' examples attention needs to be paid to the value in each of the contained resources. Some examples should have proper globally unique identifiers and some should have non-standard ids that only make sense / are unique in that file e.g. "Patient01" or "Bob".

Containment is intended for resources that do not have an independent existence from their container. See http://hl7.org/fhir/STU3/references.html#contained and the same in R4. We need examples that demonstrate the guidance in the FHIR standard - contained resources that do not have robust identifiers, and use identifiers that are clearly only unique within the content of the container.

However contained examples with proper globally unique ids as this is the most common implementation in AU at the moment including MHR mobile gateway which is why we have some examples that don't follow the FHIR guidance but demonstrate an ok way to do contained resources the way the Australian implementations are using containment in practice.

When using example URLs

Use the following second level domain names for examples as appropriate:

  • example.com
  • example.net
  • example.org
  • example.edu

This supports examples such as: example.edu/au, hospital.example.org, mobile.healthrecords.example.com/cust00123, wyle.e.cyote@mail.acme.example.net

When including example email addresses

Example email addresses can be made up of the following:

  • a Gmail address that has a username less than six letters long. Gmail doesn't allow usernames that short, so this approach ensures that you're not accidentally giving a real username. For example, you can use liz@gmail.com or darcy@gmail.com.
  • an address ending in a registered example domain. For example you can use liz@example.com or darcy@example.edu

When including Australian phone numbers

All example Australian phone numbers should be selected from the numbers set aside by the Australian Communications and Media Authority. They are currently documented here: https://www.acma.gov.au/Citizen/Phones/Numbers/Special-numbers/fictitious-numbers-for-radio-film-and-television-i-acma

When including an HI identifier

These example values should be used in examples that are consistent with the persona where possible, e.g. an IHI always has an associated name and address etc. though this may not always be possible. See DigitalHealth_HITestdata_072019.xlsx for the personas available. These HI values are assigned in the vendor environment but are not accessible in production.

When including an IHI there are seven values assigned to CI for use in documentation and examples

  • 8003608833357361
  • 8003608833564727
  • 8003608166895854
  • 8003608833564735
  • 8003608000228437
  • 8003608000228445
  • 8003608333563104

When including an HPI-I there are seven values assigned to CI for use in documentation and examples

  • 8003619900015717
  • 8003618233375103
  • 8003616566708106
  • 8003611566708354
  • 8003618233375111
  • 8003619900041630
  • 8003614900041243

When including an HPI-O there are seven values assigned to CI for use in documentation and examples

  • 8003621566684455
  • 8003623233366565
  • 8003626566699734
  • 8003623233366573
  • 8003626566699742
  • 8003621566699776
  • 8003629900033370

When including a PAI identifier

When including a PAI-O there are six known test values values:

  • 8003640011000000
  • 8003640011000018
  • 8003640011000026
  • 8003640011000034
  • 8003640011000042
  • 8003640011000059

When including a PAI-R there are six known test values values:

  • 8003640012000009
  • 8003640012000017
  • 8003640012000025
  • 8003640012000033
  • 8003640012000041
  • 8003640012000058

When including a PAI-D there are six known test values values:

  • 8003640013000008
  • 8003640013000016
  • 8003640013000024
  • 8003640013000032
  • 8003640013000040
  • 8003640013000057

Production values vs Test values

The test values of PAI identifiers are in a test arc arc of '1':

  • production PAI-O is in the format 8003640001xxxxxz, test PAI is 8003640011xxxxxz
  • production PAI-R is in the format 8003640002xxxxxz, test PAI-O is 8003640012xxxxxz
  • the production PAI-D is in the format 8003640003xxxxxz, test PAI-D is 8003640013xxxxxz
Clone this wiki locally