
# (c) Secure Identity Alliance

openapi: 3.0.0
info:
  description: OSIA PR Interface
  version: 1.2.0
  title: OSIA Population Registry Interface
  license:
    name: SIA
    url: "https://raw.githubusercontent.com/SecureIdentityAlliance/osia/master/LICENSE"
tags:
  - name: Person
  - name: Identity
  - name: Reference
  - name: Gallery
servers:
  - url: https://pr.com/
paths:

  /v1/persons/{personId}:
    post:
      tags:
        - Person
      summary: Create one person
      operationId: createPerson
      security:
        - BearerAuth: [pr.person.write]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Person'
      responses:
        '201':
          description: Operation successful
        '400':
          description: Bad request
        '403':
          description: Operation not allowed
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      tags:
        - Person
      summary: Read one person
      operationId: readPerson
      security:
        - BearerAuth: [pr.person.read]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Read successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Bad request
        '403':
          description: Read not allowed
        '404':
          description: Unknown record
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Person
      summary: Update one person
      operationId: updatePerson
      security:
        - BearerAuth: [pr.person.write]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Person'
      responses:
        '204':
          description: Update successful
        '400':
          description: Bad request
        '403':
          description: Update not allowed
        '404':
          description: Unknown record
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Person
      summary: Delete a person and all its identities
      operationId: deletePerson
      security:
        - BearerAuth: [pr.person.write]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Delete successful
        '400':
          description: Bad request
        '403':
          description: Delete not allowed
        '404':
          description: Unknown record
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/persons/{personIdTarget}/merge/{personIdSource}:
    post:
      tags:
        - Person
      summary: Merge two persons
      description: |
        Merge two person records into a single one. Identity ID are preserved and in case of duplicates
        an error is returned and no changes are done.
        If the operation is successful, the person merged is deleted.
      operationId: mergePerson
      security:
        - BearerAuth: [pr.person.write]
      parameters:
        - name: personIdTarget
          in: path
          description: the id of the person receiving new identities
          required: true
          schema:
            type: string
        - name: personIdSource
          in: path
          description: the id of the person giving the identities
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Merge successful
        '400':
          description: Bad request
        '403':
          description: Merge not allowed
        '404':
          description: Unknown record
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/persons/{personId}/identities:
    get:
      tags:
        - Identity
      summary: Read all the identities of a person
      operationId: readIdentities
      security:
        - BearerAuth: [pr.identity.read]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Identity'
        '400':
          description: Bad request
        '403':
          description: Operation not allowed
        '404':
          description: Unknown record
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Identity
      summary: Create one identity and generate its id
      operationId: createIdentity
      security:
        - BearerAuth: [pr.identity.write]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Identity'
                - type: object
                  required:
                    - status
      responses:
        '200':
          description: Insertion successful
          content:
            application/json:
              schema:
                type: object
                required:
                  - identityId
                properties:
                  identityId:
                    type: string
        '400':
          description: Bad request
        '403':
          description: Insertion not allowed
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/persons/{personId}/identities/{identityId}:
    post:
      tags:
        - Identity
      summary: Create one identity
      description: |
        Create one new identity for a person. The provided identityId is
        checked for validity and used for the new identity.
      operationId: createIdentityWithId
      security:
        - BearerAuth: [pr.identity.write]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: identityId
          in: path
          description: the id of the identity
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Identity'
                - type: object
                  required:
                    - status
      responses:
        '201':
          description: Insertion successful
        '400':
          description: Bad request
        '403':
          description: Insertion not allowed
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      tags:
        - Identity
      summary: Read one identity
      operationId: readIdentity
      security:
        - BearerAuth: [pr.identity.read]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: identityId
          in: path
          description: the id of the identity
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Read successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identity'
        '400':
          description: Bad request
        '403':
          description: Read not allowed
        '404':
          description: Unknown record
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Identity
      summary: Update one identity
      operationId: updateIdentity
      security:
        - BearerAuth: [pr.identity.write]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: identityId
          in: path
          description: the id of the identity
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Identity'
                - type: object
                  required:
                    - status
      responses:
        '204':
          description: Update successful
        '400':
          description: Bad request
        '403':
          description: Update not allowed
        '404':
          description: Unknown record
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - Identity
      summary: Update partially one identity
      description: Update partially an identity. Payload content is a partial identity object compliant with RFC7396.
      operationId: partialUpdateIdentity
      security:
        - BearerAuth: [pr.identity.write]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: identityId
          in: path
          description: the id of the identity
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Identity'
            example:
              galleries: [G1, G2]
              biographicData:
                gender: null
                nationality: FRA
      responses:
        '204':
          description: Update successful
        '400':
          description: Bad request
        '403':
          description: Update not allowed
        '404':
          description: Unknown record
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Identity
      summary: Delete one identity
      operationId: deleteIdentity
      security:
        - BearerAuth: [pr.identity.write]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: identityId
          in: path
          description: the id of the identity
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Delete successful
        '400':
          description: Bad request
        '403':
          description: Delete not allowed
        '404':
          description: Unknown record
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/persons/{personId}/identities/{identityId}/status:
    put:
      tags:
        - Identity
      summary: Change the status of an identity
      operationId: setIdentityStatus
      security:
        - BearerAuth: [pr.identity.write]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: identityId
          in: path
          description: the id of the identity
          required: true
          schema:
            type: string
        - name: status
          in: query
          description: The status of the identity
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Operation successful
        '400':
          description: Bad request
        '403':
          description: Operation not allowed
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/persons/{personId}/identities/{identityId}/reference:
    put:
      tags:
        - Reference
      summary: Define the reference
      operationId: defineReference
      security:
        - BearerAuth: [pr.reference.write]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: identityId
          in: path
          description: the id of the identity
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Operation successful
        '400':
          description: Bad request
        '403':
          description: Operation not allowed
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    
  /v1/persons/{personId}/reference:
    get:
      tags:
        - Reference
      summary: Read the reference
      operationId: readReference
      security:
        - BearerAuth: [pr.reference.read]
      parameters:
        - name: personId
          in: path
          description: the id of the person
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Read successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identity'
        '400':
          description: Bad request
        '403':
          description: Read not allowed
        '404':
          description: Unknown record
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'


  /v1/galleries:
    get:
      tags:
        - Gallery
      summary: Read the ID of all the galleries
      operationId: readGalleries
      security:
        - BearerAuth: [pr.gallery.read]
      parameters:
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '400':
          description: Bad request
        '403':
          description: Read not allowed
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/galleries/{galleryId}:
    get:
      tags:
        - Gallery
      summary: Read the content of one gallery
      operationId: readGalleryContent
      security:
        - BearerAuth: [pr.gallery.read]
      parameters:
        - name: galleryId
          in: path
          description: the id of the gallery
          required: true
          schema:
            type: string
        - name: transactionId
          in: query
          description: The id of the transaction
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - personId
                    - identityId
                  properties:
                    personId:
                      type: string
                    identityId:
                      type: string
        '400':
          description: Bad request
        '403':
          description: Read not allowed
        '404':
          description: Unknown record
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: Error code
          type: integer
          format: int32
        message:
          description: Error message
          type: string
    Person:
      description: >-
        Person entity.
      type: object
      required:
        - status
        - physicalStatus
      properties:
        personId:
          type: string
          description: The unique id for this person
        status:
          type: string
          enum: [ACTIVE, INACTIVE]
        physicalStatus:
          type: string
          enum: [DEAD, ALIVE]
    Identity:
      type: object
      properties:
        identityId:
          type: string
        status:
          type: string
          enum: [CLAIMED, VALID, INVALID, REVOKED]
        galleries:
          type: array
          items:
            type: string
          minItems: 1
          uniqueItems: true
        clientData:
          type: string
          format: byte
        contextualData:
          $ref: '#/components/schemas/ContextualData'
        biographicData:
          $ref: '#/components/schemas/BiographicData'
        biometricData:
          type: array
          items:
            $ref: '#/components/schemas/BiometricData'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
    ContextualData:
      type: object
      additionalProperties: true
      example:
        enrollmentDate: "2019-01-11"
    BiographicData:
      type: object
      additionalProperties: true
      example:
        firstName: John
        lastName: Doo
        dateOfBirth: "1985-11-30"
        gender: M
        nationality: FRA

    CompressionType:
      type: string
      enum: [NONE, JPEG, JPEG2000, PNG]

    DocumentFormatType:
      type: string
      enum: [NONE, JPEG, PNG, PDF]

    Document:
      type: object
      required:
        - documentType
        - parts
      properties:
        documentType:
          $ref: '#/components/schemas/DocumentType'
        instance:
          type: string
          description: "Used to separate two distincts documents of the same type (ex: two passports)"
        parts:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/DocumentPart'
    DocumentPart:
      type: object
      properties:
        pages:
          type: array
          description: The pages included in this part. Can be a single page number, or a list.
          minItems: 1
          items:
            type: integer
        data:
          type: string
          format: byte
          description: Base64-encoded data of the document
        dataRef:
          type: string
          format: uri
          description: URI to the data
          example: "http://server.com/buffer?id=00003"
        width:
          type: integer
          description: the width of the image in pixels
        height:
          type: integer
          description: the height of the image in pixels
        format:
          $ref: '#/components/schemas/DocumentFormatType'
        captureDate:
          type: string
          format: date
          example: "2019-05-21"
        captureDevice:
          type: string
          description: A string identifying the device used to capture the document part
    DocumentType:
      type: string
      description: Type of document. Can be extended.
      enum: [ID_CARD, PASSPORT]

    BiometricData:
      type: object
      required:
        - biometricType
      properties:
        biometricType:
          $ref: '#/components/schemas/BiometricType'
        biometricSubType:
          $ref: '#/components/schemas/BiometricSubType'
        image:
          type: string
          format: byte
          description: Base64-encoded image
        imageRef:
          type: string
          format: uri
          description: URI to an image
          example: "http://imageserver.com/image?id=00003"
        captureDate:
          type: string
          format: date
          example: "2019-05-21"
        captureDevice:
          type: string
          description: A string identifying the device used to capture the biometric
        width:
          type: integer
          description: the width of the image
        height:
          type: integer
          description: the height of the image
        bitdepth:
          type: integer
        resolution:
          type: integer
          description: the image resolution (in DPI)
        compression:
          $ref: '#/components/schemas/CompressionType'
    BiometricType:
      type: string
      enum:
        - FACE
        - FINGER
        - PALM
        - IRIS
        - UNKNOWN
    BiometricSubType:
      type: string
      enum:
        - UNKNOWN
        - RIGHT_THUMB
        - RIGHT_INDEX
        - RIGHT_MIDDLE
        - RIGHT_RING
        - RIGHT_LITTLE
        - LEFT_THUMB
        - LEFT_INDEX
        - LEFT_MIDDLE
        - LEFT_RING
        - LEFT_LITTLE
        - PLAIN_RIGHT_FOUR_FINGERS
        - PLAIN_LEFT_FOUR_FINGERS
        - PLAIN_THUMBS
        
        - UNKNOWN_PALM
        - RIGHT_FULL_PALM
        - RIGHT_WRITERS_PALM
        - LEFT_FULL_PALM
        - LEFT_WRITERS_PALM
        - RIGHT_LOWER_PALM
        - RIGHT_UPPER_PALM
        - LEFT_LOWER_PALM
        - LEFT_UPPER_PALM
        - RIGHT_OTHER
        - LEFT_OTHER
        - RIGHT_INTERDIGITAL
        - RIGHT_THENAR
        - LEFT_INTERDIGITAL
        - LEFT_THENAR
        - LEFT_HYPOTHENAR
        
        - RIGHT_INDEX_AND_MIDDLE
        - RIGHT_MIDDLE_AND_RING
        - RIGHT_RING_AND_LITTLE
        - LEFT_INDEX_AND_MIDDLE
        - LEFT_MIDDLE_AND_RING
        - LEFT_RING_AND_LITTLE
        - RIGHT_INDEX_AND_LEFT_INDEX
        - RIGHT_INDEX_AND_MIDDLE_AND_RING
        - RIGHT_MIDDLE_AND_RING_AND_LITTLE
        - LEFT_INDEX_AND_MIDDLE_AND_RING
        - LEFT_MIDDLE_AND_RING_AND_LITTLE
        
        - EYE_UNDEF
        - EYE_RIGHT
        - EYE_LEFT
        
        - PORTRAIT
        - LEFT_PROFILE
        - RIGHT_PROFILE
