Sept 3, 2025: DocumentReference Improvements

We’ve updated how DocumentReference (DocRef) resources are generated to improve navigation between related DocRefs and encounters, and to ensure key fields are populated more consistently with meaningful clinical values.

Parent and Child Distinction

Parent DocRefs represent the full document and typically include LOINC codes but little clinical detail. Child DocRefs represent sections within a document and usually contain unstructured clinical details (notes, referral reasons, etc).
Parent DocRefs now include a "clinical-document" meta.extension. Child DocRefs now include a "clinical-document-section" meta.extension and reference their parent in the context.related array.

Encounter Linking

Encompassing encounters provide high-level context but often lack detailed clinical data. Encounters listed in the encounter section usually contain the most relevant medical information.
If a document has only one encounter in its encounter section, the encounter.reference now points directly to that section. If multiple encounters are present, the DocRef continues to point to the encompassing encounter.

Context Period Population

The context.period represents the time of service being documented. This is typically derived from the effectiveDateTime in the relevant document section, but this field is occasionally empty.
If effectiveDateTime is missing, the period is now derived from the period on the related encounter.

These updates apply to newly ingested documents. Older documents will be updated as they are reprocessed the next time they come through our system.
Parent/child information is currently only available in the data mart by parsing the resource_json column, but will be surfaced in a dedicated column in the future.

Example: Updated DocumentReference

Here is a simplified example of a DocumentReference showing the new fields and logic (with comments on changed areas):

{
  "resourceType": "DocumentReference",
  "id": "DocRef-ID",
  "meta": {
    "extension": [
      {
        "url": "https://zusapi.com/data-acquisition/extension/document-reference-type",
        "valueString": "clinical-document-section"
        /* NEW: Marks this as a child DocRef */
      },
      {
        "url": "https://zusapi.com/stream",
        "valueString": "third-party"
      },
      {
        "url": "https://zusapi.com/created-at",
        "valueInstant": "2025-08-23T19:20:18.362+00:00"
      }
    ],
    "versionId": "1",
    "lastUpdated": "2025-08-23T19:20:18.362+00:00",
    "tag": [
      {
        "system": "https://zusapi.com/thirdparty/source",
        "code": "carequality"
      },
      {
        "system": "https://zusapi.com/accesscontrol/owner",
        "code": "builder/Builder-ID"
      }
    ]
  },
  "status": "current",
  "type": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "11506-3",
        "display": "Progress note"
      }
    ]
  },
  "subject": {
    "reference": "Patient/example"
  },
  "date": "2025-08-12T00:00:00Z",
  "custodian": {
    "reference": "Organization/Organization-ID"
  },
  "description": "Document description",
  "content": [
    {
      "attachment": {
        "contentType": "application/xml",
        "url": "Binary/Binary-ID",
        "creation": "2025-08-12"
      }
    }
  ],
  "context": {
    "period": {
      "start": "2025-08-02",
      /* NEW: Pulls from the encounter when the effectiveDateTime is missing */
      "end": "2025-08-07"
    },
    "related": [
      {
        "reference": "DocumentReference/parent-doc-id",
        "type": "DocumentReference"
        /* NEW: links child to parent DocRef */
      }
    ],
    "encounter": [
      {
        "reference": "Encounter/single-encounter-id",
        "type": "Encounter"
        /* NEW: links to the more specific encounter section instead of the encompassing encounter */
      }
    ]
  }
}