openapi: 3.0.2
info:
  title: Format EMR
  version: 1.2.4
  description: 
    In order to be compatible with SiVIEW Exam/Ocular, you must develop an API publicly accessible 
    that complies with the following documentation


    It contains a description to start a new exam with an existing patient from an ERP/EMR
    and a description to receive data from SiVIEW Exam.
    
    
    The GET endpoint is invoked by SiVIEW Exam when starting a new Examination.
    
    
    The POST endpoint is called by SiVIEW Exam when the examination is completed
    
    
    Version History 
    
    ```
    - v1.0.0 | 27/aug/2021 | created

    - v1.1.0 | 10/aug/2021 | first draft 

    - v1.2.0 | 06/oct/2021 | update with kerato and bino acuities 

    - v1.2.1 | 09/dec/2021 | translation in english and nullable types

    - v1.2.2 | 23/jan/2023 | Add the reporturl URL to download the PDF report from the web

    - v1.2.3 | 07/mar/2023 | Amend the POST description with Exit in investigations rules
    
    - v1.2.4 | 22/mar/2023 | Exit in investigation code (exitcode) + contact lens export
    
    ```
  

paths:
  /endpoint/siview/api:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmrData'
              examples:
                full example :
                  value:
                    format: in
                    version: '1.2'
                    patients:
                      - id: "L19700"
                        firstname: Jacques
                        lastname: DESMARAIS
                        birthday: '1966-10-23'
                        currentvisit:
                          date: 2018-02-10T09:30Z
                          pdfar: 62.5
                          pdfarod: 31.5
                          pdfaros: 31
                          comment: Data from EMR version x.y.z
                          
                          measures:
                            - type: AUTOREF
                              sphod: 2.5
                              cylod: -1.5
                              axisod: 45
                              sphos: 2
                              cylos: -1.25
                              axisos: 135
                              kerato:
                                mm1od: 8.1
                                axis1od: 50
                                mm2od: 7.8
                                mm1os: 7.5
                                axis1os: 100
                                mm2os: 8
                            - type: LM
                              sphod: 2.75
                              cylod: -1.5
                              axisod: 45
                              sphos: 2.25
                              cylos: -1.25
                              axisos: 155
                
                minimum example:
                  value:
                    format: in
                    version: '1.2'
                    patients:
                      - id: "1A2C"
                        firstname: Jacques
                        lastname: DESMARAIS
                        birthday: '1966-10-23'
                        currentvisit:
                          date: 2018-02-10T09:30Z
                          comment: Data from EMR version x.y.z
                          measures:
                            - type: LM
                              sphod: 2.75
                              cylod: -1.5
                              axisod: 45
                              sphos: 2.25
                              cylos: -1.25
                              axisos: 155

                empty example:
                  value:
                    format: in
                    version: '1.2'
                    patients:  []
          
          description: Return is OK
        '400':
          description: Params errors
        '401':
          description: Wrong or missing api key
      summary: SiVIEW Exam will call this endpoint to start a subjective refraction.
      description: 
        The web service shall return an [EmrData].
        
        
        The url address field (In SiVIEW Exam) can contain fixed parameters. 
        For example
        
            /your-endpoint/siview/api?shop=12&deviceid=2 
            
        > These parameters allow the webservice to identify which tablet is calling the service and returns the correct patient. Usually it is the current patient/client open file on the CRM/EMR software.
        
        
        The return is a json with a table of patients. Empty [], one patient [ {patient} ] 
        or multiple patients [ {patient1}, {patient2} ] 
        
        
    post:
      requestBody:
        description: EmrData with format="out"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmrData' 
            examples:
              sample_post:
                value:
                    format: out
                    version: '1.2'
                    patients:
                      - id: "L19700"
                        firstname: Jacques
                        lastname: DESMARAIS
                        birthday: '1966-10-23'
                        currentvisit:
                          date: 2018-02-10T09:30Z
                          pdfar: 62.5
                          pdfarod: 31.5
                          pdfaros: 31
                          comment: "Exam done with SiVIEW 1.18.0, duration : 00:02:26. L’AV sur l’OG à chuté au test de dépistage de l’ambiopie, cet œil doit être vu rapidement"
                          reporturl: "https://my.siviewtech.com/pdf/87445412541254112541556323636"
                          measures:
                            - type: FINAL_BINO_MAX_CONVEXE
                              sphod: 2.5
                              cylod: -1.5
                              axisod: 45
                              sphos: 2.0
                              cylos: -1.25
                              axisos: 135
                              vaod: "0.9"
                              vaos:  "1.0"
                            - type: FINAL_MONO
                              sphod: 2.75
                              cylod: -1.5
                              axisod: 45
                              sphos: 2.25
                              cylos: -1.25
                              axisos: 155 
                              vaod: "0.9"
                              vaos:  "1.0"
                            - type: FINAL_BINO_PERCEPTUAL
                              sphod: 2.75
                              cylod: -1.25
                              axisod: 45
                              sphos: 2.25
                              cylos: -1.50
                              axisos: 155 
                              vabino: "1.2"
                            - type: FINAL_BINO_PERCEPTUAL_CONTACTLENS
                              sphod: 2.50
                              cylod: -1.0
                              axisod: 45
                              sphos: 2.00
                              cylos: -1.50
                              axisos: 155 

              exit_in_invesigation_post on left eye:
                value:
                    format: out
                    version: '1.2'
                    patients:
                      - id: "L19700"
                        firstname: Jacques
                        lastname: DESMARAIS
                        birthday: '1966-10-23'
                        currentvisit:
                          date: 2018-02-10T09:30Z
                          pdfar: 62.5
                          pdfarod: 31.5
                          pdfaros: 31
                          comment: "Exam done with SiVIEW 1.18.0, duration : 00:02:26. The refraction did no go normally, the case of the complete analysis cannot be carried out. The patient answers to the fog test were inconsistent for the left eye. The exam has stopped." 
                          reporturl: "https://my.siviewtech.com/pdf/87445412541254112541556323636"
                          measures:
                            - type: FINAL_MONO
                              sphod: 5.75
                              cylod: 0.0
                              axisod: 0
                              sphos: null
                              cylos: null
                              axisos: null
                              vaod: "1.20"
                              vaos: null
                            - type: FINAL_BINO_MAX_CONVEXE
                              sphod: null
                              cylod: null
                              axisod: null
                              vaod: null
                              sphos: null
                              cylos: null
                              axisos: null 
                              vaos:  null
                            - type: FINAL_BINO_PERCEPTUAL
                              sphod: null
                              cylod: null
                              axisod: null
                              sphos: null
                              cylos: null
                              axisos: null 
                              vabino: null
                            - type: FINAL_BINO_PERCEPTUAL_CONTACTLENS
                              sphod: null
                              cylod: null
                              axisod: null
                              sphos: null
                              cylos: null
                              axisos: null 
                
      responses:
        '200':
          description: Exam sucessfully saved
      summary: SiVIEW Exam will send data to this endpoint when the exam is completed.
      description: 
        At the end of the subjective refraction exam, the system will post data
        to this endpoint.  
    
        > exitcode (string)
        
        
        > Exit in investigation code when exam detected an inconsistency in patient answers
      
        ```
          
        NONE     | All good, measures shall not be null,

        MONO_OD  | Right eye exited in investigation, Right measures can be null
        
        MONO_OS  | Left eye exited in investigation, Left measures can be null
        
        MONO_ODS | Both Right and Left eyes exited in investigation, Right and Left measures can be null
        
        BINO     | Bino steps exited in investigation, bino measures can be null

        ```
        
        
        > Special rules >>
        
        > - If a measures.type='FINAL_BINO_PERCEPTUAL' has an attribute .sphod = null
        
        > > 1. Consider the exam has exited in investigation, that means the exam is not complete due to inconsistent answers or pathology from the patient. In this case you can check 
        
        > > 1. If measures.type='FINAL_MONO' has an attribute .sphod = null Then the right eye was not measured
        
        > > 1. If measures.type='FINAL_MONO' has an attribute .sphos = null Then the left eye was not measured
        
        > > 1. Otherwise both monocular measures are valid and only binocular vision was not measured

    parameters:
      - name: api_key
        description: 
          api_key passed along with the headers for each request to secure calls. 
        schema:
          type: string
        in: header
        required: false
components:
  schemas:
  
    EmrData:
      title: EMR Data
      description: Main body for data exchange with your patients / clients management system CRM/EMR. 
      required:
        - format
        - version
      type: object
      properties:
        format:
          description: Direction of the data 
            
            * "in" from server to SiVIEW
            
            * "out" from SiVIEW to server 
          enum:
            - in 
            - out
            
          type: string
          example: '"in"'
        version:
          description: Format version (current 1.2)
          type: string
          example: '"1.2"'
        patients:
          description: Array of Patient (s)
          maxItems: 10
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/Patient'


    Patient:
      title: Patient
      description: Patient model 
      required:
        - currentvisit
        - birthday
        - firstname
        - id
        - lastname
      type: object
      properties:
        id:
          description: 
            A string that is used as a unique identifier for the patient.
            The system will post this id back so your webservice will be able to know which patient it is.
            To ignore this id you can put an empty string ""
          type: string
          nullable: true
        firstname:
          description: First name (no special caracters allowed except "-")
          type: string
        lastname:
          description: Last name (no special caracters allowed except "-")
          type: string
        birthday:
          format: date
          description: Date de naissance patient
          type: string
        lastvisit:
          allOf:
            - $ref: '#/components/schemas/Visit'
            - description: 
                Optional, latest consultation for this patient. This allows the practitioner 
                to start an exam with the latest measurement.
        currentvisit:
          allOf:
            - $ref: '#/components/schemas/Visit'
            - description: 
                Required, current visit. 

    Visit:
      title: Visit
      description: Visit of the patient, also called consultation.
      type: object
      required:
        - date
        - measures
      properties:
        date:
          format: date-time
          description: Visit date (ISO 8601) UTC
          type: string
          example: '2021-10-05T11:20:00Z'
        pdfar:
          format: double
          description: Pupillary distance in mm
          type: number
          nullable: true
          example: 62.5
        pdfarod: 
          format: double 
          description: Distance from the middle of the face to the center of the right eye in mm
          type: number
          nullable: true
          example: 31.5
        pdfaros: 
          format: double
          description: Distance from the middle of the face to the center of the left eye in mm
          type: number
          nullable: true
          example: 31
        comment:
          description: When the format is "out" contains an explanation of the exam  up to 500 characters
          type: string
          nullable: true
          example: 'Exam done with SiVIEW Exam v1.18.24, duration : 00:03:50'
        reporturl: 
          description: 
            Contains a URL to get the PDF file of the report. This url lives 24h, after this period you will no longer be able to download the report
          type: string
          nullable: true
          example : 'https://my.siviewtech.com/pdf/87445412541254112541556323636'
          
        exitcode:
          type: string
          nullable: true 
          example : 'MONO_OS'
          description: Exit in investigation code when exam detected an inconsistency in patient answers
          
            * "NONE" All good, measures shall not be null
            
            * "MONO_OD" Right eye exited in investigation, Right measures can be null
            
            * "MONO_OS" Left eye exited in investigation, Left measures can be null
            
            * "MONO_ODS" Both Right and Left eyes exited in investigation, Right and Left measures can be null
            
            * "BINO" Bino steps exited in investigation, bino measures can be null
            
          enum:
            - NONE 
            - MONO_OD
            - MONO_OS
            - MONO_ODS
            - BINO

        measures:
          description: List of measures can be an empty array
          type: array
          items:
            $ref: '#/components/schemas/Measure'

    Measure:
      description: One measure of the refraction exam (in negative cylinder notation)
      required:
        - type
      type: object
      properties:
        type:
          description: 
            Type de mesure =
            
            - OLD = Last measures
            
            - PRESC = Prescription
            
            - AUTOREF = Aurorefractometer measurement 
            
            - KER =  Keratometer / Autorefractometer data
            
            - LM = Lensmeter measurement
            
            - FINAL_BINO_MAX_CONVEXE = Binocular maxi convex result measure
            
            - FINAL_MONO = Monocular maxi convex result measure
            
            - FINAL_BINO_PERCEPTUAL = Binocular perceptual result measure
            
            - START = Start values
            
            - RAW = Raw data (undaided visual acuities)
            
          enum:
            - OLD
            - PRESC
            - AUTOREF
            - KER
            - LM
            - FINAL_BINO_MAX_CONVEXE
            - FINAL_MONO
            - FINAL_BINO_PERCEPTUAL
            - FINAL_BINO_PERCEPTUAL_CONTACTLENS
            - START
            - RAW
          type: string
          example: AUTOREF
        sphod:
          format: double
          description: Sphere right eye 
          type: number
          nullable: true
          example: 2.5
        cylod:
          format: double
          description: Cylinder right eye (<=0.0)
          type: number
          nullable: true
          example: -1.5
        axisod:
          format: double
          description: Axis right eye (degrees)
          type: number
          nullable: true
          example: 45
        sphos:
          format: double
          description: Sphere left eye
          type: number
          nullable: true
          example: 1.0
        cylos:
          format: double
          description: Cylinder left eye (<=0.0)
          type: number
          nullable: true
          example: 0.0
        axisos:
          format: double
          description: Axis left eye (degrees)
          type: number
          nullable: true
          example: 20
        vabino:
          description: Visual Binocular Acuity decimal (may be null if not done or "<0.1" when less than 1/10)
          type: string
          nullable: true
          example: "0.9"
        vaod:
          description: Right eye visual acuity (may be null if not done or "<0.1" when less than 1/10)
          type: string
          nullable: true
          example: "0.8"
        vaos:
          description: Left eye visual acuity (may be null if not done or "<0.1" when less than 1/10)
          type: string
          nullable: true
          example: "0.3"
        kerato:
          allOf:
            - $ref: '#/components/schemas/Kerato'
            - description: Kerato measurement 

    Kerato:
      description: 
        Kerato measurements expressed in negative cylinder form or corneal radius form

      type: object
      properties:
        mm1od:
          format: double
          description: 'Right Eye kerato radius 1 in millimetres '
          type: number
          example: 8.1
        axis1od:
          description: 'Right Eye kerato axis 1 in degrees (radius 2 is automatically deducted)'
          type: integer
          example : 50
        mm2od:
          format: double
          description: 'Right Eye kerato radius 2 in millimetres '
          type: number
          example: 7.8
        mm1os:
          format: double
          description: 'Lest eye kerato radius 1 in millimetres '
          type: number
          example: 7.5
        axis1os:
          description: 'Left eye kerato axis 1 in degrees (radius 2 is automatically deducted)'
          type: integer
          example : 100
        mm2os:
          format: double
          description: 'Left eye kerato radius 2 in millimetres '
          type: number
          example: 8.0

