Skip to main content

Binary

Overview​

The Binary resource provides information "that represents the data of a single raw artifact as digital content accessible in its native format".

In the bulk data export context, Binary resources represent exported data files and error files generated during the export process. These files are stored securely and accessed through the Binary resource operations.

Key Use Cases:

  • Download exported FHIR data files
  • Access export error logs
  • Retrieve attachment files referenced in exported resources
  • Support secure file transfer for bulk data

Important Notes:

  • Binary resources are only accessible for files included in authorized exports
  • Files may have expiration times for security purposes
  • Access requires the same authorization used for the export request

Resource Schema​

Key fields in Binary resources:

{
  "resourceType": "Binary",
  "id": "export-file-123",
  "contentType": "application/fhir+ndjson",
  "securityContext": {
    "reference": "Group/example-group"
  },
  "data": "<base64-encoded-content>"
}

Operations​

Note: Always verify supported operations by checking the CapabilityStatement before implementation.

Read​

Retrieves Binary resource metadata (not the actual file content).

Endpoint: GET /Binary/{id}

Examples​

Read Binary Metadata
curl -X GET https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Binary/export-file-123 \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json"

Response Example​

Binary Resource Response
{
  "resourceType": "Binary",
  "id": "export-file-123",
  "meta": {
    "lastUpdated": "2024-01-15T10:30:00Z"
  },
  "contentType": "application/fhir+ndjson",
  "securityContext": {
    "reference": "Group/example-group"
  }
}

Binary Access Read Operation ($binary-access-read)​

Downloads the actual file content without FHIR Binary metadata wrapper.

Endpoint: GET /Binary/{id}/$binary-access-read

Examples​

Download Export File
curl -X GET https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Binary/export-file-123/\$binary-access-read \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+ndjson" \
    -o exported-data.ndjson
Download Error File
curl -X GET https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Binary/error-file-456/\$binary-access-read \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+ndjson" \
    -o export-errors.ndjson

Response​

File Download Response
HTTP/2 200 OK
Content-Type: application/fhir+ndjson
Content-Length: 1048576
Content-Disposition: attachment; filename="Patient.ndjson"

{"resourceType":"Patient","id":"123",...}
{"resourceType":"Patient","id":"456",...}
{"resourceType":"Patient","id":"789",...}

Integration Patterns​

File Download Workflow​

# Step 1: Get export status with file manifest
GET /$export-poll-status/{job-id}

# Step 2: Extract file URLs from manifest
# Parse output.url values

# Step 3: Download each file
GET /Binary/{file-id}/$binary-access-read

# Step 4: Process downloaded data
# Parse NDJSON files line by line

File Types​

Data Files:

  • Content-Type: application/fhir+ndjson
  • Contains exported FHIR resources
  • One resource per line in NDJSON format

Error Files:

  • Content-Type: application/fhir+ndjson
  • Contains OperationOutcome resources for export errors
  • Helps troubleshoot export issues

Attachment Files:

  • Various content types (PDF, images, etc.)
  • Referenced by DocumentReference or other resources
  • Preserved from original format

Supported Profiles​

Note: Supported profiles are extracted from the CapabilityStatement. Always verify current profiles by checking the supportedProfile arrays.

Error Handling​

For common error scenarios and troubleshooting guidance, see Common Errors.

Relationships to Other Resources​

  • Group: Binary files are generated from Group export operations
  • Export Status: Binary file URLs are provided in export status responses
  • DocumentReference: May reference Binary resources for attachments