fhir.resources 6.1.0

FHIR Comments (JSON)

It is possible to add comments inside json like xml, but need to follow some convention, what is suggested by Grahame Grieve; is implemented here.

Also it is possible to generate json string output without comments.

Examples:

>>> observation_str = b"""{
...  "resourceType": "Observation",
...  "id": "f001",
...    "fhir_comments": [
...      "   a specimen identifier - e.g. assigned when the specimen was taken by the orderer/placer  use the accession number for the filling lab   ",
...      "  Placer ID  "
...    ],
...  "text": {
...      "fhir_comments": [
...      "   a specimen identifier - e.g. assigned when the specimen was taken by the orderer/placer  use the accession number for the filling lab   ",
...      "  Placer ID  "
...    ],
...    "status": "generated",
...    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">.........</div>"
...  },
...  "identifier": [
...    {
...      "use": "official",
...      "system": "http://www.bmc.nl/zorgportal/identifiers/observations",
...      "value": "6323"
...    }
...  ],
...  "status": "final",
...  "_status": {
...      "fhir_comments": [
...            "  EH: Note to balloters  - lots of choices for whole blood I chose this.  "
...          ]
...  },
...  "code": {
...    "coding": [
...      {
...        "system": "http://loinc.org",
...        "code": "15074-8",
...        "display": "Glucose [Moles/volume] in Blood"
...      }
...    ]
...  },
...  "subject": {
...    "reference": "Patient/f001",
...    "display": "P. van de Heuvel"
...  },
...  "effectivePeriod": {
...    "start": "2013-04-02T09:30:10+01:00"
...  },
...  "issued": "2013-04-03T15:30:10+01:00",
...  "performer": [
...    {
...      "reference": "Practitioner/f005",
...      "display": "A. Langeveld"
...    }
...  ],
...  "valueQuantity": {
...    "value": 6.3,
...    "unit": "mmol/l",
...    "system": "http://unitsofmeasure.org",
...    "code": "mmol/L"
...  },
...  "interpretation": [
...    {
...      "coding": [
...        {
...          "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
...          "code": "H",
...          "display": "High"
...        }
...      ]
...    }
...  ],
...  "referenceRange": [
...    {
...      "low": {
...        "value": 3.1,
...        "unit": "mmol/l",
...        "system": "http://unitsofmeasure.org",
...        "code": "mmol/L"
...      },
...      "high": {
...        "value": 6.2,
...        "unit": "mmol/l",
...        "system": "http://unitsofmeasure.org",
...        "code": "mmol/L"
...      }
...    }
...  ]
... }"""
>>> from fhir.resources.observation import Observation
>>> obj = Observation.parse_raw(observation_str)
>>> "fhir_comments" in obj.json()
>>> # Test comments filtering
>>> "fhir_comments" not in obj.json(exclude_comments=True)

Unfortunately comments filtering is not available for FHIRAbstractModel::dict

Special Case: Missing data

In some cases, implementers might find that they do not have appropriate data for an element with minimum cardinality = 1. In this case, the element must be present, but unless the resource or a profile on it has made the actual value of the primitive data type mandatory, it is possible to provide an extension that explains why the primitive value is not present. Example (required intent element is missing but still valid because of extension):

>>> json_str = b"""{
...    "resourceType": "MedicationRequest",
...    "id": "1620518",
...    "meta": {
...        "versionId": "1",
...        "lastUpdated": "2020-10-27T11:04:42.215+00:00",
...        "source": "#z072VeAlQWM94jpc",
...        "tag": [
...            {
...                "system": "http://www.alpha.alp/use-case",
...                "code": "EX20"
...            }
...        ]
...    },
...    "status": "completed",
...    "_intent": {
...        "extension": [
...            {
...                "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
...                "valueCode": "unknown"
...            }
...        ]
...    },
...    "medicationReference": {
...        "reference": "Medication/1620516",
...        "display": "Erythromycin 250 MG Oral Tablet"
...    },
...    "subject": {
...        "reference": "Patient/1620472"
...    },
...    "encounter": {
...        "reference": "Encounter/1620506",
...        "display": "Follow up encounter"
...    },
...    "authoredOn": "2018-06-16",
...    "requester": {
...        "reference": "Practitioner/1620502",
...        "display": "Dr. Harold Hippocrates"
...    },
...    "reasonReference": [
...        {
...            "reference": "Condition/1620514",
...            "display": "Otitis Media"
...        }
...    ],
...    "dosageInstruction": [
...        {
...            "text": "250 mg 4 times per day for 10 days",
...            "timing": {
...                "repeat": {
...                    "boundsDuration": {
...                        "value": 10,
...                        "unit": "day",
...                        "system": "http://unitsofmeasure.org",
...                        "code": "d"
...                    },
...                    "frequency": 4,
...                    "period": 1,
...                    "periodUnit": "d"
...                }
...            },
...            "doseAndRate": [
...                {
...                    "doseQuantity": {
...                        "value": 250,
...                        "unit": "mg",
...                        "system": "http://unitsofmeasure.org",
...                        "code": "mg"
...                    }
...                }
...            ]
...        }
...    ],
...    "priorPrescription": {
...        "reference": "MedicationRequest/1620517",
...        "display": "Amoxicillin prescription"
...    }
... }"""
>>> from fhir.resources.medicationrequest import MedicationRequest
>>> obj = MedicationRequest.parse_raw(json_str)
>>> "intent" not in obj.dict()

