openapi: 3.1.0
info:
  title: HL7 FHIR R4 Healthcare Bundle Patient 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: Patient
  description: Patient demographic and identity resources
paths:
  /Patient:
    get:
      operationId: searchPatient
      summary: Search patients
      description: Searches for Patient resources matching the specified search parameters. Supports name, identifier (MRN), birthdate, gender, and address searches. Returns a Bundle containing matching Patient resources.
      tags:
      - Patient
      parameters:
      - name: _id
        in: query
        schema:
          type: string
        description: Logical id of the patient
      - name: identifier
        in: query
        schema:
          type: string
        description: Patient identifier (e.g., "http://hospital.example.org/patients|12345")
      - name: family
        in: query
        schema:
          type: string
        description: A portion of the family name of the patient
      - name: given
        in: query
        schema:
          type: string
        description: A portion of the given name of the patient
      - name: birthdate
        in: query
        schema:
          type: string
        description: The patient's date of birth (e.g., "1990-01-15" or "ge1990")
      - name: gender
        in: query
        schema:
          type: string
          enum:
          - male
          - female
          - other
          - unknown
      - name: _count
        in: query
        schema:
          type: integer
          default: 20
        description: Number of results per page
      - name: _sort
        in: query
        schema:
          type: string
        description: Sort criteria (e.g., "family,-birthdate")
      - name: _include
        in: query
        schema:
          type: string
        description: Include related resources (e.g., "Patient:general-practitioner")
      responses:
        '200':
          description: Bundle of matching Patient resources
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '400':
          description: Invalid search parameters
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
    post:
      operationId: createPatient
      summary: Create a patient
      description: Creates a new Patient resource. The server assigns the logical ID.
      tags:
      - Patient
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Patient'
      responses:
        '201':
          description: Patient created
          headers:
            Location:
              schema:
                type: string
              description: URL of created resource (e.g., Patient/123/_history/1)
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Patient'
        '400':
          description: Invalid resource
  /Patient/{id}:
    get:
      operationId: readPatient
      summary: Read a patient
      description: Returns the current version of a Patient resource by its logical ID.
      tags:
      - Patient
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Logical ID of the patient
      responses:
        '200':
          description: Patient resource returned
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Patient'
        '404':
          description: Patient not found
    put:
      operationId: updatePatient
      summary: Update a patient
      description: Updates an existing Patient resource using a complete replacement (PUT semantics).
      tags:
      - Patient
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Patient'
      responses:
        '200':
          description: Patient updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Patient'
        '201':
          description: Patient created (upsert)
        '400':
          description: Invalid resource
components:
  schemas:
    CodeableConcept:
      type: object
      properties:
        coding:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
        text:
          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
    Address:
      type: object
      properties:
        use:
          type: string
          enum:
          - home
          - work
          - temp
          - old
          - billing
        type:
          type: string
          enum:
          - postal
          - physical
          - both
        text:
          type: string
        line:
          type: array
          items:
            type: string
        city:
          type: string
        district:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string
    HumanName:
      type: object
      properties:
        use:
          type: string
          enum:
          - usual
          - official
          - temp
          - nickname
          - anonymous
          - old
          - maiden
        text:
          type: string
        family:
          type: string
        given:
          type: array
          items:
            type: string
        prefix:
          type: array
          items:
            type: string
        suffix:
          type: array
          items:
            type: string
    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
    OperationOutcome:
      type: object
      properties:
        resourceType:
          type: string
          enum:
          - OperationOutcome
        issue:
          type: array
          items:
            type: object
            properties:
              severity:
                type: string
                enum:
                - fatal
                - error
                - warning
                - information
              code:
                type: string
              details:
                $ref: '#/components/schemas/CodeableConcept'
              diagnostics:
                type: string
              expression:
                type: array
                items:
                  type: string
      required:
      - resourceType
      - issue
    Patient:
      type: object
      description: Demographics and administrative information about a patient
      properties:
        resourceType:
          type: string
          enum:
          - Patient
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        identifier:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
          description: Patient identifiers (MRN, SSN, etc.)
        active:
          type: boolean
        name:
          type: array
          items:
            $ref: '#/components/schemas/HumanName'
        telecom:
          type: array
          items:
            $ref: '#/components/schemas/ContactPoint'
        gender:
          type: string
          enum:
          - male
          - female
          - other
          - unknown
        birthDate:
          type: string
          format: date
        deceased:
          type: object
          properties:
            deceasedBoolean:
              type: boolean
            deceasedDateTime:
              type: string
              format: date-time
        address:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        communication:
          type: array
          items:
            type: object
            properties:
              language:
                $ref: '#/components/schemas/CodeableConcept'
              preferred:
                type: boolean
        generalPractitioner:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
      required:
      - resourceType
    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'
    ContactPoint:
      type: object
      properties:
        system:
          type: string
          enum:
          - phone
          - fax
          - email
          - pager
          - url
          - sms
          - other
        value:
          type: string
        use:
          type: string
          enum:
          - home
          - work
          - temp
          - old
          - mobile
  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/