introduction

Introduction

Scope and Usage

The StructureDefinition resource describes a structure - a set of data element definitions, and their associated rules of usage. These structure definitions are used to describe both the content defined in the FHIR specification itself - Resources, data types, the underlying infrastructural types, and also are used to describe how these structures are used in implementations. This allows the definitions of the structures to be shared and published through repositories of structure definitions, compared with each other, and used as the basis for code, report and UI generation.

Note that as part of the specification itself, a full set of structure definitions for all resources and data types is published.

Boundaries and Relationships

• StructureDefinitions are used by CapabilityStatement instances for specifying how resources are used
• StructureDefinitions use Value Sets to specify the content of coded elements

Background and Context

Implementers should be familiar with the background and concepts described in Profiling FHIR before working with this resource.

Metadata

The StructureDefinition resource has a set of metadata that is mostly shared with the Value Set, CapabilityStatement and other infrastructure resources. The metadata describes the structure and helps find the structure when registered in repositories.

Note that there may be multiple resource versions of the structure that have this same identifier. The resource will have updates that create new versions for technical reasons, whereas the stated version number needs to be under the author's control. The version can be appended to the url in a reference to allow a reference to a particular business version of the structure definition with the format [url]|[version].

| | versionAlgorithm | Indicates the mechanism used to compare versions to determine which is more current | | name | A Computer-ready name (e.g. a token) that identifies the structure - suitable for code generation. Note that this name (and other names relevant for code generation, including element & slice names, codes etc.) may collide with reserved words in the relevant target language, and code generators will need to handle this | | title | A free text natural language name identifying the structure | | status | The status of the structure allows filtering of StructureDefinitions that are appropriate for use vs. not. See the Status Codes | | experimental | This structure was authored for testing purposes (or education/evaluation/marketing), and is not intended for genuine usage | | date | The date this version of the structure was published | | publisher | Details of the individual or organization who accepts responsibility for publishing the structure. This helps establish the "authority/credibility" of the structure. | | contact | Contact details to assist a user in finding and communicating with the publisher | | description | A free text natural language description of the structure and its use | | purpose | Why this structure was created - what the intent of it is | | useContext & Jurisdiction | Computable details about purpose and scope of use | | copyright | Notice about intellectual property ownership, can include restrictions on use | | fhirVersion | The version of the FHIR specification on which this structure is based. It is not necessary to specify the version, as most StructureDefinitions are valid across multiple versions, and the validity of a structure against a particular version of FHIR can easily be checked by tooling. | | type | The type the structure describes. | | contextType & context | For extensions, the types of contexts in which the extension can be used. For further details, see Defining Extensions |

Notes:

• The name and title of the structure are not required to be globally unique, but the name and title should have some scoping information (e.g. AcmeAllergies / Acme Inc. (USA), Allergy List)
• Multiple keywords may be assigned to the structure. These may either describe the structure, the focus of the structure or both. They are solely to help find the structure by searching for structured concepts
• The 3 status codes (draft, active, and retired) are the codes that are relevant to structure consumers. Authors may wish to use the authoring-status extension to track the life cycle of a structure as it is prepared

Notes

Interpretation Notes:

• A structure is represented as a flat list of elements. The element.path provides the overall structure.
• Differentials in constraints need only specify elements that they are making rules about. Other elements can be inferred as defined in the base resource
• Elements specified in the differential (and all elements in the snapshot) must be ordered as such:
  • Elements from the baseDefinition appear before new elements in a StructureDefinition with derivation 'specialization'
  • Elements must be in the same order as the baseDefinition, and child elements appear in depth-first order.
  • Unsliced descendants of sliced elements appear before slices
• element.short, element.formal, element.comments and element.mapping provide the specific definition for the field in a specific context.
• element.type is used to specify which types may be used for this element. If there is more than one type, the element offers a choice of types and must have a name that terminates in "[x]". (Note: when substituting [x] with a specific data type, always capitalize the first letter. Choice types are always camel-case. Ex: "effectiveDateTime" is correct, "effectivedateTime" is NOT correct.)
• When using XPath to define constraints about the relationship between the contents of the narrative and the contents of the data elements, the element against which the rule is expressed is the one against which the error or warning will be reported by a validator.
• When expression constraints are placed on elements that offer a choice of types, the expression has to select the type to which it applies using the FHIRPath as operator.
• The condition element is used to assert that a constraint defined on another element affects the allowed cardinality of this element.

StructureDefinition Root Elements

The very first element in a snapshot (the one with an element id of just the type name) defines characteristics that apply to the type as a whole. Some of these characteristics affect the constraints that can hold on an element that references the type. For example, if the root element cardinality is 0..1, then an element declared to be of that type cannot have a maximum cardinality greater than 1. (This is often used when defining extensions to indicate that multiple extension repetitions of that type are not allowed within a single element.)

In some cases, there can be redundancy between content defined on the root element and that defined on the StructureDefinition itself. For example, ElementDefinition has 'definition' while StructureDefinition has 'description'. These may have the same content put both places, though technically the 'definition' is text that describes what the type 'means', while 'description' is broader and may talk a bit about what the resource/data type/profile is for, in addition to its meaning.

Different Uses for StructureDefinition

The base structure definition is used in a number of different ways to support the FHIR specification. The various uses of the StructureDefinition are controlled by the elements kind, type, base, and url, using this basic pattern:

{ "url": the identity of this structure definition, "kind": (primitive-type | complex-type | resource | logical), "type": the type being constrained (if it's a constraint) "abstract" : {true | false}, "baseDefinition": the structure definition from which this is derived }

This list shows a number of examples, with links to real examples for each:

1. Base definition of a data type (example: Quantity - XML, JSON):

   { "resourceType": "StructureDefinition", "url": "http://hl7.org/fhir/StructureDefinition/Quantity", "name": "Quantity", "kind": "complex-type", "abstract" : false, "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Element" }

2. A constrained data type (example: Money - XML, JSON):

   { "resourceType": "StructureDefinition", "url": "http://hl7.org/fhir/StructureDefinition/Money", "name": "Money", "kind": "complex-type", "type": "Quantity", "abstract" : false, "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Quantity" }

3. Base definition of a resource (example: Patient - XML, JSON):

   { "resourceType": "StructureDefinition", "url": "http://hl7.org/fhir/StructureDefinition/Patient", "name": "Patient", "kind": "resource", "abstract" : false, "baseDefinition": "http://hl7.org/fhir/StructureDefinition/DomainResource" }

4. Base Extension (a standard data type) (example: Extension - XML, JSON):

   { "resourceType": "StructureDefinition", "url": "http://hl7.org/fhir/StructureDefinition/Extension", "name": "Extension", "kind": "complex-type", "abstract" : false, "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Element" }

5. A defined Extension (example: Extension Data Absent Reason - XML, JSON):

   { "resourceType": "StructureDefinition", "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason", "name": "Data Absent Reason", "kind": "complex-type", "type": "Extension", "abstract" : false, "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Extension" }

6. A constraint on a defined extension (no examples currently defined):

   { "resourceType": "StructureDefinition", "url": "http://example.org/fhir/StructureDefinition/race", "name": "Race codes used by institution (a subset of meaningful use codes)", "kind": "complex-type", "type": "Extension", "abstract" : false, "baseDefinition": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race" }

7. A base abstract Resource (see e.g. Resource):

   { "resourceType": "StructureDefinition", "url": "http://hl7.org/fhir/StructureDefinition/Resource", "name": "Resource", "kind": "resource", "type": "Resource", "abstract" : true, "baseDefinition": "http://hl7.org/fhir/us/core/StructureDefinition/Base" }

8. An interface defined in the base specification (see e.g. CanonicalResource):

   { "resourceType": "StructureDefinition", "url": "http://hl7.org/fhir/StructureDefinition/CanonicalResource", "name": "CanonicalResource", "kind": "resource", "type": "CanonicalResource", "abstract" : true, "baseDefinition": "http://hl7.org/fhir/us/core/StructureDefinition/DomainResource" }

9. A logical model (see e.g. Definition):

   { "resourceType": "StructureDefinition", "url": "http://hl7.org/fhir/StructureDefinition/Definition", "name": "Definition", "kind": "logical", "type": "Definition", "abstract" : false, "baseDefinition": "http://hl7.org/fhir/us/core/StructureDefinition/Base" }

On this list, structure definitions of type 1, 3, 5 and 8 - 9 can only be defined by the FHIR specification itself. The other kinds of structure definitions are (or may be) created by the specification but can also be defined by other implementers.

Rules for Constrained Types

When the structure is a constraint (derivation = constraint), see Extending and Restricting Resources for the rules that apply.

Common Mapping Targets

Structures are able to map elements to concepts in other definition systems. Generally, these are used to map the elements to local implementation models, data paths, and concepts. However they are also used to map to other standards and published terminologies. These are the standard URIs used for common targets of the mapping:

[%mappings-table%]

Logical Models

StructureDefinitions are used to define the basic structures of FHIR: data types, resources, extensions, and profiles. The same definition structure can also be used to define any arbitrary structures that are a directed acyclic graph with typed nodes, where the primitive types are those defined by the FHIR specification.

This technique has many uses:

• Describing any arbitrary content model
• Describing existing HL7 content models (e.g. v2, CDA) using FHIR
• Describing common design patterns used in FHIR
• Defining a content model to support the mapping language

Using StructureDefinitions to Define Additional Resource

Additional resources are defined by StructureDefinition resources, following these rules:

• The canonical URL of the definition is in some other canonical space than http://hl7.org/fhir
• The fhirVersion SHALL be 6.0.0 or a subsequent published version of FHIR
• The kind SHALL be resource
• abstract SHALL be false
• The type SHALL match the canonical URL exactly
• The baseDefinition SHALL be a direct reference to one of the abstract resources published by this specification (Resource or DomainResource). Resources MAY also use the implements extension to indicate adherence to the CanonicalResource or MetadataResource Interfaces
• The derivation SHALL be specialization
• The root of the element path SHALL be the tail of the canonical URL
• The root of the element SHOULD be the name assigned by HL7 to the resource
• The compartments for the resource are defined by using the (yet to be published) extension http://hl7.org/fhir/StructureDefinition/additional-resource-compartment

Here is an example with other properties removed:

{ "resourceType" : "StructureDefinition", "url" : "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/ViewDefinition", "fhirVersion" : "6.0.0", "kind" : "resource", "abstract" : false, "type" : "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/ViewDefinition", "baseDefinition" : "http://hl7.org/fhir/StructureDefinition/CanonicalResource", "derivation" : "specialization", "differential" : { "element" : [{ "path" : "ViewDefinition", // snip }] } }

Once defined, additional resources are profiled like any other resource.

StructureDefinition

Elements (Simplified)

Mapping Exceptions

structuredefinition-fivews-mapping-exceptions.xml

Unmapped Elements

• FiveWs.what — Not relevant for this resource
• FiveWs.author — Not relevant for this resource
• FiveWs.actor — Not relevant for this resource
• FiveWs.cause — Not relevant for this resource
• FiveWs.where — Not relevant for this resource
• FiveWs.context — Unknown
• FiveWs.init — Not relevant for this resource
• FiveWs.source — Not relevant for this resource
• FiveWs.who — Not relevant for this resource
• FiveWs.grade — Not relevant for this resource
• FiveWs.planned — Not relevant for this resource
• FiveWs.done — Not relevant for this resource
• FiveWs.subject — Not relevant for this resource