Custom resources on FHIR logical model

A logical model is a representation of data structures, that are not implemented in a FHIR specification. A FHIR logical data model - or simply logical model - is an expression of a data structure captured using FHIR. Logical models expressed via FHIR StructureDefinition resource, with kind property set to logical. For example:

 "kind": "logical",
 "abstract": false,
 "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Element",
 "derivation": "specialization",

Configure Aidbox

To begin using FHIR logical models, enable the FHIR Schema validator engine in Aidbox.

pageSetup Aidbox with FHIR Schema validation engine

Create StructureDefinition for custom resource

Let's define a custom resource called CustomUser. This resource contains two properties:

  1. name: This property represents the user's name and is of the FHIR HumanName type.

  2. field: This property is for arbitrary text and is of the FHIR string data type.

POST /fhir/StructureDefinition
content-type: application/json
accept: application/json

{
    "derivation": "specialization",
    "name": "CustomUser",
    "abstract": "false",
    "type": "CustomUser",
    "resourceType": "StructureDefinition",
    "status": "active",
    "id": "CustomUser",
    "kind": "logical",
    "url": "http://example.org/StructureDefinition/CustomUser",
    "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Element",
    "differential": {
        "element": [
            {
                "id": "CustomUser",
                "path": "CustomUser",
                "min": 0,
                "max": "*"
            },
            {
                "id": "CustomUser.name",
                "path": "CustomUser.name",
                "min": 0,
                "max": "*",
                "type": [
                    {
                        "code": "HumanName"
                    }
                ]
            },
            {
                "id": "CustomUser.field",
                "path": "CustomUser.field",
                "min": 1,
                "max": "1",
                "type": [
                    {
                        "code": "string"
                    }
                ]
            }
        ]
    }
}

Response:

Status: 200
{
 "derivation": "specialization",
 "name": "CustomUser",
 "abstract": "false",
 "type": "CustomUser",
 "resourceType": "StructureDefinition",
 "status": "active",
 "id": "CustomUser",
 "kind": "logical",
 "url": "http://example.org/StructureDefinition/CustomUser",
 "differential": {
  "element": [
   {
    "id": "CustomUser",
    "path": "CustomUser",
    "min": 0,
    "max": "*"
   },
   {
    "id": "CustomUser.name",
    "path": "CustomUser.name",
    "min": 0,
    "max": "*",
    "type": [
     {
      "code": "HumanName"
     }
    ]
   },
   {
    "id": "CustomUser.field",
    "path": "CustomUser.field",
    "min": 1,
    "max": "1",
    "type": [
     {
      "code": "string"
     }
    ]
   }
  ]
 },
 "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Element"
}

Interact with a resource

Let's create an instance of CustomUser resource

POST /fhir/CustomUser
content-type: application/json
accept: application/json

{
  "resourceType": "CustomUser",
  "name": [{"use": "nickname", "text": "test-user"}],
  "field": "some-field"
}

Let's try to create invalid CustomUser resource

POST /fhir/CustomUser
content-type: application/json
accept: application/json

{
  "resourceType": "CustomUser",
  "name": [{"use": "wrong-code", "text": "test-user"}]
}

Convenience

Manually writing StructureDefinitions can be overwhelming. Fortunately, there is an alternative: FSH/SUSHI allows you to generate a FHIR NPM package with your custom resources, which you can load into Aidbox and use.

pageUpload FHIR Implementation Guide

Last updated