@checkdigit/eslint-plugin 7.17.1 → 7.18.0-PR.143-8290

package/src/services/person/v1/swagger.yml

@@ -0,0 +1,1157 @@
+openapi: 3.0.0
+info:
+  title: Person
+  description: |
+    Person is a service used to create, update, or retrieve data about a person.
+
+    Primary API operations:
+    - create and update a person
+    - retrieve a person
+    - retrieve a history of changes to the person record
+    - retrieve masked person data
+
+    **Personally Identifiable Information (PII)**
+
+    Personally Identifiable Information (PII) is any information that can be used to determine an individual's identity,
+    either alone or when combined with other data.
+
+    Person Service returns encrypted PII and non-encrypted non-PII. Whether information is PII may depend on its
+    relationship to other data. For example, a city is non-PII, while a city paired with a last name is PII. In cases
+    where information is unlikely PII, but significantly narrowing, and encryption is unavailable, extra steps will
+    be taken to obfuscate the information.
+
+    ### Create a Person
+    Before creating a person, encryption keys must be created using `PUT /data-encryption-key/{dataEncryptionKeyId}`.
+
+    To create a person, send a `PersonRequest` object using `PUT /person/{personId}`.
+    PII properties in the `Person` object must be encrypted with a data encryption key (DEK). Include the
+    `dataEncryptionKeyId` used to create the encryption keys.
+
+    #### Encrypting Person object
+
+    To encrypt the values in the `Person` object use an AES algorithm and a DEK.
+
+    #### EncryptedDataEncryptionKey
+    To create the `encryptedDataEncryptionKey`, encrypt the DEK using the `transmissionKey` in the
+    `DataEncryptionKeyResponse` object and the RSA algorithm.
+
+    ### Updating a Person
+    When updating a person, use the same `dataEncryptionKeyId` used when the person was created.
+
+    ### Retrieving a Person
+    In the `PersonResponse` object, Person data is encrypted using a DEK generated by Person Service. This DEK is
+    encrypted with each `PublicKey` included in the `DataEncryptionKeyRequest` object. Each encrypted DEK is paired
+    with a hashed version of the `PublicKey` used to encrypt it. See [hash](https://github.com/checkdigit/hash).
+
+    #### Decrypting the encryptedDataEncryptionKey
+
+    The encrypted data encryption key is paired with a hashed version of the public key used to encrypt it.
+    See [hash](https://github.com/checkdigit/hash).
+
+    To decrypt, use the RSA algorithm and the private key for the public key that's hashed.
+
+    #### Decrypting person data
+
+    Decrypt each field using the AES algorithm and the decrypted encryptedDataEncryptionKey (i.e. DEK).
+
+    © Check Digit LLC. 2020-2024
+  version: 1.8.1
+  contact:
+    name: Check Digit
+
+servers:
+  - url: /person/v1
+
+tags:
+  - name: Service Health
+  - name: API
+
+x-firehose-logged: false
+
+paths:
+  /ping:
+    get:
+      operationId: 'ping-get'
+      tags:
+        - Service Health
+      description: Tests the availability of the service and returns the current server
+        time.
+      responses:
+        '200':
+          $ref: '#/components/responses/Ping'
+        default:
+          $ref: '#/components/responses/ServerError'
+
+  /public-key:
+    get:
+      operationId: 'public-key-get'
+      tags:
+        - API
+      description: Retrieves Person Service's rsa public key. This key is used to securely transmit data to Person Service APIs.
+      responses:
+        '200':
+          $ref: '#/components/responses/PublicKeyResponse'
+        default:
+          $ref: '#/components/responses/ServerError'
+
+  /data-encryption-key/{dataEncryptionKeyId}:
+    get:
+      operationId: 'data-encryption-key-get'
+      tags:
+        - API
+      description: |
+        Retrieves data encryption keys. Data encryption keys are RSA encrypted and paired with a hashed version of
+        the public key used to encrypt.
+      parameters:
+        - $ref: '#/components/parameters/dataEncryptionKeyId'
+      responses:
+        '200':
+          $ref: '#/components/responses/DataEncryptionKeyResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        default:
+          $ref: '#/components/responses/ServerError'
+    put:
+      x-firehose-logged: true
+      operationId: 'data-encryption-key-put'
+      tags:
+        - API
+      description: |
+        Creates data encryption keys used by Person Service to encrypt a Person object. The dataEncryptionKeyId is included
+        in the PersonRequest when creating a Person object.
+
+        Data encryption keys can be reused when creating new Person objects. This is particularly useful for batch
+        operations.
+      parameters:
+        - $ref: '#/components/parameters/dataEncryptionKeyId'
+      requestBody:
+        $ref: '#/components/requestBodies/DataEncryptionKeyRequest'
+      responses:
+        '200':
+          $ref: '#/components/responses/DataEncryptionKeyResponse'
+        default:
+          $ref: '#/components/responses/ServerError'
+
+  /person/{personId}:
+    get:
+      operationId: 'person-get'
+      tags:
+        - API
+      description: Retrieves encrypted person data.
+      parameters:
+        - $ref: '#/components/parameters/personId'
+        - $ref: '#/components/parameters/at'
+        - $ref: '#/components/parameters/publicKeyHash'
+      responses:
+        '200':
+          $ref: '#/components/responses/PersonResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        default:
+          $ref: '#/components/responses/ServerError'
+    put:
+      x-firehose-logged: true
+      operationId: 'person-put'
+      tags:
+        - API
+      description: |
+        Store or update person data. Use ifMatch to verify version for updates.
+
+        Person object properties described as encrypted must be encrypted using an AES generated secret key. The secret
+        key used must also be encrypted with the RSA algorithm using the transmissionKey returned from /data-encryption-key.
+      parameters:
+        - $ref: '#/components/parameters/personId'
+        - $ref: '#/components/parameters/ifMatch'
+        - $ref: '#/components/parameters/createdOn'
+        - $ref: '#/components/parameters/lastModified'
+      requestBody:
+        $ref: '#/components/requestBodies/PersonRequest'
+      responses:
+        '200':
+          $ref: '#/components/responses/PersonResponse'
+        '409':
+          description: Person record exists but with different data.
+        '412':
+          $ref: '#/components/responses/PreconditionFailed'
+        default:
+          $ref: '#/components/responses/ServerError'
+
+  /person/{personId}/history:
+    get:
+      operationId: 'person-history-get'
+      tags:
+        - API
+      description: |
+        Returns a History object that includes a list of Response objects. Each Response object
+        represents a change to data in the Person object.
+      parameters:
+        - $ref: '#/components/parameters/personId'
+        - $ref: '#/components/parameters/toDate'
+        - $ref: '#/components/parameters/fromDate'
+        - $ref: '#/components/parameters/publicKeyHash'
+      responses:
+        '200':
+          $ref: '#/components/responses/History'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        default:
+          $ref: '#/components/responses/ServerError'
+
+  /person/{personId}/masked:
+    get:
+      operationId: 'person-masked-get'
+      tags:
+        - API
+      description: Retrieves a person record with identifying data masked.
+      parameters:
+        - $ref: '#/components/parameters/personId'
+        - $ref: '#/components/parameters/at'
+      responses:
+        '200':
+          $ref: '#/components/responses/PersonMaskedResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        default:
+          $ref: '#/components/responses/ServerError'
+
+components:
+  schemas:
+    Ping:
+      type: object
+      additionalProperties: false
+      required:
+        - serverTime
+      properties:
+        serverTime:
+          type: string
+          format: date-time
+          description: Current server time
+
+    DataEncryptionKeyId:
+      type: string
+      description: |
+        Reference to encryption keys Person Service used to encrypt the Person object.
+
+        Updates must use the same dataEncryptionKeyId.
+      format: uuid
+
+    DataEncryptionKeyResponse:
+      type: object
+      required:
+        - encryptedDataEncryptionKeys
+        - transmissionKey
+        - createdOn
+        - lastModified
+      properties:
+        createdOn:
+          description: Time data was first stored
+          type: string
+          format: date-time
+        lastModified:
+          description: Time data was last modified
+          type: string
+          format: date-time
+        encryptedDataEncryptionKeys:
+          type: array
+          items:
+            $ref: '#/components/schemas/EncryptedDataEncryptionKey'
+        transmissionKey:
+          type: string
+          description: |
+            A PEM formatted public key to use when transmitting data to Person service.
+            Encrypt the data encryption key used to encrypt data being sent using the transmissionKey.
+
+    DataEncryptionKeyRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - publicKeys
+      properties:
+        publicKeys:
+          type: array
+          minItems: 1
+          description: |
+            List of public keys in PEM format.
+
+            Associated private keys can be used to decrypt person data encrypted by Person Service.
+          items:
+            $ref: '#/components/schemas/PublicKey'
+
+    PersonRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - dataEncryptionKeyId
+        - encryptedDataEncryptionKey
+        - person
+      properties:
+        dataEncryptionKeyId:
+          $ref: '#/components/schemas/DataEncryptionKeyId'
+        encryptedDataEncryptionKey:
+          description: Encrypted version of AES-256 DEK
+          type: string
+        person:
+          $ref: '#/components/schemas/Person'
+
+    PersonRecord:
+      type: object
+      additionalProperties: false
+      description: Encrypted version of object stored with created on and last modified metadata.
+      required:
+        - createdOn
+        - updatedOn
+        - person
+      properties:
+        createdOn:
+          description: Time data was first stored
+          type: string
+          format: date-time
+        updatedOn:
+          description: Time data was last stored
+          type: string
+          format: date-time
+        lastModified:
+          description: Time data was last stored (deprecated, use updatedOn)
+          deprecated: true
+          type: string
+          format: date-time
+        person:
+          $ref: '#/components/schemas/Person'
+
+    PersonResponse:
+      type: object
+      additionalProperties: false
+      description: |
+        Encrypted version of object stored and related ids and metadata. A encryptedDataEncryptionKey is included if
+        a publicKeyHash query parameter is supplied as part of request.
+      required:
+        - dataEncryptionKeyId
+        - storageKeyId
+        - createdOn
+        - updatedOn
+        - person
+      properties:
+        dataEncryptionKeyId:
+          $ref: '#/components/schemas/DataEncryptionKeyId'
+        storageKeyId:
+          type: string
+          description: |
+            DEK's non-derived identifier to be used by Check Digit services only.
+        encryptedDataEncryptionKey:
+          description: |
+            Encrypted DEK matching the publicKeyId sent in the request. Used to decrypt values in the Person object.
+          type: string
+        createdOn:
+          description: Time data was first stored
+          type: string
+          format: date-time
+        updatedOn:
+          description: Time data was last stored
+          type: string
+          format: date-time
+        lastModified:
+          description: Time data was last stored (deprecated, use updatedOn)
+          deprecated: true
+          type: string
+          format: date-time
+        person:
+          $ref: '#/components/schemas/Person'
+
+    PersonMaskedResponse:
+      type: object
+      additionalProperties: false
+      description: |
+        Encrypted version of object stored and related ids and metadata. A encryptedDataEncryptionKey is included if
+        a publicKeyHash query parameter is supplied as part of request.
+      required:
+        - createdOn
+        - updatedOn
+        - person
+      properties:
+        createdOn:
+          description: Time data was first stored
+          type: string
+          format: date-time
+        updatedOn:
+          description: Time data was last stored
+          type: string
+          format: date-time
+        person:
+          $ref: '#/components/schemas/PersonMasked'
+
+    PhoneType:
+      type: string
+      description: Type of phone number.
+      enum:
+        - HOME
+        - WORK
+        - MOBILE
+        - FAX
+        - MAIN
+        - OTHER
+
+    PersonMasked:
+      type: object
+      additionalProperties: false
+      description: |
+        This object includes masked person data.
+      properties:
+        company:
+          type: string
+          description: Masked company name.
+        firstName:
+          minLength: 1
+          type: string
+          description: Masked first name.
+        middleName:
+          minLength: 1
+          type: string
+          description: Masked middle name.
+        lastName:
+          minLength: 1
+          type: string
+          description: Masked last name.
+        addresses:
+          type: array
+          description: Masked address information.
+          items:
+            $ref: '#/components/schemas/AddressMasked'
+        phones:
+          type: array
+          description: Masked phone information.
+          items:
+            required:
+              - number
+              - type
+            type: object
+            properties:
+              type:
+                $ref: '#/components/schemas/PhoneType'
+              number:
+                minLength: 1
+                type: string
+                description: Masked phone number.
+        email:
+          minLength: 1
+          type: string
+          description: Masked email address.
+        language:
+          minLength: 1
+          type: string
+          description: Unmasked language preference.
+        timeZone:
+          minLength: 1
+          type: string
+          description: Unmasked time zone preference.
+
+    EncryptedDataEncryptionKey:
+      type: object
+      additionalProperties: false
+      description: |
+        An object that includes an encrypted data encryption key and a hashed version of the public key used to encrypt it.
+      required:
+        - publicKeyHash
+        - encryptedDataEncryptionKey
+      properties:
+        publicKeyHash:
+          $ref: '#/components/schemas/PublicKeyHash'
+        encryptedDataEncryptionKey:
+          description: Data encryption key encrypted with a public key.
+          type: string
+
+    PublicKeyHash:
+      type: string
+      description: UUID derived using @checkdigit/hash
+      format: uuid
+      example: '15a85f64-5717-4562-b3fc-2c963f66afa6'
+
+    Person:
+      type: object
+      additionalProperties: false
+      properties:
+        company:
+          minLength: 1
+          type: string
+          description: Encrypted company name using the AES algorithm
+        title:
+          minLength: 1
+          type: string
+          description: Encrypted title using the AES algorithm
+        firstName:
+          minLength: 1
+          type: string
+          description: Encrypted first name using the AES algorithm
+        middleName:
+          minLength: 1
+          type: string
+          description: Encrypted middle name using the AES algorithm
+        lastName:
+          minLength: 1
+          type: string
+          description: Encrypted last name using the AES algorithm
+        addresses:
+          type: array
+          items:
+            $ref: '#/components/schemas/Address'
+        phones:
+          type: array
+          items:
+            $ref: '#/components/schemas/Phone'
+        email:
+          minLength: 1
+          type: string
+          description: Encrypted email address using the AES algorithm
+        language:
+          minLength: 1
+          type: string
+          description: User's language preference
+        timeZone:
+          minLength: 1
+          type: string
+          description: User's timezone
+
+    History:
+      type: object
+      additionalProperties: false
+      required:
+        - updates
+      properties:
+        dataEncryptionKeyId:
+          type: string
+          description: |
+            Reference to encryption keys Person Service used to encrypt the Person object.
+
+            Updates must use the same dataEncryptionKeyId.
+          format: uuid
+        storageKeyId:
+          type: string
+          description: |
+            DEK's non-derived identifier to be used by Check Digit services only.
+        encryptedDataEncryptionKey:
+          description: |
+            Encrypted DEK matching the publicKeyId sent in the request. Used to decrypt all the items in the list.
+          type: string
+        updates:
+          type: array
+          description: |
+            A list of PersonRecord objects. Each object represents a change to data in the Person object.
+            Objects are sorted by the lastModified date with the most recent object first.
+          items:
+            $ref: '#/components/schemas/PersonRecord'
+
+    Address:
+      required:
+        - country
+        - streetLines
+        - type
+      type: object
+      properties:
+        type:
+          type: string
+          description: Type of address
+          enum:
+            - BILLING
+            - SHIPPING
+            - STATEMENTS
+            - OTHER
+        streetLines:
+          maxItems: 4
+          minItems: 1
+          type: array
+          description: Encrypted street lines using the AES algorithm
+          items:
+            minLength: 1
+            type: string
+            description: Street line
+        city:
+          minLength: 1
+          type: string
+          description: City
+        region:
+          minLength: 1
+          type: string
+          description: Region, State or Province
+        postalCode:
+          minLength: 1
+          type: string
+          description: |
+            AES encrypted postal code. This value should contain only alphanumeric characters.
+            Including non-alphanumeric characters will result in a 400 when sent as a request.
+        reportablePostalCode:
+          type: string
+          description: Postal code for reporting purposes.
+        country:
+          $ref: '#/components/schemas/Country'
+
+    AddressMasked:
+      type: object
+      required:
+        - country
+        - streetLines
+        - type
+      properties:
+        type:
+          type: string
+          description: Type of address.
+          enum:
+            - BILLING
+            - SHIPPING
+            - STATEMENTS
+            - OTHER
+        streetLines:
+          maxItems: 4
+          minItems: 1
+          type: array
+          description: Street lines with all non-numeric characters masked.
+          items:
+            minLength: 1
+            type: string
+            description: Masked street line.
+        city:
+          minLength: 1
+          type: string
+          description: Unmasked city.
+        region:
+          minLength: 1
+          type: string
+          description: Unmasked region, state or province.
+        country:
+          $ref: '#/components/schemas/Country'
+        postalCodeLongHash:
+          minLength: 1
+          type: string
+          description: Long-form postal code hashed using @checkdigit/hash.
+        postalCodeShortHash:
+          minLength: 1
+          type: string
+          description: Short-form postal code hashed using @checkdigit/hash.
+
+    Phone:
+      required:
+        - number
+        - type
+      type: object
+      properties:
+        type:
+          $ref: '#/components/schemas/PhoneType'
+        number:
+          minLength: 1
+          type: string
+          description: Encrypted phone number using the AES algorithm
+        extension:
+          minLength: 1
+          type: string
+          description: Encrypted phone number extension using the AES algorithm
+
+    Error:
+      type: object
+      properties:
+        message:
+          minLength: 1
+          type: string
+        code:
+          type: string
+      description: Error message
+
+    PublicKey:
+      description: RSA generated public key in PEM format
+      type: string
+      example: |
+        -----BEGIN PUBLIC KEY-----
+        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwm2sxmRdTF7ZIBA6+ngO
+        8jOTCHmID0PpQB1q85+hrcLSfB1rWY9bzNNLabBo/ajDnA4Pcadq/x6gpg70qZcR
+        9Wxm6TttKzBPZsxasGXgSTDqEi2KcYZgq1mL4qyxUvyIms7/llGy+W9b5huZaVcO
+        xdT1tw/zctbOhb6S2t5vH+zkta/2ncUXjG7i8XdLsJ1qe4K1kYbA4KVkOMmAtw7O
+        4STk0TZDD0YARdmrciorJjbIVt0Xj1CrYQ5QbDGrlfeXgrcZwX5f9wT2MnKlY5oZ
+        5Wtb57oGtLkVf8g6vN/2jGtAmOmHK2hHwNd/+zUet5G/S5uwEli4RgMPP4pUoKgd
+        GQIDAQAB
+        -----END PUBLIC KEY-----
+
+    PublicKeyResponse:
+      description: |
+        This object contains the rsa generated public key for the Person Service. This public key must be used
+        when transmitting encrypted data to Person Service APIs.
+      type: object
+      required:
+        - publicKey
+      properties:
+        publicKey:
+          $ref: '#/components/schemas/PublicKey'
+
+    Country:
+      type: string
+      description: Country ISO 3166-1 alpha-2 codes
+      enum:
+        - AD
+        - AE
+        - AF
+        - AG
+        - AI
+        - AL
+        - AM
+        - AO
+        - AQ
+        - AR
+        - AS
+        - AT
+        - AU
+        - AW
+        - AX
+        - AZ
+        - BA
+        - BB
+        - BD
+        - BE
+        - BF
+        - BG
+        - BH
+        - BI
+        - BJ
+        - BL
+        - BM
+        - BN
+        - BO
+        - BQ
+        - BR
+        - BS
+        - BT
+        - BV
+        - BW
+        - BY
+        - BZ
+        - CA
+        - CC
+        - CD
+        - CF
+        - CG
+        - CH
+        - CI
+        - CK
+        - CL
+        - CM
+        - CN
+        - CO
+        - CR
+        - CU
+        - CV
+        - CW
+        - CX
+        - CY
+        - CZ
+        - DE
+        - DJ
+        - DK
+        - DM
+        - DO
+        - DZ
+        - EC
+        - EE
+        - EG
+        - EH
+        - ER
+        - ES
+        - ET
+        - FI
+        - FJ
+        - FK
+        - FM
+        - FO
+        - FR
+        - GA
+        - GB
+        - GD
+        - GE
+        - GF
+        - GG
+        - GH
+        - GI
+        - GL
+        - GM
+        - GN
+        - GP
+        - GQ
+        - GR
+        - GS
+        - GT
+        - GU
+        - GW
+        - GY
+        - HK
+        - HM
+        - HN
+        - HR
+        - HT
+        - HU
+        - ID
+        - IE
+        - IL
+        - IM
+        - IN
+        - IO
+        - IQ
+        - IR
+        - IS
+        - IT
+        - JE
+        - JM
+        - JO
+        - JP
+        - KE
+        - KG
+        - KH
+        - KI
+        - KM
+        - KN
+        - KP
+        - KR
+        - KW
+        - KY
+        - KZ
+        - LA
+        - LB
+        - LC
+        - LI
+        - LK
+        - LR
+        - LS
+        - LT
+        - LU
+        - LV
+        - LY
+        - MA
+        - MC
+        - MD
+        - ME
+        - MF
+        - MG
+        - MH
+        - MK
+        - ML
+        - MM
+        - MN
+        - MO
+        - MP
+        - MQ
+        - MR
+        - MS
+        - MT
+        - MU
+        - MV
+        - MW
+        - MX
+        - MY
+        - MZ
+        - NA
+        - NC
+        - NE
+        - NF
+        - NG
+        - NI
+        - NL
+        - NO
+        - NP
+        - NR
+        - NU
+        - NZ
+        - OM
+        - PA
+        - PE
+        - PF
+        - PG
+        - PH
+        - PK
+        - PL
+        - PM
+        - PN
+        - PR
+        - PS
+        - PT
+        - PW
+        - PY
+        - QA
+        - RE
+        - RO
+        - RS
+        - RU
+        - RW
+        - SA
+        - SB
+        - SC
+        - SD
+        - SE
+        - SG
+        - SH
+        - SI
+        - SJ
+        - SK
+        - SL
+        - SM
+        - SN
+        - SO
+        - SR
+        - SS
+        - ST
+        - SV
+        - SX
+        - SY
+        - SZ
+        - TC
+        - TD
+        - TF
+        - TG
+        - TH
+        - TJ
+        - TK
+        - TL
+        - TM
+        - TN
+        - TO
+        - TR
+        - TT
+        - TV
+        - TW
+        - TZ
+        - UA
+        - UG
+        - UM
+        - US
+        - UY
+        - UZ
+        - VA
+        - VC
+        - VE
+        - VG
+        - VI
+        - VN
+        - VU
+        - WF
+        - WS
+        - YE
+        - YT
+        - ZA
+        - ZM
+        - ZW
+
+  parameters:
+    at:
+      name: at
+      in: query
+      description: Return data as it was at this time.  Must be at least 1 second
+        in the past.
+      required: true
+      schema:
+        type: string
+        format: date-time
+
+    dataEncryptionKeyId:
+      name: dataEncryptionKeyId
+      in: path
+      description: UUID for key
+      required: true
+      schema:
+        type: string
+        format: uuid
+
+    personId:
+      name: personId
+      in: path
+      description: UUID for person
+      required: true
+      schema:
+        type: string
+        format: uuid
+
+    publicKeyHash:
+      name: publicKeyHash
+      in: query
+      description: UUID derived using @checkdigit/hash
+      required: false
+      schema:
+        type: string
+        format: uuid
+        example: '15a85f64-5717-4562-b3fc-2c963f66afa6'
+
+    ifMatch:
+      name: If-Match
+      in: header
+      description: |
+        Required to make idempotent updates to a person.
+      schema:
+        type: string
+
+    createdOn:
+      name: Created-On
+      in: header
+      description: |
+        Created-On header, establishes createdOn and last-modified values for the created data.
+        If both Created-On and Last-Modified values are provided, the value provided in Created-On
+        will be used for creating the data and the value provided in Last-Modified will be ignored.
+      example: '1970-01-01T00:00:00.000Z'
+      required: false
+      schema:
+        type: string
+        format: date-time
+
+    lastModified:
+      name: Last-Modified
+      in: header
+      description: Can be used to set createdOn or lastModified when creating or updating data respectively.
+      required: false
+      schema:
+        type: string
+        format: date-time
+
+    toDate:
+      name: toDate
+      in: query
+      description: Returns items created before this time. Must be at least 1 second in the past
+      required: true
+      schema:
+        type: string
+        description: Date time in simplified extended ISO format
+        format: date-time
+
+    fromDate:
+      name: fromDate
+      in: query
+      description: Returns elements created at or after this time. Must be at least 1 second in the past
+      required: false
+      schema:
+        type: string
+        description: Date time in simplified extended ISO format
+        default: '1970-01-01T00:00:00.000Z'
+        format: date-time
+
+  requestBodies:
+    PersonRequest:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/PersonRequest'
+
+    DataEncryptionKeyRequest:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/DataEncryptionKeyRequest'
+
+  responses:
+    Ping:
+      description: ping successful response
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Ping'
+
+    PublicKeyResponse:
+      description: Public Key response.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/PublicKeyResponse'
+      headers:
+        Created-On:
+          description: CreatedOn timestamp for the newly created record
+          required: true
+          schema:
+            type: string
+            format: date-time
+
+        Updated-On:
+          description: UpdatedOn timestamp for the existing record
+          required: true
+          schema:
+            type: string
+            format: date-time
+
+    DataEncryptionKeyResponse:
+      description: |
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/DataEncryptionKeyResponse'
+      headers:
+        Created-On:
+          $ref: '#/components/headers/Created-On'
+        Updated-On:
+          $ref: '#/components/headers/Updated-On'
+        Last-Modified:
+          $ref: '#/components/headers/Last-Modified'
+
+    PersonResponse:
+      description: PersonResponse response.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/PersonResponse'
+      headers:
+        Last-Modified:
+          $ref: '#/components/headers/Last-Modified'
+        Created-On:
+          $ref: '#/components/headers/Created-On'
+        Updated-On:
+          $ref: '#/components/headers/Updated-On'
+        ETag:
+          $ref: '#/components/headers/ETag'
+
+    PersonMaskedResponse:
+      description: PersonMaskedResponse response.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/PersonMaskedResponse'
+      headers:
+        Last-Modified:
+          $ref: '#/components/headers/Last-Modified'
+        Created-On:
+          $ref: '#/components/headers/Created-On'
+        Updated-On:
+          $ref: '#/components/headers/Updated-On'
+        ETag:
+          $ref: '#/components/headers/ETag'
+
+    PreconditionFailed:
+      description: Precondition failed
+
+    NotFound:
+      description: Not found
+
+    ServerError:
+      description: Server Error response
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+
+    History:
+      description: A successful history response
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/History'
+
+  headers:
+    ETag:
+      description: Version information
+      schema:
+        type: string
+
+    Last-Modified:
+      description: Date and time at which the record was last modified
+      schema:
+        type: string
+        format: date-time
+
+    Created-On:
+      description: CreatedOn timestamp for the newly created record
+      schema:
+        type: string
+        format: date-time
+
+    Updated-On:
+      description: UpdatedOn timestamp for the existing record
+      schema:
+        type: string
+        format: date-time