Orthovision AI FHIR Implementation Guide
0.2.0 - ci-build
Orthovision AI FHIR Implementation Guide - Local Development build (v0.2.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
The following diagram shows the complete classification workflow:
sequenceDiagram
participant Client
participant API as Orthovision API
participant AI as AI Service
opt Capability Discovery
Client->>API: GET /metadata
API->>Client: CapabilityStatement with supported DICOM tags
Note over Client: Check supported-dicom-tags extension
end
Client->>API: POST /Bundle (OrthovisionAIBundle)
Note over Client,API: Bundle contains: Binary + Task + optional ImagingStudy
alt Bundle validation successful
API->>API: Create resources (Binary, Task, optional ImagingStudy)
API->>API: Set Task status to "in-progress"
API->>Client: 200 OK + Bundle response with created resources
Note over API,AI: Async Processing
API->>AI: Process image from Binary
AI->>AI: DICOM tag classification
AI->>API: Create Observation results
API->>API: Update Task status to completed
Client->>API: GET /Task/{id} (polling)
API->>Client: Task (completed) + Observation refs in output
Client->>API: GET /Observation/{id}
API->>Client: DICOM tag classification results
else Bundle validation failed
API->>Client: 400 Bad Request + OperationOutcome
Note over Client,API: Contains specific error codes and diagnostics
end
Endpoint: GET [base]/metadata
Before submitting classification requests, clients can discover which DICOM tags the implementation supports by checking the CapabilityStatement:
Response: CapabilityStatement with supported-dicom-tags extension
{
"resourceType": "CapabilityStatement",
"id": "orthovision-ai-server",
"extension": [
{
"url": "http://medoco.health/fhir/StructureDefinition/supported-dicom-tags",
"valueString": "modality"
},
{
"url": "http://medoco.health/fhir/StructureDefinition/supported-dicom-tags",
"valueString": "protocol"
},
{
"url": "http://medoco.health/fhir/StructureDefinition/supported-dicom-tags",
"valueString": "body-part"
}
],
// ... rest of capability statement
}
Client Usage: Extract the supported DICOM tag names from the extensions and only request classification for those tags in the Task inputs.
Note: If a client requests classification for an unsupported DICOM tag, the server will return an OperationOutcome with appropriate error details during bundle processing.
Endpoint: POST [base]/Bundle
Input: OrthovisionAIBundle containing Binary, Task, and optional ImagingStudy
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:binary-12345",
"resource": {
"resourceType": "Binary",
"contentType": "image/jpeg",
"data": "base64EncodedImageData..."
},
"request": {
"method": "POST",
"url": "Binary"
}
},
{
"fullUrl": "urn:uuid:study-12345",
"resource": {
"resourceType": "ImagingStudy",
"status": "available",
"subject": {
"reference": "Patient/patient-12345"
}
},
"request": {
"method": "POST",
"url": "ImagingStudy"
}
},
{
"fullUrl": "urn:uuid:task-12345",
"resource": {
"resourceType": "Task",
"status": "requested",
"intent": "order",
"code": {
"coding": [{
"system": "http://hl7.org/fhir/CodeSystem/task-code",
"code": "fulfill"
}]
},
"focus": {
"reference": "urn:uuid:binary-12345"
},
"input": [
{
"type": {
"coding": [{
"system": "http://hl7.org/fhir/task-input-type",
"code": "imagingStudy"
}]
},
"valueReference": {
"reference": "urn:uuid:study-12345"
}
},
{
"type": {
"coding": [{
"system": "http://hl7.org/fhir/task-input-type",
"code": "tagDICOM"
}]
},
"valueString": "modality"
},
{
"type": {
"coding": [{
"system": "http://hl7.org/fhir/task-input-type",
"code": "tagDICOM"
}]
},
"valueString": "protocol"
}
],
"authoredOn": "2025-09-25T14:30:00Z"
},
"request": {
"method": "POST",
"url": "Task"
}
}
]
}
Response: HTTP 200 OK with Bundle response containing created resources and their assigned IDs. The Task status is automatically changed to "in-progress".
Note: The imagingStudy is optional and provides additional context to optimize AI processing.
Simple - Polling: GET [base]/Task/{id}
Suggestion: Use exponential backoff for polling intervals.
When the Task status becomes completed, results are available via the Task output references:
Final Results: OrthovisionAIObservation resources containing DICOM tag classifications
Example Modality Classification: GET [base]/Observation/modality-obs-12345
{
"resourceType": "Observation",
"id": "modality-obs-12345",
"status": "final",
"category": [{
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/observation-category",
"code": "imaging"
}]
}],
"code": {
"coding": [{
"system": "http://medoco.health/fhir/CodeSystem/dicom-tags",
"code": "modality"
}]
},
"valueCodeableConcept": {
"coding": [{
"code": "XC",
"display": "External Photography"
}]
},
"extension": [{
"url": "http://medoco.health/fhir/StructureDefinition/confidence-score",
"valueDecimal": 0.97
}]
}
Example Protocol Classification: GET [base]/Observation/protocol-obs-12345
{
"resourceType": "Observation",
"id": "protocol-obs-12345",
"status": "final",
"category": [{
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/observation-category",
"code": "imaging"
}]
}],
"code": {
"coding": [{
"system": "http://medoco.health/fhir/CodeSystem/dicom-tags",
"code": "protocol"
}]
},
"valueString": "Frontal Facial view",
"extension": [{
"url": "http://medoco.health/fhir/StructureDefinition/confidence-score",
"valueDecimal": 0.89
}]
}
The Bundle-based approach provides several advantages over individual resource creation:
All OrthovisionAIObservation resources include confidence scores via the confidence-score extension, providing transparency into AI model certainty:
{
"resourceType": "Observation",
"valueCodeableConcept": {
"coding": [{"code": "XC", "display": "External Photography"}]
},
"extension": [{
"url": "http://medoco.health/fhir/StructureDefinition/confidence-score",
"valueDecimal": 0.97
}]
}
Failed requests return OperationOutcome with specific error codes:
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "invalid",
"details": {
"coding": [{
"system": "http://medoco.health/fhir/CodeSystem/orthovision-ai-error-codes",
"code": "unsupported-image-format"
}]
},
"diagnostics": "Only JPEG, PNG, JP2, and DICOM images are supported. Received: image/bmp"
}]
}
The Bundle can include an optional ImagingStudy resource to provide additional DICOM metadata context for more accurate classification. When included in the bundle, the Task references it using temporary UUIDs:
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:binary-12345",
"resource": { "resourceType": "Binary", "..." }
},
{
"fullUrl": "urn:uuid:study-12345",
"resource": { "resourceType": "ImagingStudy", "..." }
},
{
"fullUrl": "urn:uuid:task-12345",
"resource": {
"resourceType": "Task",
"focus": { "reference": "urn:uuid:binary-12345" },
"input": [
{
"type": {
"coding": [{
"system": "http://hl7.org/fhir/task-input-type",
"code": "imagingStudy"
}]
},
"valueReference": { "reference": "urn:uuid:study-12345" }
}
]
}
}
]
}
This approach allows the AI service to use both the raw image data (from the Binary) and structured DICOM metadata (from the ImagingStudy) for improved classification accuracy while maintaining referential integrity within the bundle.
Once a Task reaches a final state (completed, failed, or cancelled), the associated Binary and ImagingStudy resources used for processing can be safely deleted.
Recommended Cleanup Timeline:
410 Gone when accessedExample Cleanup Policy:
{
"resourceType": "Task",
"id": "task-12345",
"status": "completed",
"focus": {
"reference": "Binary/binary-12345"
},
"output": [
{
"type": {
"coding": [{
"system": "http://hl7.org/fhir/task-output-type",
"code": "observation"
}]
},
"valueReference": {
"reference": "Observation/modality-obs-12345"
}
}
]
}
Implementation Considerations: