hip.yaml

openapi: 3.0.0
info:
  version: "0.5"
  title: Health Repository Provider / Bridge Specifications (HIP)
  description: >
    The following are the specifications for the APIs to be implemented at the Health Repository end if an entity is only serving the role of a HIP. The specs are essentially duplicates from the Gateway and Health Repository, but put together so as to make it clear to *HIPs* which set of APIs they should implement to participate in the network. 
    
      1. The APIs are organized by the flows - **discovery**, **link**, **consent flow**, **data flow**, **user auth** and **monitoring**. They represent the APIs that are expected to be available at the HIP end by the Gateway. 
      2. For majority of the APIs, there are corresponding callback APIs on the Gateway. e.g for **/care-context/discover** API on HIP end, its expected that a corresponding callback API **/care-context/on-discover** on Gateway is called. Such APIs are organized under the **Gateway** label. 
      3. Gateway relevant APIs for HIPs are grouped under **Gateway** label. These include the APIs that HIPs may require to call on the Gateway. For example, to notify a CM that requested data is transferred, HIP would call **/health-information/notify** API on gateway. Or for example, to get a session or to do a hip-initiated purpose for linking care-contexts. 
      4. APIs under **data transfer** are meant to be implemented by the HIU. However, these have been marked here to give indication to the HIPs about the data contract. 
    
      
servers:
  - url: https://ncg-dev.projecteka.in/api-bridge1
    description: Dev
tags:
  - name: discovery
  - name: link
  - name: consent flow
  - name: data flow
  - name: data transfer
  - name: user auth
  - name: monitoring
  - name: Gateway
paths:
  /v0.5/care-contexts/discover:
    post:
      tags:
        - discovery
      summary: Discover patient's accounts
      description: >
        Request for patient care context discover, made by Gateway intended for a specific HIP. It is expected that HIP will subsequently return either zero or one patient record with (potentially masked) associated care contexts
          1. **At least one of the verified identifier matches**
          2. **Name (fuzzy), gender matches**
          3. **If YoB was given, age band(+-2) matches**
          4. **If unverified identifiers were given, one of them matches**
          5. **If more than one patient records would be found after aforementioned steps, then patient who matches most verified and unverified identifiers would be returned.**
          6. **If there would be still more than one patients (after ranking) error would be returned**
          7. **Intended HIP should be able to resolve and identify results returned in the subsequent link confirmation request via the specified transactionId**
          8. **Intended HIP should store the discovery results with transactionId and care contexts discovered for subsequent link initiation**
          
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientDiscoveryRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientDiscoveryRequest'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * Empty verified identifiers.
              * Format mismatch of any of attributes.
                | type   | Format/Allowed Values|
                | ------- | ----------------    |
                | gender  | M/F/O/U |
                | MOBILE  | valid mobile number with proper country code |
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/links/link/init:
    post:
      tags:
        - link
      summary: Link patient's care contexts
      description: >
        Request from Gateway to links care contexts associated with only one patient
          1. **Validate account reference number and care context reference number**
          2. **Validate transactionId in the request with discovery request entry to check whether there was a discovery
              and were these care contexts discovered or not for a given patient**
          3. **Before eventual link confirmation, HIP needs to authenticate the request with the patient(eg: OTP verification)**
          4. **HIP should communicate the mode of authentication of a successful request to Consent Manager**
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientLinkReferenceRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientLinkReferenceRequest'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * Consent manager user id is not provided
              * Patient reference number is not provided
              * Care context references are not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/links/link/confirm:
    post:
      tags:
        - link
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
      summary: Token submission by Consent Manager for link confirmation
      description: >
        API to submit the token that was sent by HIP during the link request. 
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkConfirmationRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/LinkConfirmationRequest'
      responses:
        '202':
          description: accepted
        '400':
          description: >
            **Causes:**
              * Token is not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/health-information/hip/request:
    post:
      tags:
        - data flow
      summary: Health information data request
      description: >
        API called by CM to request Health information from HIP against a validated consent artefact. The transactionId is the correlation id that HIP should use use when pushing data to the **dataPushUrl**. 
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/X-HIP-ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIPHealthInformationRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/HIPHealthInformationRequest'
      responses:
        '202':
          description: Request accepted.
        '400':
          description: >
            **Causes:**
              * Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Token is invalid or Link has expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/health-information/transfer:
    post:
      tags:
        - data transfer
      summary: health information transfer API
      description: >
        **NOTE**: This API is actually the callback URL that is passed as **dataPushUrl** in the data request API - /v0.5/health-information/hip/request. This API is directly called by HIP Data Bridge and is not mediated via CM, and hence not routed through the Gateway. 
          1. This API should be implemented at HIU side. It maybe implemented by the Data Bridge representing the HIU. 
          2. Entry elements maybe ***content*** or ***link***, although for version 1, entry ***content*** is preferred. 
          3. Entry ***content*** (or even link reference content) must be encrypted by means of Diffie Hellman Key Exchange, utilizing the HIU keymaterials that are passed through the data request API - /v0.5/health-information/hip/request. 
          4. Media contains the mimetype of content, and for v1, it is "application/fhir+json"
          5. checksum is Md5 checksum of the data conent, before encryption
          6. Please refer to the ProjectEKA WIKI for the format of FHIR bundle that is passed through content 
      parameters:
        - $ref: '#/components/parameters/authorization'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataNotification'
          application/xml:
            schema:
              $ref: '#/components/schemas/DataNotification'
      responses:
        '202':
          description: Data accepted.
        '401':
          description: >
            **Causes:**
              * Invalid/Expired/Empty token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream services are down
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/consents/hip/notify:
    post:
      tags:
        - consent flow
      summary: Consent notification
      description: |
        Notification of consents to health information providers consent request granted, consent revoked, consent expired. Only the GRANTED and REVOKED status notifications will be sent to HIP.
          1. If consent is granted, status=GRANTED, then consentDetail contains the consent artefact details and signature is available. 
          2. If consent is revoked, then status=REVOKED, and consentId specifes which consent artefact is revoked. 
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIPConsentNotification'
          application/xml:
            schema:
              $ref: '#/components/schemas/HIPConsentNotification'
      responses:
        '202':
          description: Request Accepted
        '401':
          description: >
            **Causes:**
              * Invalid/Expired/Empty token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream services are down
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  
  
  /v0.5/heartbeat:
    get:
      tags:
        - monitoring
      summary: Get consent request status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
  /v0.5/links/link/on-add-contexts:
    post:
      tags:
        - link
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
      summary: callback API for HIP initiated patient linking /link/add-context
      description: >
        If the accessToken is valid for purpose of linking, and specified details provided, CM will send "acknoweldgement.status" as SUCCESS. If any error occcurred, for example invalid token, or other required patient or care-context information not provided, then "error" attribute conveys so. 
          1. **accessToken must be valid and must be for the purpose of linking**
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientCareContextLinkResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientCareContextLinkResponse'
      responses:
        '202':
          description: accepted
        '400':
          description: >
            **Causes:**
              * resp not specified
              * atleast acknowledgement or error should be specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/users/auth/on-fetch-modes:
    post:
      tags:
        - user auth
      summary: Identification result for a consent-manager user-id
      description: |
        If a patient is found then **auth** attribute contains the supported modes for the specified purpose. 
        Otherwise, error is raised for invalid requests or for non-existent id.
        Note in addition to the "Authorization" header, one of the following headers must be specified
        1. specify **X-HIU-ID** if the requester is HIU (identified from /auth/fetch-modes requester.id)
        2. specify **X-HIP-ID** if the requester is HIP (identified from /auth/fetch-modes requester.id)
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthModeQueryResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthModeQueryResponse'
      responses:
        '202':
          description: Request Accepted
        '400':
          description: >
            Invalid request, required attributes not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  
  
  /v0.5/users/auth/on-init:
    post:
      tags:
        - user auth
      summary: Response to user authentication initialization from HIP
      description: >
        If the patient's id is valid, CM will return a transactionId as initialization of user auth. If the request is valid, then 'auth.mode' will convey how the authentication should be done. The authentication can be mediated or direct. For example, if the auth.modeis DIRECT, then HIP/HIU is not expected to send over anything as part of /auth/confirm, rather way for CM to notify them when patient approves so. For other mediated authentication modes, HIP or HIU is epected to send over eiter codes (OTP or similar) or demographic info as part of the /users/auth/confirm request accompanied with the transactionId. Note, for DIRECT authentication, CM will subsequently call /users/auth/notify call (Not spec'd yet)
        
          1. **auth.mode** conveys whats the mode of authentication is, and what is expected from HIP/HIU in the subsequent /auth/confirm API call. Possible values, MOBILE_OTP - for OTP sent to mobile,  AADHAAR_OTP - if an OTP was sent as part of Aadhaar authentication. DEMOGRAPHICS - If it is expected that the HIP/HIU sends over demographi details in the /auth/confirm API call. 
          2. **meta.expiry** conveys the expiry time of the token and the authentication session
          3. **NOTE**, only one of **X-HIP-ID** or **X-HIU-ID** will be sent as part of header, not both. 
          
        The error section in the body, represents the potential errors that may have occurred. Possible reasons:
          1. **Patient id is invalid**
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthInitResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthInitResponse'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * required information not provided
              * neither authInit nor error specified 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'  
  /v0.5/users/auth/on-confirm:
    post:
      tags:
        - user auth
      summary: Request sending token, otp or other authentication details from HIP for confirmation
      description: >
        This API is called by HIPs to confirm authentication of users. The transactionId retuned by the previous /uses/auth/on-init API must be used along with necessary "mode" specific details.
        
          1. **auth.accessToken** - is specific to the purpose mentioned in the /auth/init. This token needs to be used for initiating the intended action. For example for HIP initiated linking of care-contexts
          2. **NOTE**, only one of **X-HIP-ID** or **X-HIU-ID** will be sent as part of header, not both.   
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthConfirmResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthConfirmResponse'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * required details not provided
              * neither auth nor error specified 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'                
  /v0.5/care-contexts/on-discover:
    post:
      tags:
        - Gateway
      summary: Response to patient's account discovery request
      description: >
        Result of patient care-context discovery request at HIP end. If a matching patient found with zero or more care contexts associated, it is specified as result attribute. If the prior discovery request, resulted in errors then it is specified in the error attribute. Reasons of errors can be 
          1. **more than one definitive match for the given request** 
          2. **no verified identifer was specified**
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientDiscoveryResult'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientDiscoveryResult'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * Format mismatch of any of attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/links/link/on-init:
    post:
      tags:
        - Gateway
      summary: Response to patient's care context link request
      description: >
        Result of patient care-context link request from HIP end. This happens in context of previous discovery of patient found at HIP end, therefore the link requests ought to be in reference to the patient reference and care-context references previously returned by the HIP. The correlation of discovery and link request is maintained through the transactionId. HIP should have
          1. **Validated transactionId in the request to check whether there was a discovery done previously, and the link request corresponds to returned patient care care context references**
          2. **Before returning the response, HIP should have sent an authentication request to the patient(eg: OTP verification)**
          3. **HIP should communicate the mode of authentication of a successful request**
          4. **HIP subsequently should expect the token passed via /link/confirm against the link.referenceNumber passed in this call**
          
        The error section in the body, represents the potential errors that may have occurred. Possible reasons:
          1. **Patient reference number is invalid**
          2. **Care context reference numbers are invalid**
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientLinkReferenceResult'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientLinkReferenceResult'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * Format mismatch of any of attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/links/link/on-confirm:
    post:
      tags:
        - Gateway
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      summary: Token authenticated by HIP, indicating completion of linkage of care-contexts
      description: >
        Returns a list of linked care contexts with patient reference number.
          1. **Validated and linked account reference number**
          2. **Validated that the token sent from Consent Manager is same as the one generated by HIP**
          3. **Verified that same Consent Manager which made the link request is sending the token**
          4. **Results of unmasked linked care contexts with patient reference number**
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientLinkResult'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientLinkResult'
      responses:
        '202':
          description: accepted
        '400':
          description: >
            **Causes:**
              * resp not specified
              * atleast patient or error should be specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/consents/hip/on-notify:
    post:
      tags:
        - Gateway
      summary: Consent notification
      description: >
        This API is called by HIP as acknowledgement to notification of consents, in cases of consent revocation and expiration. 
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIPConsentNotificationResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/HIPConsentNotificationResponse'
      responses:
        '202':
          description: Request Accepted
        '401':
          description: >
            **Causes:**
              * Invalid/Expired/Empty token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream services are down
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/health-information/hip/on-request:
    post:
      tags:
        - Gateway
      summary: Health information data request
      description: >
        API called by HIP to acknowledge Health information request receipt. Either the **hiRequest** or **error** must be specified. **hiRequest** element returns the same transactionId as before with a status indicating that the request is acknowledged.  
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/X-CM-ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIPHealthInformationRequestAcknowledgement'
          application/xml:
            schema:
              $ref: '#/components/schemas/HIPHealthInformationRequestAcknowledgement'
      responses:
        '202':
          description: Request accepted.
        '400':
          description: >
            **Causes:**
              * Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Token is invalid or Link has expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  
  
  /v0.5/users/auth/fetch-modes:
    post:
      tags:
        - Gateway
      summary: Get a patient's authentication modes by her consent-manager user-id relevant to specified purpose
      description: >
        This API is meant for identify supported authentication modes for a patient given a specific purpose. The supported purposes are KYC, LINK, KYC_AND_LINK
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthModeQueryRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthModeQueryRequest'
      responses:
        '202':
          description: Request Accepted
        '400':
          description: >
            Invalid request, required attributes not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                
                
  /v0.5/users/auth/init:
    post:
      tags:
        - Gateway
      summary: Initialize authentication from HIP
      description: >
        This API is called by HIPs to initiate authentication of users. A transactionId is retuned by the corresponding callback API for confirmation of user auth.
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthInitRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthInitRequest'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * patient id is not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'  
  /v0.5/users/auth/confirm:
    post:
      tags:
        - Gateway
      summary: Confirmation request sending token, otp or other authentication details from HIP for confirmation
      description: >
        This API is called by HIP/HIUs to confirm authentication of users. The transactionId returned by the previous callback API /users/auth/on-init must be sent. If Authentication is successful the callback API will send an "access token" for subsequent purpose specific API calls. Note only **credential.authCode** or **credential.demographic** should be sent
          1. demographic details are only required for  demographic auth as of now. 
          2. demographic details are required only in MEDIATED cases and if the **auth.mode** so demands. e.g. if **auth.mode** is DEMOGRAPHICS. Usually for demographic authentication, the name, gender and DOB must be exactly as specified in User Account.
          3. demographic.identifier is optional, however maybe required if authentication so mandates. 
          4. credential.authCode is required for other MEDIATED authentication like MOBILE_OTP, AADHAAR_OTP. 
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthConfirmRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthConfirmRequest'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * tranasction id is not provided or invalid
              * token or other auth confirmation details not provided or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'  
  /v0.5/links/link/add-contexts:
    post:
      tags:
        - Gateway
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      summary: API for HIP initiated care-context linking for patient
      description: >
        API to submit care-context to CM for HIP initiated linking. The API must accompany the "accessToken" fetched in the users/auth process.  
          1. subsequent usage for accessToken may be invalid if it was meant for one-time usage or if it expired
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientCareContextLinkRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientCareContextLinkRequest'
      responses:
        '202':
          description: accepted
        '400':
          description: >
            **Causes:**
              * required information not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/health-information/notify:
    post:
      tags:
        - Gateway
      summary: Notifications corresponding to events during data flow
      description: |
        API called by HIU and HIP during data-transfer. 
        1. HIP on transfer of data would send **sessionStatus** - one of [TRANSFERRED, FAILED]
        2. HIP would also send **hiStatus** for each *careContextReference* - on of [DELIVERED, ERRORED]
        3. HIU on receipt of data would send **sessionStatus** - one of [TRANSFERRED, FAILED]. For example, FAILED when if data was not sent or if invalid data was sent
        4. HIU would also send **hiStatus** for each *careContextReference* - one of [OK, ERRORED] 
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/X-CM-ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HealthInformationNotification'
          application/xml:
            schema:
              $ref: '#/components/schemas/HealthInformationNotification'
      responses:
        '204':
          description: Notification is Accepted
        '400':
          description: >
            **Causes:**
              * Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Expired/Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/sessions:
    post:
      tags:
        - Gateway
      summary: Get access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/SessionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '404':
          description: >
            **Causes:**
              * Invalid consent request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Invalid client Id or secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/.well-known/openid-configuration:
    get:
      tags:
        - Gateway
      summary: Get openid configuration
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIdConfiguration'
            application/xml:
              schema:
                $ref: '#/components/schemas/OpenIdConfiguration'
        '404':
          description: >
            **Causes:**
              * Invalid consent request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/certs:
    get:
      tags:
        - Gateway
      summary: Get certs for JWT verification
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certs'
            application/xml:
              schema:
                $ref: '#/components/schemas/Certs'
        '404':
          description: >
            **Causes:**
              * Invalid consent request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  
  

components:
  parameters:
    authorization:
      name: Authorization
      in: header
      required: true
      description: Access token which was issued after successful login with gateway auth server, which will be sent by gateway to authenticate itself with API bridge.
      schema:
        type: string
    X-Origin-ID:
      name: X-Origin-ID
      in: header
      description: >
       Identifier of the health information provider user from which the request came.
       (Necessity of this header depends on the authentication at the Bridge)
       If gateway uses JWT authentication, from access token itself originator can be identified.
      schema:
        type: string
    X-HIP-ID:
      name: X-HIP-ID
      in: header
      required: true
      description: Identifier of the health information provider to which the request was intended.
      schema:
        type: string
    X-HIU-ID:
      name: X-HIU-ID
      in: header
      required: true
      description: Identifier of the health information user to which the request was intended.
      schema:
        type: string
    X-CM-ID:
      name: X-CM-ID
      in: header
      required: true
      description: Suffix of the consent manager to which the request was intended.
      schema:
        type: string
    LinkRefNumber:
      name: linkRefNumber
      in: path
      required: true
      description: Reference number for the link request made earlier.
      schema:
        $ref: '#/components/schemas/UuidSchema'
    ConsentRequestId:
      name: consentRequestId
      in: path
      required: true
      description: Consent request's identifier
      schema:
        type: string
        format: uuid
    ConsentId:
      name: consentId
      in: path
      required: true
      description: Consent request's identifier
      schema:
        type: string
        format: uuid
  schemas:
    UuidSchema:
      type: string
      format: uuid
      example: a1s2c932-2f70-3ds3-a3b5-2sfd46b12a18d
    PatientDiscoveryRequest:
      type: object
      required:
        - requestId
        - timestamp
        - transactionId
        - patient
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request. 
          example: "499a5a4a-7dda-4f20-9b67-e24589627061"
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        transactionId:
          type: string
          format: uuid
          description: correlation-Id for patient discovery and subsequent care context linkage
        patient:
          type: object
          required:
            - id
            - verifiedIdentifiers
            - name
            - gender
            - yearOfBirth
          properties:
            id:
              type: string
              example: <patient-id>@<consent-manager-id>
              description: Identifier of patient at consent manager
            verifiedIdentifiers:
              type: array
              items:
                $ref: '#/components/schemas/Identifier'
              xml:
                name: verifiedIdentifiers
                wrapped: true
            unverifiedIdentifiers:
              type: array
              items:
                $ref: '#/components/schemas/Identifier'
              xml:
                name: unverifiedIdentifiers
                wrapped: true
            name:
              type: string
              example: "chandler bing"
            gender:
              $ref: '#/components/schemas/PatientGender'
            yearOfBirth:
              type: integer
              example: 2000
      xml:
        name: PatientDiscoveryRequest
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Identifier:
      type: object
      required:
        - type
        - value
      properties:
        type:
          $ref: '#/components/schemas/IdentifierType'
        value:
          type: string
          example: "+919800083232"
      xml:
        name: Identifier
    IdentifierType:
      type: string
      enum: [MOBILE, MR]
    PatientRepresentation:
      type: object
      required:
        - referenceNumber
        - display
        - careContexts
      properties:
        referenceNumber:
          type: string
        display:
          type: string
        careContexts:
          type: array
          items:
            $ref: '#/components/schemas/CareContextRepresentation'
        matchedBy:
          type: array
          items:
            $ref: '#/components/schemas/IdentifierType'
      xml:
        name: Patient
    CareContext:
      type: object
      required:
        - referenceNumber
      properties:
        referenceNumber:
          type: string
      xml:
        name: Tag
    CareContextRepresentation:
      type: object
      required:
        - referenceNumber
        - display
      properties:
        referenceNumber:
          type: string
        display:
          type: string
      xml:
        name: Tag
    PatientLinkReferenceRequest:
      type: object
      required:
        - requestId
        - timestamp
        - patient
        - transactionId
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        transactionId:
          type: string
          format: uuid
        patient:
          type: object
          required:
            - id
            - referenceNumber
            - careContexts
          properties:
            id:
              type: string
              example: hinapatel79@ncg
            referenceNumber:
              type: string
              example: TMH-PUID-001
            careContexts:
              type: array
              items:
                $ref: '#/components/schemas/CareContext'
              xml:
                name: careContexts
                wrapped: true
          xml:
            name: PatientLinkReferenceRequest
    LinkConfirmationRequest:
      type: object
      required:
        - requestId
        - timestamp
        - confirmation
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        confirmation:
          type: object
          required:
            - linkRefNumber
            - token
          properties:
            linkRefNumber:
              type: string
            token:
              type: string
    Meta:
      type: object
      required:
        - communicationMedium
      properties:
        communicationMedium:
          type: string
          enum: ['M0BILE', 'EMAIL']
        communicationHint:
          type: string
        communicationExpiry:
          type: string
          example: "2019-12-30T12:01:55Z"
      xml:
        name: Meta
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          enum: [1000, 10001]
        message:
          type: string
      xml:
        name: Error
    consent:
      type: object
      required:
        - id
      properties:
        id:
          type: string
    DateRange:
      type: object
      required:
        - from
        - to
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
    HIPConsentNotification:
      type: object
      required:
        - requestId
        - timestamp
        - notification
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        notification:
          type: object
          required:
            - status
            - consentId
            - consentDetail
            - signature
          properties:
            status:
              $ref: '#/components/schemas/ConsentStatus'
            consentId:
              type: string
              format: uuid
            consentDetail:
              type: object
              required:
                - consentId
                - createdAt
                - patient
                - careContexts
                - purpose
                - hiTypes
                - hip
                - consentManager
                - permission
              properties:
                schemaVersion:
                  type: string
                  format: string
                consentId:
                  type: string
                  format: uuid
                createdAt:
                  type: string
                  format: date-time
                patient:
                  $ref: '#/components/schemas/ConsentManagerPatientID'
                careContexts:
                  type: array
                  items:
                    type: object
                    required:
                      - patientReference
                      - careContextReference
                    properties:
                      patientReference:
                        type: string
                        example: batman@tmh
                      careContextReference:
                        type: string
                        example: Episode1
                purpose:
                  $ref: '#/components/schemas/UsePurpose'
                hip:
                  type: object
                  allOf:
                    - $ref: '#/components/schemas/OrganizationRepresentation'
                    - xml:
                        name: hip
                consentManager:
                  type: object
                  allOf:
                    - $ref: '#/components/schemas/OrganizationReference'
                    - xml:
                        name: consentManager
                hiTypes:
                  type: array
                  items:
                    $ref: '#/components/schemas/HITypeEnum'
                permission:
                  $ref: '#/components/schemas/Permission'
            signature:
              type: string
              example: Signature of CM as defined in W3C standards; Base64 encoded
    HITypeEnum:
      type: string
      enum:
        - OPConsultation
        - Prescription
        - DischargeSummary
        - DiagnosticReport
      xml:
        name: HIType
    ConsentStatus:
      type: string
      enum:
        - GRANTED
        - EXPIRED
        - DENIED
        - REQUESTED
        - REVOKED
    ConsentManagerPatientID:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          xml:
            attribute: true
          format: <user-id>@<ncg-id>
          example: batman@ncg
    UsePurpose:
      type: object
      required:
        - text
        - code
      properties:
        text:
          type: string
        code:
          type: string
          description: From the fixed set, documented at refUri
        refUri:
          type: string
          format: uri
    Permission:
      type: object
      required:
        - accessMode
        - dateRange
        - dataEraseAt
        - frequency
      properties:
        accessMode:
          type: string
          enum: [VIEW, STORE, QUERY, STREAM]
        dateRange:
          type: object
          required:
            - from
            - to
          properties:
            from:
              type: string
              format: date-time
            to:
              type: string
              format: date-time
        dataEraseAt:
          type: string
          format: date-time
        frequency:
          type: object
          properties:
            unit:
              type: string
              enum: [HOUR, WEEK, DAY, MONTH, YEAR]
            value:
              type: integer
            repeats:
              type: integer
      xml:
        name: Permission
    OrganizationRepresentation:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          xml:
            attribute: true
      xml:
        name: OrganizationResponse
    OrganizationReference:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          xml:
            attribute: true
      xml:
        name: OrganizationReference
    KeyMaterial:
      type: object
      required:
        - cryptoAlg
        - curve
        - dhPublicKey
        - nonce
      properties:
        cryptoAlg:
          type: string
          format: string
          example: ECDH
        curve:
          type: string
          format: string
          example: Curve25519
        dhPublicKey:
          $ref: '#/components/schemas/keyObject'
        nonce:
          type: string
          format: 32 byte string
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    keyObject:
      type: object
      required:
        - expiry
        - parameters
        - keyValue
      properties:
        expiry:
          type: string
          format: date-time
        parameters:
          type: string
          format: string
          example: Curve25519/32byte random key
        keyValue:
          type: string
          format: string
    TimestampSchema:
      type: string
      format: date-time
      description: Date time format in UTC, includes miliseconds YYYY-MM-DDThh:mm:ss.vZ
    RequestReference:
      type: object
      required:
        - requestId
      properties:
        requestId: 
          type: string
          format: uuid
          description: the requestId that was passed
    HeartbeatResponse:
      type: object
      required:
        - timestamp
        - status
      properties:
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        status:
          type: string
          enum:
            - UP
            - DOWN
        error:
          $ref: '#/components/schemas/Error'
      xml:
        name: HeartbeatResponse
    HIPHealthInformationRequest:
      type: object
      required:
        - requestId
        - timestamp
        - transactionId
        - hiRequest
      properties:
        requestId:
          $ref: '#/components/schemas/UuidSchema'
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        transactionId:
          $ref: '#/components/schemas/UuidSchema'
        hiRequest: 
          type: object
          required:
            - consent
            - dataPushUrl
            - keyMaterial
            - dateRange
          properties:
            consent:
              $ref: '#/components/schemas/consent'
            dateRange:
              $ref: '#/components/schemas/DateRange'
            dataPushUrl:
              type: string
            keyMaterial:
              $ref: '#/components/schemas/KeyMaterial'
    DataNotification:
      type: object
      required:
        - transactionId
        - entries
        - keyMaterial
        - pageNumber
        - pageCount
      properties:
        pageNumber:
          type: integer
          description: Current page number.
        pageCount:
          type: integer
          description: Total number of pages.
        transactionId:
          type: string
          format: uuid
          description: Transaction Id issued when data requested.
        entries:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/EntryContent'
              - $ref: '#/components/schemas/EntryLink'
        keyMaterial:
          $ref: '#/components/schemas/KeyMaterial'
    EntryContent:
      type: object
      required:
        - content
        - media
        - checksum
        - careContextReference
      properties:
        content:
          type: string
          description: Encrypted content
          example: Encrypted content of data packaged in FHIR bundle
        media:
          type: string
          enum: ['application/fhir+json']
          description: mimetype of the content.
        checksum:
          type: string
          description: Md5 checksum of the content before encryption
        careContextReference:
          type: string
          example: RVH1008
          description: care context reference number.
    EntryLink:
      type: object
      required:
        - link
        - media
        - checksum
        - careContextReference
      properties:
        link:
          type: string
          description: Encrypted content
          example: https://data-from.net/sa2321afaf12e13
        media:
          type: string
          enum: ['application/fhir+json']
          description: mimetype of the content.
        checksum:
          type: string
          description: Md5 checksum of the content before encryption
        careContextReference:
          type: string
          example: NCC1701
          description: care context reference number.
    PatientAuthInitResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        auth:
          type: object
          required:
            - transactionId
            - mode
          properties:
            transactionId:
              type: string
            mode:
              $ref: '#/components/schemas/AuthenticationMode'
            meta:
              $ref: '#/components/schemas/AuthMeta'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    
    AuthMeta:
      type: object
      properties:
        hint:
          type: string
        expiry:
          type: string
          example: "2019-12-30T12:01:55Z"
      xml:
        name: Meta
    
    PatientAddress:
      type: object
      properties:
        line:
          type: string
        district:
          type: string
        state:
          type: string
        pincode:
          type: string
    
    PatientDemographicResponse:
      type: object
      required:
        - id
        - name
        - gender
        - yearOfBirth
      properties:
        id:
          type: string
          example: <patient-id>@<consent-manager-id>
          description: PHR Identifier of patient at consent manager
        name:
          type: string
          example: "Hina Patel"
        gender:
          $ref: '#/components/schemas/PatientGender'
        yearOfBirth:
          type: integer
          example: 2000
        address:
          $ref: '#/components/schemas/PatientAddress'
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
          xml:
            name: identifiers
            wrapped: true
    
    PatientAuthConfirmResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        auth:
          type: object
          description: >
            depending on the purpose of auth, as specified in /auth/init, the response may include the following 
              1. LINK - only returns **accessToken**
              2. KYC - only returns **patient**
              3. KYC_AND_LINK - returns both **accessToken** and **patient**
          properties:
            accessToken :
              type: string
              description: access token for initialization of subsequent action. 
            patient:
              $ref: '#/components/schemas/PatientDemographicResponse'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    
    PatientCareContextLinkResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        acknowledgement:
          type: object
          required:
            - status
          properties:
            status: 
              type: string
              enum:
              - SUCCESS
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    PatientDiscoveryResult:
      type: object
      required:
        - requestId
        - timestamp
        - transactionId
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        transactionId:
          type: string
          format: uuid
        patient:
          $ref: '#/components/schemas/PatientRepresentation'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
      xml:
        name: PatientDiscoveryResult
    PatientLinkReferenceResult:
      type: object
      required:
        - requestId
        - timestamp
        - resp
        - transactionId
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        transactionId:
          $ref: '#/components/schemas/UuidSchema'
        link:
          type: object
          required:
            - referenceNumber
            - authenticationType
          properties:
            referenceNumber:
              type: string
            authenticationType:
              type: string
              enum: ['DIRECT', 'MEDIATED']
            meta:
              $ref: '#/components/schemas/Meta'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    PatientLinkResult:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        patient:
          type: object
          required:
            - referenceNumber
            - display
            - careContexts
          properties:
            referenceNumber:
              type: string
            display:
              type: string
            careContexts:
              type: array
              items:
                $ref: '#/components/schemas/CareContextRepresentation'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    HIPConsentNotificationResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        acknowledgement:
          $ref: '#/components/schemas/ConsentAcknowledgement'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    OpenIdConfiguration:
      type: object
      properties:
        jwks_uri:
          type: string
          format: uri
          example: "https://ncg-gateway/certs"
    Certs:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/CertificateOrKeyGetSchema'
    CertificateOrKeyGetSchema:
      type: object
      properties:
        e:
          type: string
        kid:
          type: string
        kty:
          type: string
        n:
          type: string
        use:
          type: string
        x5c:
          type: array
          items:
            description: A PKIX certificate [RFC5280]
            type: string
        x5t:
          type: string
        x5t#S256:
          type: string
        alg:
          type: string
    ConsentAcknowledgement:
      type: object
      required:
        - status
        - consentId
      properties:
        status:
          type: string
          enum:
          - OK
          - UNKNOWN
        consentId:
          type: string
          example: <consent-artefact-id>
    SessionResponse:
      type: object
      properties:
        accessToken:
          type: string
          example: eyJhbGciOiJSUzI1Ni.IsInR5cCIgOiAiSldUIiwia2lkIiA6ICJrVVp.2MXJQMjRyYXN1UW9wU2lWbkdZQUZIVFowYVZGVWpYNXFLMnNibTk0In0
        expiresIn:
          type: integer
          example: 1800
          description: In Minutes
        refreshExpiresIn:
          type: integer
          example: 1800
          description: In Minutes
        refreshToken:
          type: string
          example: eyJhbGciOiJSUzI1Ni.IsInR5cCIgOiAiSldUIiwia2lkIiA6ICJrVVp.2MXJQMjRyYXN1UW9wU2lWbkdZQUZIVFowYVZGVWpYNXFLMnNibTk0In0
        tokenType:
          type: string
          example: bearer
    SessionRequest:
      type: object
      required:
        - clientId
        - clientSecret
        - grantType
      properties:
        clientId:
          type: string
        clientSecret:
          type: string
        grantType:
          type: string
          enum: [ClientCredentials,RefreshToken]
    HealthInformationNotification:
      type: object
      required:
        - requestId
        - timestamp
        - notification
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request. 
          example: "499a5a4a-7dda-4f20-9b67-e24589627061"
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        notification:
          type: object
          required:
            - consentId
            - transactionId
            - doneAt
            - notifier
            - statusNotification
          properties:
            consentId:
              $ref: '#/components/schemas/UuidSchema'
            transactionId:
              $ref: '#/components/schemas/UuidSchema'
            doneAt:
              type: string
              format: date-time
            notifier:
              type: object
              properties:
                type:
                  type: string
                  enum: [HIU, HIP]
                id:
                  type: string
                  example: tmh
            statusNotification:
              type: object
              required:
                - sessionStatus
                - hipId
              properties:
                sessionStatus:
                  type: string
                  enum: [TRANSFERRED, FAILED]
                hipId:
                  type: string
                  example: max
                statusResponses:
                  type: array
                  items:
                    type: object
                    required:
                      - careContextReference
                      - hiStatus
                    properties:
                      careContextReference:
                        type: string
                      hiStatus:
                        type: string
                        enum: [DELIVERED, OK, ERRORED]
                        example: OK
                      description:
                        type: string
    PatientCareContextLinkRequest:
      type: object
      required:
        - requestId
        - timestamp
        - link
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        link:
          $ref: '#/components/schemas/PatientCareContextLink'
    PatientCareContextLink:
      type: object
      required:
        - accessToken
        - patient
      properties:
        accessToken:
          type: string
          description: AccessToken fetched in the user auth process for the purpose specified
        patient:
          type: object
          required:
            - referenceNumber
            - display
            - careContexts
          properties:
            referenceNumber:
              type: string
              example: TMH-PUID-001
              description: patient reference id at HIP
            display:
              type: string
            careContexts:
              type: array
              items:
                $ref: '#/components/schemas/CareContextRepresentation'
              xml:
                name: careContexts
                wrapped: true
    PatientAuthConfirmRequest:
      type: object
      required:
        - requestId
        - timestamp
        - tranasctionId
        - credential
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        tranasctionId:
          type: string
        credential:
          type: object
          description: note, demographic details are only required for demographic auth at this point.
          properties:
            authCode:
              type: string
            demographic:
              $ref: '#/components/schemas/PatientDemographic'
    PatientAuthInitRequest:
      type: object
      required:
        - requestId
        - timestamp
        - query
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        query:
          type: object
          required:
            - id
            - purpose
            - requester
          properties:
            id:
              type: string
              example: "hinapatel@ncg"
              description: id  of the patient understood by the CM
            purpose:
              $ref: '#/components/schemas/PatientAuthPurpose'
            authMode:
              $ref: '#/components/schemas/AuthenticationMode'
            requester:
              type: object
              required:
                - type
                - id
              description: identification of requester
              properties:
                type: 
                  type: string
                  enum: [HIP]
                id:
                  type: string
                  example: 100005
    HIPHealthInformationRequestAcknowledgement:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        hiRequest:
          type: object
          required:
            - transactionId
            - sessionStatus
          properties:
            transactionId: 
              type: string
              format: uuid
            sessionStatus:
              type: string
              enum:
              - ACKNOWLEDGED
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    PatientDemographic:
      type: object
      required:
        - name
        - gender
        - dateOfBirth
      description: Demographic details are only required for demographic auth at this point. Demographic details must be same as registered 
      properties:
        name: 
          type: string
          example: "janki das"
        gender:
          $ref: '#/components/schemas/PatientGender'
        dateOfBirth:
          type: string
          example: "1972-02-29"
          description: date of birth in YYYY-MM-DD format. 
        identifier: 
          $ref: '#/components/schemas/Identifier'
    PatientGender:
      type: string
      enum: [M, F, O, U]
    AuthenticationMode:
      type: string
      enum: ['M0BILE_OTP', 'DIRECT', 'DEMOGRAPHICS', 'AADHAAR_OTP']
      description: > 
        Subjected to CM specific capability
         1. MOBILE_OTP - for SMS OTP
         2. DIRECT - for auth through apps (usually direct)
         3. AADHAAR_OTP - for auth using OTP sent to Aadhaar number
         4. DEMOGRAPHICS - for auth using demographic.
    
    PatientAuthPurpose:
      type: string
      enum: [LINK, KYC, KYC_AND_LINK]
      description: what is the purpose of user auth
    
    PatientAuthModeQueryResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        auth:
          type: object
          required:
            - purpose
            - modes
          properties:
            purpose:
              $ref: '#/components/schemas/PatientAuthPurpose'
            modes: 
              type: array
              items:
                $ref: '#/components/schemas/AuthenticationMode'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    
    PatientAuthModeQueryRequest:
      type: object
      required:
        - requestId
        - timestamp
        - query
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        query:
          type: object
          required:
            - id
            - purpose
            - requester
          properties:
            id:
              type: string
              example: hinapatel79@ncg
            purpose:
              $ref: '#/components/schemas/PatientAuthPurpose'
            requester:
              type: object
              required:
                - id
                - type
              properties:
                type: 
                  type: string
                  enum: [HIP, HIU]
                id:
                  type: string
                  example: 100005