While FHIR uses two different ways to define core elements and extensions, zen profiles provide unified framework to describe both. Zen FHIR format offers user-defined elements or "first-class extensions". In zen profiles, you can define new attributes (elements) for existing (FHIR) resources.
The example below shows how to define extensions in zen profiles.
resourceType: Patient
id: sample-pt
extension:
- url: http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
extension:
- url: text
valueString: Asian Indian
- url: ombCategory
valueCoding:
system: urn:oid:2.16.840.1.113883.6.238
code: 2028-9
display: Asian
- url: detailed
valueCoding:
system:
code: 2029-7
display: Asian Indian
Note that extension elements have :confirms to a FHIR primitive or complex type specified. Previously these were specified in the base profile schema. These :confirms and the :fhir/extensionUri are needed to allow zen FHIR <-> FHIR format transformation.
Steps to define first-class extension as zen profile:
Initialize zen project and add additional IGs if necessary.
Define your custom first-class extension. For syntax and more examples refer to this page.
Define :fhir/extensionUri property value.
:fhir/extensionUri "http://tenant-id-extension-url" is an equivalent of the extensionUrl field of the Attribute resource and used to form FHIR extension.
Replace plain zen type by FHIR type in your extensions.
I.e. use :confirms #{hl7-fhir-r4-core.string/schema} instead of :type zen/string.
Define new extension with Attribute
In Aidbox, you can define first-class extensions using the custom resource Attribute.
Let's create an extension definition of type Reference in the REST Console of Aidbox:
Create new extension in the Aidbox format:
PUT /Attribute/ServiceRequest.requestedOrganizationDepartment
description: Department in the organization that made the service request
resource: {id: ServiceRequest, resourceType: Entity}
path: [requestedOrganizationDepartment]
type: {id: Reference, resourceType: Entity}
refers:
- Organization
extensionUrl: urn:extension:requestedOrganizationDepartment
description - string.
Attribute text description
resource - required, Reference(Entity).
Reference to a target resource type
path - required, array of strings.
Path to a new attribute location in the target resource type
type - Reference(Entity).
Type of data stored in this attribute. Can be any primitive or complex type.
If omitted, treated as BackboneElement, i.e. a complex-type object with structure defined via other Attributes relying on this attribute in their path
isCollection - boolean.
Whether the attribute is a collection, i.e. if true sets attribute cardinality to ..*
isRequired - boolean.
Whether the attribute is required, i.e. if true sets attribute cardinality to 1..
isUnique - boolean.
Sets unique restriction on the attribute.
refers - Reference(Entity).
Only for type=Reference. Specifies to which resourceTypes this reference can refer to
extensionUrl - string.
URL which will be used to create extension element in FHIR format. If omitted, Attribute won't be transformed in FHIR format
Note: you can not use Attributes and zen profiles on the same resource at the same time
Use your extension
Now, you can create the ServiceRequest resource using the new attribute requestedOrganizationDepartment in the root of the resource:
Create resource in the Aidbox format:
PUT /ServiceRequest/servicerequest-with-aidbox-native-extensions
requestedOrganizationDepartment:
resourceType: Organization
display: City Hospital Neurology Department
identifier: {system: 'urn:oid:1.2.3.4.5.6.7.8', value: '456'}
category:
- coding:
- {code: '183829003',
system: 'http://snomed.info/sct',
display: "Refer for imaging"}
authoredOn: '2020-01-18T15:08:00'
resourceType: ServiceRequest
requester:
resourceType: PractitionerRole
display: Din Morgan
identifier: {value: "1760", system: 'urn:oid:1.2.3.4.5.6.7.6'}
priority: routine
status: active
intent: original-order
performer:
- resourceType: Organization
display: Aga Khan University Hospital Laboratory
identifier: {value: "1514", system: 'urn:oid:1.2.3.4.5.6.7.8'}
subject:
resourceType: Patient
display: Jack Black, 10.12.1941
identifier: {value: '2155800871000065', system: 'urn:oid:1.2.3.4.5.6.7.9'}
FHIR Format
You can get the resource in the FHIR format where our new attribute is rendered as the extension element:
Note that the URL is different:GET /fhir/ServiceRequest/
Get the resource in the FHIR format:
GET /fhir/ServiceRequest/servicerequest-with-aidbox-native-extensions
extension:
- url: urn:extension:requestedOrganizationDepartment
valueReference:
type: Organization
identifier: {value: '456', system: 'urn:oid:1.2.3.4.5.6.7.8'}
display: City Hospital Neurology Department
category:
- coding:
- {code: '183829003',
system: 'http://snomed.info/sct',
display: "Refer for imaging"}
meta:
lastUpdated: '2020-02-04T09:15:18.664293Z'
versionId: '32'
extension:
- {url: 'ex:createdAt', valueInstant: '2020-02-04T09:12:20.103301Z'}
authoredOn: '2020-01-18T15:08:00'
resourceType: ServiceRequest
requester:
type: PractitionerRole
identifier: {value: '1760', system: 'urn:oid:1.2.3.4.5.6.7.6'}
display: Din Morgan
priority: routine
status: active
id: servicerequest-with-aidbox-native-extensions
intent: original-order
subject:
type: Patient
identifier: {value: '2155800871000065',
system: 'urn:oid:1.2.3.4.5.6.7.9'}
display: Jack Black, 10.12.1941
performer:
- type: Organization
identifier: {value: '1514', system: 'urn:oid:1.2.3.4.5.6.7.8'}
display: Aga Khan University Hospital Laboratory
Other extension examples
Let's create an extension of type Reference and list allowed resource types (Organization in that case) in the refers property.
managingOrganization
PUT /Attribute/ServiceRequest.managingOrganization
resourceType: Attribute
description: Organization that made the service request
resource: {id: ServiceRequest, resourceType: Entity}
path: [managingOrganization]
id: ServiceRequest.managingOrganization
type: {id: Reference, resourceType: Entity}
refers:
- Organization
extensionUrl: urn:extension:requestedOrganization
Extension of type Coding:
paymentType
PUT /Attribute/ServiceRequest.paymentType
resourceType: Attribute
description: Payment type for the service request, e.g. government health insurance
id: ServiceRequest.paymentType
resource:
id: ServiceRequest
resourceType: Entity
path:
- paymentType
type:
id: Coding
resourceType: Entity
extensionUrl: urn:extension:paymentType
Create resource using these extensions:
PUT /ServiceRequest/servicerequest-with-aidbox-native-extensions
managingOrganization:
resourceType: Organization
display: City Hospital
identifier: {value: "123", system: 'urn:oid:1.2.3.4.5.6.7.8'}
requestedOrganizationDepartment:
resourceType: Organization
display: City Hospital Neurology Department
identifier: {system: 'urn:oid:1.2.3.4.5.6.7.8', value: '456'}
paymentType: {system: 'urn:CodeSystem:paymentType',
code: "1",
display: "Government Health Insurance"}
resourceType: ServiceRequest
status: active
intent: original-order
subject:
resourceType: Patient
display: Jack Black, 10.12.1941
identifier: {value: '2155800871000065', system: 'urn:oid:1.2.3.4.5.6.7.9'}
Get resource in the FHIR format:
GET /fhir/ServiceRequest/servicerequest-with-aidbox-native-extensions
resourceType: ServiceRequest
extension:
- url: urn:extension:requestedOrganization
valueReference:
type: Organization
identifier: {value: '123', system: 'urn:oid:1.2.3.4.5.6.7.8'}
display: City Hospital
- url: urn:extension:requestedOrganizationDepartment
valueReference:
type: Organization
identifier: {value: '456', system: 'urn:oid:1.2.3.4.5.6.7.8'}
display: City Hospital Neurology Department
- url: urn:extension:paymentType
valueCoding: {code: '1',
system: 'urn:CodeSystem:paymentType',
display: Government Health Insurance}
status: active
id: servicerequest-with-aidbox-native-extensions
intent: original-order
subject:
type: Patient
identifier: {value: '2155800871000065', system: 'urn:oid:1.2.3.4.5.6.7.9'}
display: Jack Black, 10.12.1941
Nested extensions
Let's create a structure of nested attributes:
performerInfo
PUT /Attribute/ServiceRequest.performerInfo
resourceType: Attribute
description: Information filled in by performer
resource: {id: ServiceRequest, resourceType: Entity}
path: [performerInfo]
id: ServiceRequest.performerInfo
extensionUrl: urn:extension:performerInfo
PUT /Attribute/ServiceRequest.precondition
resourceType: Attribute
description: "The condition or state of the patient, prior or during
the diagnostic procedure or test, for example, fasting, at-rest,
or post-operative. This captures circumstances that may influence
the measured value and have bearing on the interpretation of the result."
resource: {id: ServiceRequest, resourceType: Entity}
path: [precondition]
id: ServiceRequest.precondition
type: {id: CodeableConcept, resourceType: Entity}
isCollection: true
extensionUrl: "http://hl7.org/fhir/StructureDefinition/servicerequest-precondition"
Let's create a resource in the FHIR format:
Create resource in the FHIR format:
PUT /fhir/ServiceRequest/servicerequest-with-aidbox-native-extensions
resourceType: ServiceRequest
status: active
intent: original-order
subject:
type: Patient
display: Jack Black, 10.12.1941
extension:
- url: http://hl7.org/fhir/StructureDefinition/servicerequest-precondition
valueCodeableConcept:
text: After calorie fasting
coding:
- code: "726055006"
system: http://snomed.info/sct
display: After calorie fasting
- url: http://hl7.org/fhir/StructureDefinition/servicerequest-precondition
valueCodeableConcept:
text: At rest
coding:
- code: "263678003"
system: http://snomed.info/sct
display: At rest
Let's get the resource in the Aidbox format:
Get resource in the Aidbox format:
GET /ServiceRequest/servicerequest-with-aidbox-native-extensions
resourceType: ServiceRequest
id: servicerequest-with-aidbox-native-extensions
intent: original-order
status: active
subject: {type: Patient, display: 'Jack Black, 10.12.1941'}
precondition:
- text: After calorie fasting
coding:
- {code: '726055006',
system: 'http://snomed.info/sct',
display: After calorie fasting}
- text: At rest
coding:
- {code: '263678003',
system: 'http://snomed.info/sct',
display: At rest}
Create FHIR primitive type extension
FHIR primitive named fieldName can be extended with _fieldName field. Aidbox treats fieldName as independent from fieldName. Aidbox do not validate fields with names started with underscore.
Suppose we need to extend Patient.gender attribute with primitive type. It means, that we need to create Patient._gender attribute.