Custom Validators

fhir.resources is providing the extensive API to create and attach custom validator into any model. See more about root validator Some convention you have to follow though, while creating a root validator.

1. Number of arguments are fixed, as well as names are also. i.e (cls, values).

2. Should return values, unless any exception need to be raised.

3. Validator should be attached only one time for individual Model. Update [from now, it’s not possible to attach multiple time same name validator on same class]

Example 1: Validator for Patient:

from typing import Dict
from fhir.resources.patient import Patient

import datetime

def validate_birthdate(cls, values: Dict):
    if not values:
        return values
    if "birthDate" not in values:
        raise ValueError("Patient's ``birthDate`` is required.")

    minimum_date = datetime.date(2002, 1, 1)
    if values["birthDate"] > minimum_date:
        raise ValueError("Minimum 18 years patient is allowed to use this system.")
    return values
# we want this validator to execute after data evaluating by individual field validators.
Patient.add_root_validator(validate_gender, pre=False)

Example 2: Validator for Patient from Validator Class:

from typing import Dict
from fhir.resources.patient import Patient

import datetime

class MyValidator:
    @classmethod
    def validate_birthdate(cls, values: Dict):
        if not values:
            return values
        if "birthDate" not in values:
            raise ValueError("Patient's ``birthDate`` is required.")

        minimum_date = datetime.date(2002, 1, 1)
        if values["birthDate"] > minimum_date:
            raise ValueError("Minimum 18 years patient is allowed to use this system.")
        return values
# we want this validator to execute after data evaluating by individual field validators.
Patient.add_root_validator(MyValidator.validate_gender, pre=False)

important notes It is possible add root validator into any base class like DomainResource. In this case you have to make sure root validator is attached before any import of derived class, other than validator will not trigger for successor class (if imported before) by nature.

ENUM Validator

fhir.resources is providing API for enum constraint for each field (where applicable), but it-self doesn’t enforce enum based validation! see discussion here. If you want to enforce enum constraint, you have to create a validator for that.

Example: Gender Enum:

from typing import Dict
from fhir.resources.patient import Patient

def validate_gender(cls, values: Dict):
    if not values:
        return values
    enums = cls.__fields__["gender"].field_info.extra["enum_values"]
    if "gender" in values and values["gender"] not in enums:
        raise ValueError("write your message")
    return values

Patient.add_root_validator(validate_gender, pre=True)

Reference Validator

fhir.resources is also providing enum like list of permitted resource types through field property enum_reference_types. You can get that list by following above (Enum) approaches resource_types = cls.__fields__["managingOrganization"].field_info.extra["enum_reference_types"]

Usages of orjson

orjson is one of the fastest Python library for JSON and is more correct than the standard json library (according to their docs). Good news is that fhir.resource has an extensive support for orjson and it’s too easy to enable it automatically. What you need to do, just make orjson as your project dependency!

pydantic Field Type Support

All available fhir resources (types) can be use as pydantic’s Field’s value types. See issue#46 Support for FastAPI pydantic response models. The module fhirtypes.py contains all fhir resources related types and should trigger validator automatically.

Resource.id aka fhirtypes.Id constraint extensibility

There are a lots of discussion here here i.) https://bit.ly/360HksL ii.) https://bit.ly/3o1fZgl about the length of Resource.Id’s value. Based on those discussions, we recommend that keep your Resource.Id size within 64 letters (for the seek of intercompatibility with third party system), but we are also providing freedom about the length of Id, in respect with others opinion that 64 chr length is not sufficient. fhirtypes.Id.configure_constraints() is offering to customize as your own requirement.

Examples::

>>> from fhir.resources.fhirtypes import Id
>>> Id.configure_constraints(min_length=16, max_length=128)

Note: when you will change that behaviour, that would impact into your whole project.

fhir.resources.fhirelementfactory.FHIRElementFactory::instantiate

Replacement: fhir.resources.construct_fhir_element

• First parameter value is same as previous, the Resource name.

• Second parameter is more flexible than previous! it is possible to provide not only json dict but also json string or json file path.

• No third parameter, what was in previous version.

fhir.resources.fhirabstractbase.FHIRAbstractBase::__init__

Replacement: fhir.resources.fhirabstractmodel.FHIRAbstractModel::parse_obj<classmethod>

• First parameter value is same as previous, json dict.

• No second parameter, what was in previous version.

fhir.resources.fhirabstractbase.FHIRAbstractBase::as_json

Replacement: fhir.resources.fhirabstractmodel.FHIRAbstractModel::dict

• Output are almost same previous, but there has some difference in case of some date type, for example py date, datetime, Decimal are in object representation.

• It is possible to use fhir.resources.fhirabstractmodel.FHIRAbstractModel::json as replacement, when json string is required (so not need further, json dumps from dict)

Note:

All resources/classes are derived from fhir.resources.fhirabstractmodel.FHIRAbstractModel what was previously from fhir.resources.fhirabstractbase.FHIRAbstractBase.