openapi: 3.1.0
info:
  title: HL7 FHIR R4 Healthcare Bundle Observation API
  description: HL7 FHIR R4 (v4.0.1) RESTful API for healthcare data exchange. Provides access to patient demographics, clinical observations, conditions, medications, encounters, care plans, and diagnostic reports. Implements the FHIR REST specification including CRUD operations, search parameters, history, and batch/ transaction bundles. SMART on FHIR OAuth 2.0 authorization required.
  version: 4.0.1
  contact:
    name: HL7 International
    url: https://www.hl7.org/fhir/
  license:
    name: Creative Commons CC0
    url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://fhir-server.example.com/fhir/R4
  description: FHIR R4 server base URL (replace with actual server URL)
security:
- SMARTonFHIR: []
tags:
- name: Observation
  description: Clinical measurements, lab results, vital signs
paths:
  /Observation:
    get:
      operationId: searchObservation
      summary: Search observations
      description: Searches for Observation resources (lab results, vital signs, surveys). Common use cases include retrieving recent vital signs or lab values for a patient.
      tags:
      - Observation
      parameters:
      - name: patient
        in: query
        schema:
          type: string
        description: Patient reference (e.g., "Patient/123")
      - name: category
        in: query
        schema:
          type: string
        description: Observation category (vital-signs, laboratory, social-history, etc.)
      - name: code
        in: query
        schema:
          type: string
        description: LOINC code or system|code (e.g., "8302-2" for body height)
      - name: date
        in: query
        schema:
          type: string
        description: Observation date filter (e.g., "ge2024-01-01")
      - name: status
        in: query
        schema:
          type: string
          enum:
          - registered
          - preliminary
          - final
          - amended
          - corrected
          - cancelled
      - name: _count
        in: query
        schema:
          type: integer
          default: 20
      - name: _sort
        in: query
        schema:
          type: string
          default: -date
      responses:
        '200':
          description: Bundle of matching Observation resources
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
  /Observation/{id}:
    get:
      operationId: readObservation
      summary: Read an observation
      description: Returns a specific Observation resource by its logical ID.
      tags:
      - Observation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Observation resource returned
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Observation'
        '404':
          description: Observation not found
components:
  schemas:
    CodeableConcept:
      type: object
      properties:
        coding:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
        text:
          type: string
    Quantity:
      type: object
      properties:
        value:
          type: number
        comparator:
          type: string
          enum:
          - <
          - <=
          - '>='
          - '>'
        unit:
          type: string
        system:
          type: string
          format: uri
        code:
          type: string
    Bundle:
      type: object
      description: A container for a collection of FHIR resources
      properties:
        resourceType:
          type: string
          enum:
          - Bundle
        id:
          type: string
        type:
          type: string
          enum:
          - document
          - message
          - transaction
          - transaction-response
          - batch
          - batch-response
          - history
          - searchset
          - collection
        total:
          type: integer
          description: Total number of matches (for searchset bundles)
        link:
          type: array
          items:
            type: object
            properties:
              relation:
                type: string
                enum:
                - self
                - first
                - previous
                - next
                - last
              url:
                type: string
                format: uri
        entry:
          type: array
          items:
            type: object
            properties:
              fullUrl:
                type: string
                format: uri
              resource:
                type: object
                description: FHIR resource (any type)
              search:
                type: object
                properties:
                  mode:
                    type: string
                    enum:
                    - match
                    - include
                    - outcome
                  score:
                    type: number
              request:
                type: object
                properties:
                  method:
                    type: string
                    enum:
                    - GET
                    - HEAD
                    - POST
                    - PUT
                    - DELETE
                    - PATCH
                  url:
                    type: string
              response:
                type: object
                properties:
                  status:
                    type: string
                  location:
                    type: string
      required:
      - resourceType
      - type
    Reference:
      type: object
      properties:
        reference:
          type: string
          description: Relative or absolute URL (e.g., "Patient/123")
        type:
          type: string
          format: uri
        identifier:
          $ref: '#/components/schemas/Identifier'
        display:
          type: string
    Identifier:
      type: object
      properties:
        use:
          type: string
          enum:
          - usual
          - official
          - temp
          - secondary
          - old
        type:
          $ref: '#/components/schemas/CodeableConcept'
        system:
          type: string
          format: uri
        value:
          type: string
    Observation:
      type: object
      description: Measurements and simple assertions about a patient or other subject
      properties:
        resourceType:
          type: string
          enum:
          - Observation
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        status:
          type: string
          enum:
          - registered
          - preliminary
          - final
          - amended
          - corrected
          - cancelled
          - entered-in-error
          - unknown
        category:
          type: array
          items:
            $ref: '#/components/schemas/CodeableConcept'
        code:
          $ref: '#/components/schemas/CodeableConcept'
        subject:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        effectiveDateTime:
          type: string
          format: date-time
        issued:
          type: string
          format: date-time
        valueQuantity:
          $ref: '#/components/schemas/Quantity'
        valueCodeableConcept:
          $ref: '#/components/schemas/CodeableConcept'
        valueString:
          type: string
        interpretation:
          type: array
          items:
            $ref: '#/components/schemas/CodeableConcept'
        note:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
        component:
          type: array
          items:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/CodeableConcept'
              valueQuantity:
                $ref: '#/components/schemas/Quantity'
      required:
      - resourceType
      - status
      - code
    Coding:
      type: object
      properties:
        system:
          type: string
          format: uri
          description: Identity of the terminology system (e.g., "http://loinc.org", "http://snomed.info/sct")
        version:
          type: string
        code:
          type: string
        display:
          type: string
        userSelected:
          type: boolean
    Meta:
      type: object
      properties:
        versionId:
          type: string
        lastUpdated:
          type: string
          format: date-time
        profile:
          type: array
          items:
            type: string
            format: uri
        tag:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
  securitySchemes:
    SMARTonFHIR:
      type: oauth2
      description: SMART on FHIR OAuth 2.0 authorization
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            patient/Patient.read: Read patient data
            patient/Observation.read: Read observations
            patient/Condition.read: Read conditions
            patient/MedicationRequest.read: Read medication requests
            patient/Encounter.read: Read encounters
            launch/patient: Patient context launch
            openid: OpenID Connect identity
externalDocs:
  description: HL7 FHIR R4 Specification
  url: https://www.hl7.org/fhir/R4/