Skip to content

How to bind a Value Set to an element in a profile

When a Value Set and a Code System are successfully posted to the Terminology Service, they can be used in the resources where binding strength is allowed. But what if we need to change the binding strength and bind a new ValueSet to an element? It can be done by creating a new profile for a resource and changing the binding in the definition of the element. First, choose a profile for the resource. You can use a base FHIR profile or pick a profile from one of the Implementation Guides that suits your project needs the most. For this example, we will use an FHIR profile for Observation. Since we are creating a new profile, we will need to change the profile's id, name, url and, optionally, version, publisher, date, contact, description, and purpose. You can use a Kodjin FHIR Profiler Tool to make profile editing easier. This tool will validate your profile on the go and show syntax and validation errors.

    {
        "resourceType": "StructureDefinition",
        "id": "Observation",
        "meta": {
            "lastUpdated": "2019-11-01T09:29:23.356+11:00"
        },
        "text": {
            "status": "generated",
            "div": "<div>!-- Snipped for Brevity --></div>"
        },
        "extension": [
            …
        ],
        "url": "http://hl7.org/fhir/StructureDefinition/Observation",
        "version": "4.0.1",
        "name": "Observation",
        "status": "active",
        "date": "2019-11-01T09:29:23+11:00",
        "publisher": "Health Level Seven International (Orders and Observations)",
        "contact": [
            {
                "telecom": [
                    {
                        "system": "url",
                        "value": "http://hl7.org/fhir"
                    }
                ]
            },
            {
                "telecom": [
                    {
                        "system": "url",
                        "value": "http://www.hl7.org/Special/committees/orders/index.cfm"
                    }
                ]
            }
        ],
        "description": "Measurements and simple assertions made about a patient, device or other subject.",
        "purpose": "Observations are a key aspect of healthcare.  This resource is used to capture those that do not require more sophisticated mechanisms."
    …

    {
        "resourceType": "StructureDefinition",
        "id": "Observation-example-of-binding",
        "meta": {
            "lastUpdated": "2023-02-16T09:29:23.356+11:00"
        },
        "text": {
            "status": "generated",
            "div": "<div>!-- Snipped for Brevity --></div>"
        },
        "extension": [
            …
        ],
        "url": "https://kodjin-example.edenlab.dev/fhir/StructureDefinition/Observation-example-of-binding",
        "version": "4.0.1",
        "name": "Observation example of binding",
        "status": "active",
        "date": "2023-02-16T09:29:23.356+11:00",
        "publisher": "Edenlab IT",
        "contact": [
            {
                "telecom": [
                    {
                        "system": "url",
                        "value": "https://kodjin.com/"
                    }
                ]
            }
        ],
        "description": "This is an example of changing binding for an element",
        "purpose": "Show how to change a binding for an element"


    …

Now, let’s find an element definition we want to change and go to the binding section. In this example, it is Observation.code. Change the URL of a valueSet and, optionally, the binding strength:

      "binding": {
                "extension": [
                    {
                        "url": "http://hl7.org/fhir/StructureDefinition/elementdefinition-bindingName",
                        "valueString": "ObservationCode"
                    }
                ],
                "strength": "example",
                "description": "Codes identifying names of simple observations.",
                "valueSet": "http://hl7.org/fhir/ValueSet/observation-codes"
            },

     "binding": {
                "extension": [
                    {
                        "url": "http://hl7.org/fhir/StructureDefinition/elementdefinition-bindingName",
                        "valueString": "ObservationCode"
                    }
                ],
                "strength": "required",
                "description": "Codes identifying names of simple observations.",
                "valueSet": "http://hl7.org/fhir/ValueSet/Observation-example-of-binding"
            },

If you are using the Kodjin FHIR Profiler Tool, you can validate the profile now to ensure there are no errors.

screenshot of Kodjin FHIR Profiler Tool

If the profile is valid, you can upload it to the server. Like with CodeSystems and ValueSets, a profile can be uploaded in two different ways: via the GitHub repository or API.

Upload Structure Definition via API

  1. Upload a new profile by posting to {{host}}/fhir/StructureDefinition
  2. Wait several minutes until it is cached
  3. Check that everything works fine by calling a $validate operation on your Resource Type, referencing the profile in meta: {{host}}/fhir/{{resource_type}}/$validate

Upload Structure Definition via the GitHub Repository

  1. Add a new profile to {{your_repository}}/definitions/custom/ folder in fixtures repository
  2. Push to the repository and wait several minutes until the profile is cached
  3. Check that everything works fine by calling an $validate operation on your Resource Type, referencing the profile in meta: {{host}}/fhir/{{resource_type}}/$validate