openapi: 3.0.1
info:
  title: Senzing REST API
  version: "3.4.1"
  description: >-
    This is the Senzing REST API.  It describes the REST interface
    to Senzing API functions available via REST.  It leverages the
    Senzing native API which is documented at
    [https://docs.senzing.com](https://docs.senzing.com).
    <br><br>
    <b>SSE NOTE:</b> Some end-points described here will indicate "(Supports SSE)" to
    indicate that they support "Server-sent Events" via the `text/event-stream`
    media type.  This support is activated by adding the
    `Accept: text/event-stream` header to a request to override the
    default `application/json` media type.  Further, the end-point will behave
    similarly to its standard operation but will produce `progress` events
    at regular intervals that are equivalent to its `200` response schema.
    Upon success, the final event will be `completed` with the same response
    schema as a `200` response.  Upon failure, the final event will be
    `failed` with same schema as the `4xx` or `5xx` response (typically the
    `SzErrorResponse`)
    <br><br>
    <b>WEB SOCKETS NOTE:</b> Some end-points described here will indicate "(Supports
    WebSockets)" to indicate that they can invoked via the Web Sockets protocol.
    This support is activated by invoking the end-point using the `ws://`
    protocol in the URL.  Any request query parameters can still be sent on the
    URL and the request body can be sent as one or more message from the client
    (as documented).  The end-point response will be sent as one or more
    response messages as documented (sometimes describing progress as with SSE
    end-points).  Upon failure responses will follow the same schema as the
    `4xx` or `5xx` response (typically the `SzErrorResponse`)

servers:
  - url: http://localhost:8250
  - url: '{protocol}://{host}:{port}{path}'
    variables:
      protocol:
        enum:
          - http
          - https
        default: http
      host:
        default: localhost
      port:
        default: '8250'
      path:
        default: '/'

paths:
  /:
    get:
      tags:
        - Admin
      summary: >-
        Gets a root-level response from the server.  This returns the same
        as the `GET /heartbeat` endpoint for now, but may change in the future
        to provide additional information.
      description: |
        The root operation can be used to ensure that the HTTP server is
        indeed running, but this operation does not call upon the underlying
        native Senzing API and therefore does not ensure the Senzing
        initialization or configuration is valid.
      operationId: root
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzBaseResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzBaseResponse'
  /heartbeat:
    get:
      tags:
        - Admin
      summary: >-
        Gets a heartbeat from the server to make sure it is up and
        running.  The response will include the current timestamp.
      description: |
        The heartbeat operation can be used to ensure that the HTTP server is
        indeed running, but this operation does not call upon the underlying
        native Senzing API and therefore does not ensure the Senzing
        initialization or configuration is valid.
      operationId: heartbeat
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzBaseResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzBaseResponse'
  /specifications/open-api:
    get:
      tags:
        - Admin
      summary: >-
        Gets this Open API specification to describe the API.
      description: |
        This operation can be used to obtain the Open API specification in JSON
        format.  The specification can either be the `data` field of a standard
        response (i.e.: a response with a `meta`, `links` and `data` field) or
        as raw format where the root JSON document is the Open API specification
        JSON.
      operationId: openApiSpecification
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzOpenApiSpecResponseOrRawJson'
            application/json:
              schema:
                $ref: '#/components/schemas/SzOpenApiSpecResponseOrRawJson'
            default:
              schema:
                $ref: '#/components/schemas/SzOpenApiSpecResponseOrRawJson'
  /license:
    get:
      tags:
        - Admin
      summary: Get the license information.
      description: |
        This operation will obtain license information for the underlying
        native Senzing API.
      operationId: license
      parameters:
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzLicenseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzLicenseResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzLicenseResponse'
  /version:
    get:
      tags:
        - Admin
      summary: Get the full version information.
      description: |
        This operation will obtain the full version information for the server.
        Much of the same information is available in the `meta` segment of
        every JSON response.
      operationId: version
      parameters:
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzVersionResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzVersionResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzVersionResponse'
  /server-info:
    get:
      tags:
        - Admin
      summary: Get info regarding the server's state and supported features.
      description: |
        This operation will provides server information describing the options
        with which the server was started.  This can be used to determine if
        the admin operations are enabled or if only read operations may be
        invoked.  This also allows the client to know the maximum message size
        for Web Sockets communication.
      operationId: getServerInfo
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzServerInfoResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzServerInfoResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzServerInfoResponse'
  /attribute-types:
    get:
      tags:
        - Config
      summary: Get a list of configured attribute types.
      description: |
        This operation will provide a list of attribute types that are
        configured.  The client can filter the returned list of attribute types
        using various query parameters.
      operationId: getAttributeTypes
      parameters:
        - name: withInternal
          description: >-
            Set to `true` to include internal attribute types that are generally
            not mapped by users.  This defaults to false.
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: attributeClass
          description: >-
            If specified, this filters the list of returned attribute types
            to those of a specific attribute class.  If not specified then no
            filtering on attribute class is performed and all are returned.
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SzAttributeClass'
        - name: featureType
          description: >-
            If specified, this filters the list of returned attribute types
            to those belonging to a specific feature type.  If not specified
            then no filtering on feature type is performed and all are returned.
          in: query
          required: false
          schema:
            type: string
            default: null
          examples:
            NAME:
              value: NAME
            ADDRESS:
              value: ADDRESS
            PHONE:
              value: PHONE
            DOB:
              value: DOB
            EMAIL:
              value: EMAIL
            EMPLOYER:
              value: EMPLOYER
            DRLIC:
              value: DRLIC
            SSN:
              value: SSN
            NATIONAL_ID:
              value: NATIONAL_ID
            PASSPORT:
              value: PASSPORT
            CITIZENSHIP:
              value: CITIZENSHIP
            NATIONALITY:
              value: NATIONALITY
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzAttributeTypesResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzAttributeTypesResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzAttributeTypesResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /attribute-types/{attributeCode}:
    get:
      tags:
        - Config
      summary: Get the attribute type identified by the attribute code.
      description: |
        This operation will provide a description of a single attribute type for
        the specified attribute type code.
      operationId: getAttributeType
      parameters:
        - name: attributeCode
          description: >-
            The attribute code that uniquely identifies the attribute type.
          in: path
          required: true
          schema:
            type: string
          examples:
            NAME_ORG:
              value: NAME_ORG
            NAME_FULL:
              value: NAME_FULL
            NAME_LAST:
              value: NAME_LAST
            NAME_FIRST:
              value: NAME_FIRST
            NAME_MIDDLE:
              value: NAME_MIDDLE
            NAME_SUFFIX:
              value: NAME_SUFFIX
            ADDR_FULL:
              value: ADDR_FULL
            ADDR_LINE1:
              value: ADDR_LINE1
            ADDR_CITY:
              value: ADDR_CITY
            ADDR_STATE:
              value: ADDR_STATE
            ADDR_POSTAL_CODE:
              value: ADDR_POSTAL_CODE
            ADDR_COUNTRY:
              value: ADDR_COUNTRY
            PHONE_NUMBER:
              value: PHONE_NUMBER
            EMAIL_ADDRESS:
              value: EMAIL_ADDRESS
            DATE_OF_BIRTH:
              value: DATE_OF_BIRTH
            DRIVERS_LICENSE_NUMBER:
              value: DRIVERS_LICENSE_NUMBER
            SSN_NUMBER:
              value: SSN_NUMBER
            NATIONAL_ID_NUMBER:
              value: NATIONAL_ID_NUMBER
            PASSPORT_NUMBER:
              value: PASSPORT_NUMBER
            PASSPORT_COUNTRY:
              value: PASSPORT_COUNTRY
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzAttributeTypeResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzAttributeTypeResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzAttributeTypeResponse'
        '404':
          description: >-
            If the specified attribute code is not recognized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /data-sources:
    get:
      tags:
        - Config
      summary: Get a list of configured data sources.
      description: |
        This operation will provide a list of data source codes as well as a
        list of detailed descriptions of each data source.
      operationId: getDataSources
      parameters:
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzDataSourcesResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzDataSourcesResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzDataSourcesResponse'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags:
        - Config
      summary: >-
        Adds one or more new data sources to the current default configuration
        and reinitializes with the newly modified configuration.
      description: |
        Obtains the current default configuration, adds the specified data
        sources and sets the modified configuration as the new default
        configuration -- returning the set of all configured data sources.

        **NOTE:** This operation may not be allowed.  Some conditions that
        might cause this operation to be forbidden are:
          1. The server does not have administrative functions enabled.
          2. The server is running in "read-only" mode.
          3. The server is started with a file-based configuration specified
             by `G2CONFIGFILE` property in the initialziation parameters.
          4. The server is started with a specific configuration ID and
             therefore cannot modify the configuration and change to a new
             configuration.
      operationId: addDataSources
      parameters:
        - name: dataSource
          description: |
            The multi-valued query parameter where each value is a data source
            code identifying data sources to be created.  If a data source code
            is specified only via this parameter then the data source ID is
            generated by the API server -- which is usually fine.  If you want
            to specify the data source ID, then use the request body instead.
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          examples:
            singleDataSourceExample:
              summary: Specify a single data source
              value: [ PARTNERS ]
            multipleDataSourcesExample:
              summary: Specify multiple data sources
              value: [ PARTNERS, VIPS ]
        - $ref: '#/components/parameters/withRawQueryParam'
      requestBody:
        description: |
          The optional request body to describe the data sources to be created.
          This can be specified as an alternative to the `dataSource` parameter
          or in addition to it.  The content can be an array of string data
          source codes or `SzDataSource` objects.  It may also be a plain-text
          unquoted string that is simply a single data source code.
          See the various request body examples.
        required: false
        content:
          application/json; charset=UTF-8:
            schema:
              oneOf:
                - type: array
                  items:
                    $ref: '#/components/schemas/SzDataSourceDescriptor'
                - $ref: '#/components/schemas/SzDataSourceDescriptor'
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              noDataSources:
                $ref: '#/components/examples/noDataSources'
              singleSourceString:
                $ref: '#/components/examples/singleDataSourceString'
              singleSourceStringArray:
                $ref: '#/components/examples/singleDataSourceStringArray'
              multipleSourcesStringArray:
                $ref: '#/components/examples/multipleDataSourcesStringArray'
              singleSourceObjectNoId:
                $ref: '#/components/examples/singleDataSourceObjectNoId'
              singleSourceObjectArrayNoId:
                $ref: '#/components/examples/singleDataSourceObjectArrayNoId'
              singleSourceObjectWithId:
                $ref: '#/components/examples/singleDataSourceObjectWithId'
              singleSourceObjectArrayWithId:
                $ref: '#/components/examples/singleDataSourceObjectArrayWithId'
              multipleSourcesObjectArrayWithId:
                $ref: '#/components/examples/multipleDataSourcesObjectArrayWithId'
              multipleSourcesMixed:
                $ref: '#/components/examples/multipleDataSourcesMixed'
          application/json:
            schema:
              oneOf:
                - type: array
                  items:
                    $ref: '#/components/schemas/SzDataSourceDescriptor'
                - $ref: '#/components/schemas/SzDataSourceDescriptor'
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              noDataSources:
                $ref: '#/components/examples/noDataSources'
              singleSourceString:
                $ref: '#/components/examples/singleDataSourceString'
              singleSourceStringArray:
                $ref: '#/components/examples/singleDataSourceStringArray'
              multipleSourcesStringArray:
                $ref: '#/components/examples/multipleDataSourcesStringArray'
              singleSourceObjectNoId:
                $ref: '#/components/examples/singleDataSourceObjectNoId'
              singleSourceObjectArrayNoId:
                $ref: '#/components/examples/singleDataSourceObjectArrayNoId'
              singleSourceObjectWithId:
                $ref: '#/components/examples/singleDataSourceObjectWithId'
              singleSourceObjectArrayWithId:
                $ref: '#/components/examples/singleDataSourceObjectArrayWithId'
              multipleSourcesObjectArrayWithId:
                $ref: '#/components/examples/multipleDataSourcesObjectArrayWithId'
              multipleSourcesMixed:
                $ref: '#/components/examples/multipleDataSourcesMixed'
          text/plain; charset=UTF=8:
            schema:
              type: string
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              noDataSources:
                $ref: '#/components/examples/noDataSources'
              singleSourceUnquotedString:
                $ref: '#/components/examples/singleDataSourceUnquotedString'
          text/plain:
            schema:
              type: string
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              noDataSources:
                $ref: '#/components/examples/noDataSources'
              singleSourceUnquotedString:
                $ref: '#/components/examples/singleDataSourceUnquotedString'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzDataSourcesResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzDataSourcesResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzDataSourcesResponse'
        '403':
          description: >-
            If the server was started in read-only mode and so the operation
            is not permitted.  This is also returned if the server was started
            with a file-based configuration rather than a configuration stored
            in the database (i.e.: `G2CONFIGFILE` is specified in an INI file)
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /data-sources/{dataSourceCode}:
    get:
      tags:
        - Config
      summary: Gets the details on the specified data source.
      description: |
        This operation provides details on a specific data source identified
        by the data source code in the requested path.
      operationId: getDataSource
      parameters:
        - $ref: '#/components/parameters/dataSourceCodePathParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzDataSourceResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzDataSourceResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzDataSourceResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /configs/active:
    get:
      tags:
        - Config
      summary: >-
        Gets the current active configuration as raw JSON, no interpretation.
      description: |
        This operation returns the JSON configuration that is currently being
        used by the native Senzing API initialized by the running server.  No
        processing or interpretation is performed on the JSON.  This may differ
        from the registered "default configuration" which the server would
        use if no other configuration were provided.
      operationId: getActiveConfig
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzConfigResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzConfigResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzConfigResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /configs/template:
    get:
      tags:
        - Config
      summary: >-
        Gets the base template configuration as raw JSON, no interpretation.
        This is the initial configuration for a new repository.
      description: |
        This operation returns a template base JSON configuration that can be
        modified or customized by the caller.  The returned template is
        according to the underlying native Senzing API and may change between
        version upgrades to Senzing.  No processing or interpretation is
        performed on the JSON.  This will likely differ from the registered
        "default configuration" or currently "active configuration" being used
        by the running API server.
      operationId: getTemplateConfig
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzConfigResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzConfigResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzConfigResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /data-sources/{dataSourceCode}/records:
    post:
      tags:
        - Entity Data
      summary: >-
        Load a new record specified in a data source with either an
        auto-generated record ID or a `RECORD_ID` specified in the payload.
      description: |
        This operation loads a single record using the data source identified by
        the data source code in the request path.  The provided record in the
        request body is described in JSON using the
        [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification).
        The provided record may contain a `RECORD_ID` to identify it uniquely
        among other records in the same data source, but if it does not then a
        record ID will be automatically generated.  The record ID is returned
        as part of the response.

        **NOTE:** The `withInfo` parameter will return the entity resolution
        info pertaining to the load.  This can be used to update a search index
        or external data mart.   Additionally, Senzing API Server provides a
        means to have the "raw" entity resolution info (from the underlying
        native Senzing API) automatically sent to a messaging service such as
        those provided by Amazon SQS, Rabbit MQ or Kafka regardless of the
        `withInfo` query parameter value.
      operationId: addRecordWithReturnedRecordId
      parameters:
        - $ref: '#/components/parameters/dataSourceCodePathParam'
        - $ref: '#/components/parameters/loadIdQueryParam'
        - $ref: '#/components/parameters/withInfoQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      requestBody:
        description: >-
          The record data as JSON.  The format of the JSON is described
          by the [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification).
          The specified JSON may include or exclude the DATA_SOURCE field.
          It will be added if excluded.  If included, it must match the
          data source code in the path parameters.
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              type: object
              additionalProperties: {}
            examples:
              simpleFlatRecordExample:
                $ref: '#/components/examples/simpleFlatRecordExample'
              complexFlatRecordExample:
                $ref: '#/components/examples/complexFlatRecordExample'
              simpleHierarchicalRecordExample:
                $ref: '#/components/examples/simpleHierarchicalRecordExample'
              complexHierarchicalRecordExample:
                $ref: '#/components/examples/complexHierarchicalRecordExample'
          application/json:
            schema:
              type: object
              additionalProperties: {}
            examples:
              simpleFlatRecordExample:
                $ref: '#/components/examples/simpleFlatRecordExample'
              complexFlatRecordExample:
                $ref: '#/components/examples/complexFlatRecordExample'
              simpleHierarchicalRecordExample:
                $ref: '#/components/examples/simpleHierarchicalRecordExample'
              complexHierarchicalRecordExample:
                $ref: '#/components/examples/complexHierarchicalRecordExample'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzLoadRecordResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzLoadRecordResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzLoadRecordResponse'
        '400':
          description: >-
            If the specified data contains a DATA_SOURCE field that is not
            consistent with the dataSourceCode in the path of the request
            or if the specified content body is not formatted as JSON.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '403':
          description: >-
            If the server was started in read-only mode and so the operation
            is not permitted.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '404':
          description: >-
            If the specified data source code in the path is not recognized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /data-sources/{dataSourceCode}/records/{recordId}:
    get:
      tags:
        - Entity Data
      summary: Get an entity record by data source and record ID.
      description: |
        Gets details on a specific entity record identified by the data source
        code and record ID specified in the request path.
      operationId: getRecord
      parameters:
        - $ref: '#/components/parameters/dataSourceCodePathParam'
        - $ref: '#/components/parameters/recordIdPathParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successul response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzRecordResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzRecordResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzRecordResponse'
        '404':
          description: If data source or record ID are not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      tags:
        - Entity Data
      summary: >-
        Load a new record or replace a record in a data source with a
        specific record ID.
      description: |
        This operation loads a single record using the data source identified by
        the data source code in the request path.  The record will be identified
        uniquely within the data source by the record ID provided in the request
        path.  The provided record in the request body is described in JSON
        using the [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification).
        The provided JSON record may omit the `RECORD_ID`, but if it contains a
        `RECORD_ID` then it **must** match the record ID provided on the request
        path.  The record ID is returned as part of the response.

        **NOTE:** The `withInfo` parameter will return the entity resolution
        info pertaining to the load.  This can be used to update a search index
        or external data mart.   Additionally, Senzing API Server provides a
        means to have the "raw" entity resolution info (from the underlying
        native Senzing API) automatically sent to a messaging service such as
        those provided by Amazon SQS, Rabbit MQ or Kafka regardless of the
        `withInfo` query parameter value.
      operationId: addRecord
      parameters:
        - $ref: '#/components/parameters/dataSourceCodePathParam'
        - $ref: '#/components/parameters/recordIdPathParam'
        - $ref: '#/components/parameters/loadIdQueryParam'
        - $ref: '#/components/parameters/withInfoQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      requestBody:
        description: >-
          The record data as JSON.  The format of the JSON is described
          by the [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification).
          The specified JSON may include or exclude the DATA_SOURCE and
          RECORD_ID fields.  Any excluded field will be added to the JSON
          accordingly.  Any included field in the JSON, must match the
          respective path parameter for data source code or record ID.
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              type: object
              additionalProperties: {}
            examples:
              simpleFlatRecordExample:
                $ref: '#/components/examples/simpleFlatRecordExample'
              complexFlatRecordExample:
                $ref: '#/components/examples/complexFlatRecordExample'
              simpleHierarchicalRecordExample:
                $ref: '#/components/examples/simpleHierarchicalRecordExample'
              complexHierarchicalRecordExample:
                $ref: '#/components/examples/complexHierarchicalRecordExample'
          application/json:
            schema:
              type: object
              additionalProperties: {}
            examples:
              simpleFlatRecordExample:
                $ref: '#/components/examples/simpleFlatRecordExample'
              complexFlatRecordExample:
                $ref: '#/components/examples/complexFlatRecordExample'
              simpleHierarchicalRecordExample:
                $ref: '#/components/examples/simpleHierarchicalRecordExample'
              complexHierarchicalRecordExample:
                $ref: '#/components/examples/complexHierarchicalRecordExample'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzLoadRecordResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzLoadRecordResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzLoadRecordResponse'
        '400':
          description: >-
            If the specified data contains a DATA_SOURCE field that is not
            consistent with the dataSourceCode in the path of the request
            or if the specified content body is not formatted as JSON.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '403':
          description: >-
            If the server was started in read-only mode and so the operation
            is not permitted.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '404':
          description: >-
            If the specified data source code in the path is not recognized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Entity Data
      summary: Delete a record given its data source and record ID.
      description: |
        This operation deletes a single record identified by the data source
        code and record ID in the request path.

        **NOTE:** The `withInfo` parameter will return the entity resolution
        info pertaining to the delete.  This can be used to update a search
        index or external data mart.   Additionally, Senzing API Server provides
        a means to have the "raw" entity resolution info (from the underlying
        native Senzing API) automatically sent to a messaging service such as
        those provided by Amazon SQS, Rabbit MQ or Kafka regardless of the
        `withInfo` query parameter value.
      operationId: deleteRecord
      parameters:
        - $ref: '#/components/parameters/dataSourceCodePathParam'
        - $ref: '#/components/parameters/recordIdPathParam'
        - $ref: '#/components/parameters/loadIdQueryParam'
        - $ref: '#/components/parameters/withInfoQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: default response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzDeleteRecordResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzDeleteRecordResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzDeleteRecordResponse'
        '404':
          description: If data source is not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /data-sources/{dataSourceCode}/records/{recordId}/reevaluate:
    post:
      tags:
        - Entity Data
      summary: Reevaluate a record identified by a data source and record ID.
      description: |
        This operation reevaluates a single record identified by the data source
        code and record ID in the request path.

        **NOTE:** The `withInfo` parameter will return the entity resolution
        info pertaining to the reevaluation.  This can be used to update a
        search index or external data mart.   Additionally, Senzing API Server
        provides a means to have the "raw" entity resolution info (from the
        underlying native Senzing API) automatically sent to a messaging service
        such as those provided by Amazon SQS, Rabbit MQ or Kafka regardless of
        the `withInfo` query parameter value.
      operationId: reevaluateRecord
      parameters:
        - $ref: '#/components/parameters/dataSourceCodePathParam'
        - $ref: '#/components/parameters/recordIdPathParam'
        - $ref: '#/components/parameters/withInfoQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: default response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzReevaluateResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzReevaluateResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzReevaluateResponse'
        '404':
          description: If data source or record ID are not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /data-sources/{dataSourceCode}/records/{recordId}/entity:
    get:
      tags:
        - Entity Data
      summary: Get a resolved entity by data source and record ID.
      description: |
        Gets the details on a resolved entity that contains the record
        identified by the data source code and record ID in the specified
        request path.
      operationId: getEntityByRecordId
      parameters:
        - $ref: '#/components/parameters/dataSourceCodePathParam'
        - $ref: '#/components/parameters/recordIdPathParam'
        - $ref: '#/components/parameters/detailLevelQueryParam'
        - $ref: '#/components/parameters/featureModeQueryParam'
        - $ref: '#/components/parameters/withFeatureStatsQueryParam'
        - $ref: '#/components/parameters/withInternalFeaturesQueryParam'
        - $ref: '#/components/parameters/forceMinimalQueryParam'
        - $ref: '#/components/parameters/withRelatedQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: default response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzEntityResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzEntityResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzEntityResponse'
        '404':
          description: If data source or record ID are not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /data-sources/{dataSourceCode}/records/{recordId}/entity/why:
    get:
      tags:
        - Entity Data
      summary: >-
        Returns an analysis of why the entity for the record with the
        respective data source code and record ID resolved.
      description: |
        This operation provides an anlysis of why the records in an entity
        resolved.  The subject entity is the one containing the record
        identified by the data source code and record ID in the request path.
      operationId: whyEntityByRecordID
      parameters:
        - $ref: '#/components/parameters/dataSourceCodePathParam'
        - $ref: '#/components/parameters/recordIdPathParam'
        - $ref: '#/components/parameters/withRelationshipsQueryParam'
        - $ref: '#/components/parameters/whyWithFeatureStatsQueryParam'
        - $ref: '#/components/parameters/whyWithInternalFeaturesQueryParam'
        - $ref: '#/components/parameters/detailLevelQueryParam'
        - $ref: '#/components/parameters/featureModeQueryParam'
        - $ref: '#/components/parameters/forceMinimalQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successul response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzWhyEntityResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzWhyEntityResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzWhyEntityResponse'
        '404':
          description: If data source or record ID are not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /data-sources/{dataSourceCode}/records/{recordId}/entity/how:
    get:
      tags:
        - Entity Data
      summary: >-
        Returns an analysis of how the entity for the record with the
        respective data source code and record ID resolved.
      description: |
        This operation provides an anlysis of how the records in an entity
        resolved.  The subject entity is the one containing the record
        identified by the data source code and record ID in the request path.
      operationId: howEntityByRecordID
      parameters:
        - $ref: '#/components/parameters/dataSourceCodePathParam'
        - $ref: '#/components/parameters/recordIdPathParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successul response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzHowEntityResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzHowEntityResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzHowEntityResponse'
        '404':
          description: If data source or record ID are not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /entities:
    get:
      tags:
        - Entity Data
      summary: >-
        Search for entities that would resolve to or relate to the provided
        entity features.
      description: |
        This operation finds all entities that would resolve or relate to the
        search candidate features specified by the `attr` and/or `attrs` query
        parameters.  The search candidate features are treated as if they
        belonged to an inbound record being loaded, thus the attribute names are
        given by the [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification).
        If including the search candidate features as query parameters presents
        privacy concerns due to sensitivity of the data, they can alternately
        be sent in the request body using the `POST /search-entities` endpoint.

        **NOTE:** This operation differs from a keyword search in that it uses
        deterministic entity resolution rules to determine the result set.  This
        means that features that are considered "generic" (i.e.: overly common)
        will be ignored just as they are during entity resolution and will not
        yield search results.  For example, searching on a gender by itself will
        return no results rather than half of all entities.  Similarly, a phone
        number such as `555-1212` may yield no results.
      operationId: searchEntitiesByGet
      parameters:
        - name: attrs
          description: |
            The JSON record describing the entity attributes in the same
            format as how an entity record is loaded.  The specified
            attributes are treated as a hypothetical record being loaded,
            and the result is anything that would have matched or related
            to it.  Here are some examples of encoding this parameter:

            - **JavaScript Example**
              ```javascript
                var searchCriteria = {
                  "NAME_FULL": "Joe Schmoe",
                  "DATE_OF_BIRTH": "03-SEP-1987"
                };
                var searchAttrs = JSON.stringify(searchCriteria);
                var urlPath = "/entities?attrs=" + encodeURIComponent(searchAttrs);
              ```

            - **Java Example**
              ```java
                JsonObjectBuilder builder = Json.createObjectBuilder();
                builder.add("NAME_FULL", "Joe Schmoe");
                builder.add("DATE_OF_BIRTH", "03-SEP-1987");
                JsonObject searchCriteria = builder.build();

                String searchAttrs = searchCriteria.toString();
                String encodedAttrs = URLEncoder.encode(searchAttrs, "UTF-8");
                String urlPath = "/entities?attrs=" + encodedAttrs;
              ```

            In both of the above examples the `urlPath` variable is set to:
            ```json

            /entities?attrs=%7B%22NAME_FULL%22%3A%22Joe%20Schmoe%22%2C%22DATE_OF_BIRTH%22%3A%2203-SEP-1987%22%7D

            ```
          in: query
          required: false
          schema:
            type: string
          examples:
            notSpecifiedExample:
              summary: Not specified
              value:
            ssnExample:
              $ref: '#/components/examples/ssnSearchExample'
            nameAndBirthDateExample:
              $ref: '#/components/examples/nameAndBirthDateSearchExample'
            nameAndAddressExample:
              $ref: '#/components/examples/nameAndAddressSearchExample'
        - name: attr
          description: >-
            Either the `attrs` or `attr` parameter is required, **however** if
            the `attrs` parameter is provided it takes precedence and the `attr`
            parameter will be ignored.  If you are using this API programmatically
            then you should typically use the `attrs` parameter.  But when
            manually constructing a URL in the browser address bar, in a
            command-line tool like `curl` or in a REST client browser extension
            for debugging or testing purposes, encoding that JSON value can be
            unwieldy.  This parameter (which is multi-valued) lets you specify
            colon-delimited strings that are prefixed with the JSON property name
            and suffixed with the value.  For example, `NAME_FIRST:Joe` (url
            encoded of course).  This side-steps the need to URL-encode the
            structural JSON characters and usually means you need only URL-encode
            basic characters like colons (`%3A`) and spaces (`%20`).  The JSON
            constructed using this parameter is obviously flat.  If you want to
            group properties together by their "usage type" (e.g.: `NAME_TYPE`,
            `PHONE_TYPE` or `ADDRESS_TYPE`) then you would **also** prefix with
            the type (e.g.: `HOME_PHONE_NUMBER:702-555-1212`).
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          examples:
            notSpecifiedExample:
              summary: Not specified
              value:
            basicExample:
              summary: Basic name and date of birth example
              value: [ "NAME_FULL:Joe Schmoe", "DATE_OF_BIRTH:03-SEP-1987"]
            basicArrayExample:
              summary: Multiple phone numbers without usage types
              value: [ "PHONE_NUMBER:702-555-1212", "PHONE_NUMBER:702-555-1414" ]
            basicUsageTypeExample:
              summary: Multiple phone numbers with usage types
              value: [ "HOME_PHONE_NUMBER:702-555-1212", "WORK_PHONE_NUMBER:702-555-1414" ]
            complexUsageTypeExample:
              summary: Multiple address search with usage types for grouping
              value: [
                "HOME_ADDR_LINE1:101 Main Street",
                "HOME_ADDR_CITY:Los Angeles",
                "HOME_ADDR_STATE:CA",
                "WORK_ADDR_LINE1:105 Colorado Blvd",
                "WORK_ADDR_CITY:Pasadena",
                "WORK_ADDR_STATE:CA"
              ]
        - $ref: '#/components/parameters/includeOnlyQueryParam'
        - $ref: '#/components/parameters/detailLevelQueryParam'
        - $ref: '#/components/parameters/featureModeQueryParam'
        - $ref: '#/components/parameters/withFeatureStatsQueryParam'
        - $ref: '#/components/parameters/withInternalFeaturesQueryParam'
        - $ref: '#/components/parameters/forceMinimalQueryParam'
        - $ref: '#/components/parameters/withRelationshipsQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzAttributeSearchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzAttributeSearchResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzAttributeSearchResponse'
        '400':
          description: >-
            If the specified attrs parameter is missing or is not formatted
            properly.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /search-entities:
    post:
      tags:
        - Entity Data
      summary: >-
        Search for entities that would match or relate to the provided
        entity features.  This is similar to `GET /entities` except it requires
        the caller to specify the search criteria as JSON in the request body.
      description: |
        This operation finds all entities that would resolve or relate to the
        search candidate features specified in JSON request body.  The search
        candidate features are treated as if they belonged to an inbound record
        being loaded.  The JSON format of the request body is defined by the
        [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification).
        This operation is similar to the `GET /entities` endpoint in function
        except that it provides a means to avoid specifying potentially
        sensitive data in query parameters, but instead in the request body.

        **NOTE:** This operation differs from a keyword search in that it uses
        deterministic entity resolution rules to determine the result set.  This
        means that features that are considered "generic" (i.e.: overly common)
        will be ignored just as they are during entity resolution and will not
        yield search results.  For example, searching on a gender by itself will
        return no results rather than half of all entities.  Similarly, a phone
        number such as `555-1212` may yield no results.
      operationId: searchEntitiesByPost
      parameters:
        - $ref: '#/components/parameters/includeOnlyQueryParam'
        - $ref: '#/components/parameters/detailLevelQueryParam'
        - $ref: '#/components/parameters/featureModeQueryParam'
        - $ref: '#/components/parameters/withFeatureStatsQueryParam'
        - $ref: '#/components/parameters/withInternalFeaturesQueryParam'
        - $ref: '#/components/parameters/forceMinimalQueryParam'
        - $ref: '#/components/parameters/withRelationshipsQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      requestBody:
        description: >-
          The JSON record describing the entity attributes in the same format as
          how an entity record is loaded The format of the JSON is described by
          the [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification).
          The specified attributes are treated as a hypothetical record being
          loaded, and the result is anything that would have matched or related
          to it.
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              type: object
              additionalProperties: {}
            examples:
              ssnExample:
                $ref: '#/components/examples/ssnSearchExample'
              nameAndBirthDateExample:
                $ref: '#/components/examples/nameAndBirthDateSearchExample'
              nameAndAddressExample:
                $ref: '#/components/examples/nameAndAddressSearchExample'
          application/json:
            schema:
              type: object
              additionalProperties: {}
            examples:
              ssnExample:
                $ref: '#/components/examples/ssnSearchExample'
              nameAndBirthDateExample:
                $ref: '#/components/examples/nameAndBirthDateSearchExample'
              nameAndAddressExample:
                $ref: '#/components/examples/nameAndAddressSearchExample'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzAttributeSearchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzAttributeSearchResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzAttributeSearchResponse'
        '400':
          description: >-
            If the specified attrs parameter is missing or is not formatted
            properly.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /entities/{entityId}:
    get:
      tags:
        - Entity Data
      summary: Get a resolved entity by entity ID.
      description: |
        Gets the details on a resolved entity that is identified by the entity
        ID specified in the request path.

        **NOTE:** Bear in mind that entity ID's are transient and may be
        recycled or repurposed as new records are loaded and entities resolve,
        unresolve and re-resolve.  An alternative way to identify an entity is
        by one of its constituent records using
        `GET /data-sources/{dataSourceCode}/records/{recordId}/entity`.
      operationId: getEntityByEntityId
      parameters:
      - name: entityId
        description: >-
          The unique numeric ID that identifies that entity being requested.
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/detailLevelQueryParam'
      - $ref: '#/components/parameters/featureModeQueryParam'
      - $ref: '#/components/parameters/withFeatureStatsQueryParam'
      - $ref: '#/components/parameters/withInternalFeaturesQueryParam'
      - $ref: '#/components/parameters/forceMinimalQueryParam'
      - $ref: '#/components/parameters/withRelatedQueryParam'
      - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzEntityResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzEntityResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzEntityResponse'
        '404':
          description: If the entity ID is not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /entities/{entityId}/why:
    get:
      tags:
        - Entity Data
      summary: >-
        Returns an analysis of why the entity for the respective
        entity ID resolved.
      description: |
        This operation provides an anlysis of why the records in an entity
        resolved.  The subject entity is identified by the entity ID in the
        request path.

        **NOTE:** Bear in mind that entity ID's are transient and may be
        recycled or repurposed as new records are loaded and entities resolve,
        unresolve and re-resolve.  An alternative way to identify an entity is
        by one of its constituent records using
        `GET /data-sources/{dataSourceCode}/records/{recordId}/entity/why`.
      operationId: whyEntityByEntityID
      parameters:
        - name: entityId
          description: >-
            The unique numeric ID that identifies that entity being requested.
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - $ref: '#/components/parameters/withRelationshipsQueryParam'
        - $ref: '#/components/parameters/whyWithFeatureStatsQueryParam'
        - $ref: '#/components/parameters/whyWithInternalFeaturesQueryParam'
        - $ref: '#/components/parameters/detailLevelQueryParam'
        - $ref: '#/components/parameters/featureModeQueryParam'
        - $ref: '#/components/parameters/forceMinimalQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successul response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzWhyEntityResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzWhyEntityResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzWhyEntityResponse'
        '404':
          description: If entity ID is not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /entities/{entityId}/how:
    get:
      tags:
        - Entity Data
      summary: >-
        Returns an analysis of how the entity for the respective
        entity ID resolved.
      description: |
        This operation provides an anlysis of how the records in an entity
        resolved.  The subject entity is identified by the entity ID in the
        request path.

        **NOTE:** Bear in mind that entity ID's are transient and may be
        recycled or repurposed as new records are loaded and entities resolve,
        unresolve and re-resolve.  An alternative way to identify an entity is
        by one of its constituent records using
        `GET /data-sources/{dataSourceCode}/records/{recordId}/entity/how`.
      operationId: howEntityByEntityID
      parameters:
        - name: entityId
          description: >-
            The unique numeric ID that identifies the entity for which to
            perform the analysis.
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successul response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzHowEntityResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzHowEntityResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzHowEntityResponse'
        '404':
          description: If entity ID is not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /why/records:
    get:
      tags:
        - Entity Data
      summary: >-
        Returns an analysis of why the records identified by the data source
        and record ID's in the query parameters resolved or did not resolve.
      description: |
        This operation provides an anlysis of two records identified by data
        source code and record ID in respective qeury parameters resolved or
        did not resolve.
      operationId: whyRecords
      parameters:
        - name: dataSource1
          description: >-
            The data source for the first record.
          required: true
          in: query
          schema:
            type: string
        - name: recordId1
          description: >-
            The record ID for the first record.
          required: true
          in: query
          schema:
            type: string
        - name: dataSource2
          description: >-
            The data source for the second record.
          required: true
          in: query
          schema:
            type: string
        - name: recordId2
          description: >-
            The data source for the second record.
          required: true
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/withRelationshipsQueryParam'
        - $ref: '#/components/parameters/whyWithFeatureStatsQueryParam'
        - $ref: '#/components/parameters/whyWithInternalFeaturesQueryParam'
        - $ref: '#/components/parameters/detailLevelQueryParam'
        - $ref: '#/components/parameters/featureModeQueryParam'
        - $ref: '#/components/parameters/forceMinimalQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successul response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzWhyRecordsResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzWhyRecordsResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzWhyRecordsResponse'
        '404':
          description: If data source or record ID are not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /why/entities:
    get:
      tags:
        - Entity Data
      summary: >-
        Returns an analysis of why the two entities related, did not relate, or
        did not resolve.
      description: |
        This operation provides an anlysis of why two entities related, did not
        relate or did not resolve.  The entities are identified either by
        entity ID's or by data source code and record ID pairs for constituent
        records of those entities.

        **NOTE:** If the first entity is identified by entity ID then the second
        must also be identified an entity ID.  Similarly, if the first entity is
        identified by data source code and record ID then the second must also
        be identified by data source code and record ID.

        **ALSO NOTE:** Bear in mind that entity ID's are transient and may be
        recycled or repurposed as new records are loaded and entities resolve,
        unresolve and re-resolve.
      operationId: whyEntities
      parameters:
        - name: entity1
          description: >-
            The `SzEntityIdentifier` for the first entity as an entity ID or an
            encoded `SzRecordId` for the constituent record.  Whatever format is
            used for the "entity1" parameter must match the format of the
            "entity2" parameter.  NOTE: An encoded `SzRecordId` can EITHER be
            encoded as JSON or as a delimited string where the first character
            is the delimiter and the remainder is parsed as a data source prefix
            (up to the second occurrence of the delimiter) and a record ID
            suffix (all characters after the second occurrence of the
            delimiter).  For example: `{"src":"PEOPLE","id":"12345ABC"}` or
            `:PEOPLE:12345ABC`.
          required: true
          in: query
          schema:
            type: string
        - name: entity2
          description: >-
            The `SzEntityIdentifier` for the second entity as an entity ID or an
            encoded `SzRecordId` for the constituent record.  Whatever format is
            used for the "entity2" parameter must match the format of the
            "entity1" parameter.  NOTE: An encoded `SzRecordId` can EITHER be
            encoded as JSON or as a delimited string where the first character
            is the delimiter and the remainder is parsed as a data source prefix
            (up to the second occurrence of the delimiter) and a record ID
            suffix (all characters after the second occurrence of the
            delimiter).  For example: `{"src":"PEOPLE","id":"12345ABC"}` or
            `:PEOPLE:12345ABC`.
          required: true
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/withRelationshipsQueryParam'
        - $ref: '#/components/parameters/whyWithFeatureStatsQueryParam'
        - $ref: '#/components/parameters/whyWithInternalFeaturesQueryParam'
        - $ref: '#/components/parameters/detailLevelQueryParam'
        - $ref: '#/components/parameters/featureModeQueryParam'
        - $ref: '#/components/parameters/forceMinimalQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successul response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzWhyEntitiesResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzWhyEntitiesResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzWhyEntitiesResponse'
        '404':
          description: If data source or record ID are not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /reevaluate-entity:
    post:
      tags:
        - Entity Data
      summary: Reevaluate an entity identified by its entity ID.
      description: |
        Reevaluates an entity identified by the entity ID specified via the
        `entityId` query parameter.

        **NOTE:** The `withInfo` parameter will return the entity resolution
        info pertaining to the reevaluation.  This can be used to update a
        search index or external data mart.   Additionally, Senzing API Server
        provides a means to have the "raw" entity resolution info (from the
        underlying native Senzing API) automatically sent to a messaging service
        such as those provided by Amazon SQS, Rabbit MQ or Kafka regardless of
        the `withInfo` query parameter value.

        **ALSO NOTE:** Bear in mind that entity ID's are transient and may be
        recycled or repurposed as new records are loaded and entities resolve,
        unresolve and re-resolve.
      operationId: reevaluateEntity
      parameters:
        - name: entityId
          in: query
          required: true
          description: >-
            The entity ID of the entity to reevaluate.
          schema:
            type: integer
            format: int64
        - $ref: '#/components/parameters/withInfoQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: default response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzReevaluateResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzReevaluateResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzReevaluateResponse'
        '404':
          description: If data source or record ID are not found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /virtual-entities:
    get:
      tags:
        - Entity Data
      summary: >-
        Builds a virtual entity by simulating the resolution of the records
        identified by the specified record ID parameters.
      description: |
        This operation simulates the resolution of the one or more specified
        records into a single entity and returns the simulated "virtual"
        entity.  The subject records are identified by data source code and
        record ID pairs.
      operationId: getVirtualEntityByRecordIds
      parameters:
        - name: r
          description: >-
            Repeating query parameter containing encoded `SzRecordId`
            definitions that identify records to be inclued in the resultant
            virtual entity.  At least one record identifier is required.  If
            both this parameter and the `records` parameter are specified then
            the values are merged.
            **NOTE**: An encoded `SzRecordId` can EITHER be encoded as JSON or
            as a delimited string where the first character is the delimiter and
            the remainer is parsed as a data source prefix (up to the second
            occurrence of the delimiter) and a record ID suffix (all characters
            after the second occurrence of the delimiter).  For example:
            `{"src":"PEOPLE","id":"12345ABC"}` or `:PEOPLE:12345ABC`.
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SzRecordIdentifier'
          examples:
            noRecordsExample:
              $ref: '#/components/examples/noRecordsExample'
            singleByDelimitedRecordIdExample:
              $ref: '#/components/examples/singleRecordByDelimitedRecordIdExample'
            multipleByDelimitedRecordIdExample:
              $ref: '#/components/examples/multipleRecordsByDelimitedRecordIdExample'
            singleByJsonRecordIdExample:
              $ref: '#/components/examples/singleRecordByJsonRecordIdExample'
            multipleByJsonRecordIdExample:
              $ref: '#/components/examples/multipleRecordsByJsonRecordIdExample'
            multipleByMixedRecordIdExample:
              $ref: '#/components/examples/multipleRecordsByMixedRecordIdExample'
        - name: records
          description: >-
            Singular query parameter containing multiple encoded `SzRecordId`
            definitions that identify records to be inclued in the resultant
            virtual entity as a JSON array or a simple comma-separated array.
            At least one record identifier is required.  If both this parameter
            and the `r` parameter are specified then the values are merged.
            **NOTE**: An encoded `SzRecordId` can EITHER be encoded as JSON or
            as a delimited string where the first character is the delimiter and
            the remainer is parsed as a data source prefix (up to the second
            occurrence of the delimiter) and a record ID suffix (all characters
            after the second occurrence of the delimiter).  For example:
            `{"src":"PEOPLE","id":"12345ABC"}` or `:PEOPLE:12345ABC`.
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SzRecordIdentifiers'
          examples:
            noRecordsExample:
              $ref: '#/components/examples/noRecordsArrayExample'
            singleByDelimitedRecordIdExample:
              $ref: '#/components/examples/singleRecordByDelimitedRecordIdArrayExample'
            multipleByDelimitedRecordIdExample:
              $ref: '#/components/examples/multipleRecordsByDelimitedRecordIdArrayExample'
            singleByJsonRecordIdExample:
              $ref: '#/components/examples/singleRecordByJsonRecordIdArrayExample'
            multipleByJsonRecordIdExample:
              $ref: '#/components/examples/multipleRecordsByJsonRecordIdArrayExample'
            multipleByMixedRecordIdExample:
              $ref: '#/components/examples/multipleRecordsByMixedRecordIdArrayExample'
        - $ref: '#/components/parameters/detailLevelQueryParam'
        - $ref: '#/components/parameters/featureModeQueryParam'
        - $ref: '#/components/parameters/withFeatureStatsQueryParam'
        - $ref: '#/components/parameters/withInternalFeaturesQueryParam'
        - $ref: '#/components/parameters/forceMinimalQueryParam'
        - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzVirtualEntityResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzVirtualEntityResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzVirtualEntityResponse'
        '400':
          description: >-
            If no record identifies are specified via the query parameters.
            Also, if any of the identified records cannot be found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /entity-paths:
    get:
      tags:
        - Entity Graph
      summary: >-
        Finds a path between two entities identified by entity ID or by
        data sources and record IDs of constituent records.
      description: |
        This operation finds the path between two entities and returns a
        description of that entity path (if any) or a response indicating that
        there is no path between the entities.  The subject entities are either
        identfieid by entity ID or by data source code and record ID pairs for
        constituent records of those entities.

        **NOTE:** If the first entity is identified by entity ID then the second
        must also be identified an entity ID.  Similarly, if the first entity is
        identified by data source code and record ID then the second must also
        be identified by data source code and record ID.

        **ALSO NOTE:** Bear in mind that entity ID's are transient and may be
        recycled or repurposed as new records are loaded and entities resolve,
        unresolve and re-resolve.
      operationId: findEntityPath
      parameters:
      - name: from
        description: >-
          The `SzEntityIdentifier` for the first entity for the path either as
          an entity ID or an encoded `SzRecordId` for the constituent record.
          Whatever format is used for the "from" parameter must match the format
          of the "to" parameter.  NOTE: An encoded `SzRecordId` can EITHER
          be encoded as JSON or as a delimited string where the first character
          is the delimiter and the remainder is parsed as a data source prefix
          (up to the second occurrence of the delimiter) and a record ID suffix
          (all characters after the second occurrence of the delimiter).  For
          example: `{"src":"PEOPLE","id":"12345ABC"}` or `:PEOPLE:12345ABC`.
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/SzEntityIdentifier'
        examples:
          entityIdExample:
            summary: A numeric entity ID
            value: 1234567
          encodedRecordIdExample:
            summary: A record ID encoded as a deliminted string.
            value: ":CUSTOMERS:ABC123"
          jsonRecordIdExample:
            summary: A record ID encoded as JSON
            value: {"src":"CUSTOMERS","id":"ABC123"}
      - name: to
        description: >-
          The `SzEntityIdentifier` for the last entity for the path either as
          an entity ID or a encoded `SzRecordId` for the constituent record.
          Whatever format is used for the "to" parameter must match the
          format of the "from" parameter.  NOTE: An encoded `SzRecordId` can
          EITHER be encoded as JSON or as a delimited string where the first
          character is the delimiter and the remainder is parsed as a data
          source prefix (up to the second occurrence of the delimiter) and a
          record ID suffix (all characters after the second occurrence of the
          delimiter).  For example: `{"src":"PEOPLE","id":"12345ABC"}` or
          `:PEOPLE:12345ABC`.
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/SzEntityIdentifier'
        examples:
          entityIdExample:
            summary: A numeric entity ID
            value: 7654321
          encodedRecordIdExample:
            summary: A record ID encoded as a deliminted string.
            value: ":EMPLOYEES:DEF456"
          jsonRecordIdExample:
            summary: A record ID encoded as JSON
            value: {"src":"EMPLOYEES","id":"DEF456"}
      - name: maxDegrees
        description: >-
            The maximum number of degrees to look for a path from the first
            entity to the last entity.  This defaults to `3` if not specified.
            If specified, the value must be greater-than zero (0) since a path
            cannot exist at zero degrees of separation.
        in: query
        required: false
        schema:
          type: integer
          format: int8
          minimum: 1
          default: 3
      - name: x
        description: >-
          Repeating query parameter containing `SzEntityIdentifier` definitions
          that identify entities to be avoided or forbidden from the path
          (depending on the forbidAvoided parameter).  The entity identifiers
          are either all 64-bit long integers representing entity IDs or they
          are all encoded SzRecordId instances identifying records that are
          part of the resolved entities to exclude.  If this parameter is not
          provided, then the default is to NOT exclude any entities.  If both
          this parameter and the `avoidEntities` parameter are specified then
          the values are merged.  NOTE: An encoded `SzRecordId` can EITHER be
          encoded as JSON or as a delimited string where the first character is
          the delimiter and the remainder is parsed as a data source prefix (up
          to the second occurrence of the delimiter) and a record ID suffix (all
          characters after the second occurrence of the delimiter).  For
          example: `{"src":"PEOPLE","id":"12345ABC"}` or `:PEOPLE:12345ABC`.
        in: query
        required: false
        explode: true
        style: form
        schema:
          type: array
          items:
            $ref: '#/components/schemas/SzEntityIdentifier'
        examples:
          avoidNoEntitiesExample:
            $ref: '#/components/examples/noEntitiesExample'
          avoidSingleByEntityIdExample:
            $ref: '#/components/examples/singleEntityByEntityIdExample'
          avoidMultipleByEntityIdExample:
            $ref: '#/components/examples/multipleEntitiesByEntityIdExample'
          avoidSingleByDelimitedRecordIdExample:
            $ref: '#/components/examples/singleEntityByDelimitedRecordIdExample'
          avoidMultipleByDelimitedRecordIdExample:
            $ref: '#/components/examples/multipleEntitiesByDelimitedRecordIdExample'
          avoidSingleByJsonRecordIdExample:
            $ref: '#/components/examples/singleEntityByJsonRecordIdExample'
          avoidMultipleByJsonRecordIdExample:
            $ref: '#/components/examples/multipleEntitiesByJsonRecordIdExample'
          avoidMultipleByMixedRecordIdExample:
            $ref: '#/components/examples/multipleEntitiesByMixedRecordIdExample'
      - name: avoidEntities
        description: >-
          Single query parameter containing multiple `SzEntityIdentifier`
          definitions as a JSON array or a simple comma-separated array that
          identify entities to be avoided or forbidden from the path
          (depending on the forbidAvoided parameter).  The entity identifiers
          are either all 64-bit long integers representing entity IDs or they
          are all encoded `SzRecordId` instances identifying records that are
          part of the resolved entities to exclude.  At least one entity
          identifier is required.  If both this parameter and one or more `x`
          parameters are specified then the values are merged.  NOTE: An
          encoded `SzRecordId` can EITHER be encoded as JSON or as a delimited
          string where the first character is the delimiter and the remainder
          is parsed as a data source prefix (up to the second occurrence of the
          delimiter) and a record ID suffix (all characters after the second
          occurrence of the delimiter).  For example:
          `{"src":"PEOPLE","id":"12345ABC"}` or `:PEOPLE:12345ABC`.
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SzEntityIdentifiers'
        examples:
          avoidNoEntitiesArrayExample:
            $ref: '#/components/examples/noEntitiesArrayExample'
          avoidSingleByEntityIdArrayExample:
            $ref: '#/components/examples/singleEntityByEntityIdArrayExample'
          avoidMultipleByEntityIdArrayExample:
            $ref: '#/components/examples/multipleEntitiesByEntityIdArrayExample'
          avoidSingleByDelimitedRecordIdArrayExample:
            $ref: '#/components/examples/singleEntityByDelimitedRecordIdArrayExample'
          avoidMultipleByDelimitedRecordIdArrayExample:
            $ref: '#/components/examples/multipleEntitiesByDelimitedRecordIdArrayExample'
          avoidSingleByJsonRecordIdArrayExample:
            $ref: '#/components/examples/singleEntityByJsonRecordIdArrayExample'
          avoidMultipleByJsonRecordIdArrayExample:
            $ref: '#/components/examples/multipleEntitiesByJsonRecordIdArrayExample'
          avoidMultipleByMixedRecordIdArrayExample:
            $ref: '#/components/examples/multipleEntitiesByMixedRecordIdArrayExample'
      - name: forbidAvoided
        description: >-
          If the avoidEntities parameter is provided then this flag is used to
          control whether or not to forbid the avoided entities rather than
          include them in the path as a "last resort".
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: s
        description: >-
          The multi-valued query parameter where each value is a data source
          code identifying data sources for which one must be included in the
          entities for the path.  If not provided, then the default is to NOT
          require any specific data sources.
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
        examples:
          requireNoDataSourcesExample:
            summary: Require no data sources
            value: []
          requireSingleDataSourceExample:
            summary: Require a single data source
            value: [ VIPS ]
          requireMultipleDataSourcesExample:
            summary: Require multiple data sources
            value: [ VIPS, PARTNERS ]
      - $ref: '#/components/parameters/detailLevelQueryParam'
      - $ref: '#/components/parameters/featureModeQueryParam'
      - $ref: '#/components/parameters/withFeatureStatsQueryParam'
      - $ref: '#/components/parameters/withInternalFeaturesQueryParam'
      - $ref: '#/components/parameters/forceMinimalQueryParam'
      - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzEntityPathResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzEntityPathResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzEntityPathResponse'
        '400':
          description: >-
            If the 'from' or 'to' parameters are missing or if any of the
            parameters are not formatted as expected.  Also, if any of the
            identified entities or records cannot be found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /entity-networks:
    get:
      tags:
        - Entity Graph
      summary: >-
        Finds the entity network around one or more entities.
      description: |
        This operation finds the entity network around one or more entities.
        This attempts to find paths between the specified entities.  If no
        paths exist, then island networks are returned with each island network
        containing up to a specified number of related entities.  The entities
        are identified by their entity IDs or by data source code and record ID
        pairs for constituent records of those entities.

        **NOTE:** If the first entity is identified by entity ID then the
        subsequent entities must also be identified entity ID.  Similarly, if
        the first entity is identified by the data source code and record ID
        of a consistuent record then the subsequent entities must also be
        identified by the data source code and record ID of constituent records.

        **ALSO NOTE:** Bear in mind that entity ID's are transient and may be
        recycled or repurposed as new records are loaded and entities resolve,
        unresolve and re-resolve.
      operationId: findEntityNetwork
      parameters:
      - name: e
        description: >-
          Repeating query parameter containing `SzEntityIdentifier` definitions
          that identify entities to be included in the entity network.  The
          entity identifiers are either all 64-bit long integers representing
          entity IDs or they are all encoded `SzRecordId` instances identifying
          records that are part of the resolved entities to avoid.  At least
          one entity identifier is required.  If both this parameter and the
          `entities` parameter are specified then the values are merged.
          **NOTE**: An encoded `SzRecordId` can EITHER be encoded as JSON or as
          a delimited string where the first character is the delimiter and the
          remainder is parsed as a data source prefix (up to the second
          occurrence of the delimiter) and a record ID suffix (all characters
          after the second occurrence of the delimiter).  For example:
          `{"src":"PEOPLE","id":"12345ABC"}` or `:PEOPLE:12345ABC`.
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/SzEntityIdentifier'
        examples:
          noEntitiesExample:
            $ref: '#/components/examples/noEntitiesExample'
          singleByEntityIdExample:
            $ref: '#/components/examples/singleEntityByEntityIdExample'
          multipleByEntityIdExample:
            $ref: '#/components/examples/multipleEntitiesByEntityIdExample'
          singleByDelimitedRecordIdExample:
            $ref: '#/components/examples/singleEntityByDelimitedRecordIdExample'
          multipleByDelimitedRecordIdExample:
            $ref: '#/components/examples/multipleEntitiesByDelimitedRecordIdExample'
          singleByJsonRecordIdExample:
            $ref: '#/components/examples/singleEntityByJsonRecordIdExample'
          multipleByJsonRecordIdExample:
            $ref: '#/components/examples/multipleEntitiesByJsonRecordIdExample'
          multipleByMixedRecordIdExample:
            $ref: '#/components/examples/multipleEntitiesByMixedRecordIdExample'
      - name: entities
        description: >-
          Single query parameter containing multiple SzEntityIdentifier
          definitions that identify entities to be included in the entity
          network as a JSON array or a simple comma-separated array.  The
          entity identifiers are either all 64-bit long integers representing
          entity IDs or they are all encoded `SzRecordId` instances identifying
          records that are part of the resolved entities to avoid.  At least
          one entity identifier is required.  If both this parameter and one
          or more `e` parameters are specified then the values are merged.
          NOTE: An encoded `SzRecordId` can EITHER be encoded as JSON or as a
          delimited string where the first character is the delimiter and the
          remainder is parsed as a data source prefix (up to the second
          occurrence of the delimiter) and a record ID suffix (all characters
          after the second occurrence of the delimiter).  For example:
          `{"src":"PEOPLE","id":"12345ABC"}` or `:PEOPLE:12345ABC`.
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SzEntityIdentifiers'
        examples:
          noEntitiesArrayExample:
            $ref: '#/components/examples/noEntitiesArrayExample'
          singleByEntityIdArrayExample:
            $ref: '#/components/examples/singleEntityByEntityIdArrayExample'
          multipleByEntityIdArrayExample:
            $ref: '#/components/examples/multipleEntitiesByEntityIdArrayExample'
          singleByDelimitedRecordIdArrayExample:
            $ref: '#/components/examples/singleEntityByDelimitedRecordIdArrayExample'
          multipleByDelimitedRecordIdArrayExample:
            $ref: '#/components/examples/multipleEntitiesByDelimitedRecordIdArrayExample'
          singleByJsonRecordIdArrayExample:
            $ref: '#/components/examples/singleEntityByJsonRecordIdArrayExample'
          multipleByJsonRecordIdArrayExample:
            $ref: '#/components/examples/multipleEntitiesByJsonRecordIdArrayExample'
          multipleByMixedRecordIdArrayExample:
            $ref: '#/components/examples/multipleEntitiesByMixedRecordIdArrayExample'
      - name: maxDegrees
        description: >-
            The maximum number of degrees to look for a path between the
            specified entities.  If not specified, this defaults to `3`.
            Unlike `GET /entity-paths/` the value here may be zero (0) which
            allows the caller to specify a list of entities and simply
            "build out" the network around each to a maximum number of degrees
            and up to a maximum number of entities.
        in: query
        required: false
        schema:
          type: integer
          format: int8
          minimum: 0
          default: 3
      - name: buildOut
        description: >-
            The maximum number of degrees to build out around each of the
            specified entities regardless of those entities being on the
            path between entities.  The number of entities built out is limited
            by the `maxEntities` parameter.  This defaults to `1` degree if not
            specified.
        in: query
        required: false
        schema:
          type: integer
          format: int8
          minimum: 0
          maximum: 100
          default: 1
      - name: maxEntities
        description: >-
            The maximum number of entities to build out when the `buildOut` is
            greater than zero (0).  This defaults to `1000` if not specified.
        in: query
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
          default: 1000
      - $ref: '#/components/parameters/detailLevelQueryParam'
      - $ref: '#/components/parameters/featureModeQueryParam'
      - $ref: '#/components/parameters/withFeatureStatsQueryParam'
      - $ref: '#/components/parameters/withInternalFeaturesQueryParam'
      - $ref: '#/components/parameters/forceMinimalQueryParam'
      - $ref: '#/components/parameters/withRawQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzEntityNetworkResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzEntityNetworkResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzEntityNetworkResponse'
        '400':
          description: >-
            If no entity identifiers are specified or if any of the parameters
            are not formatted as expected.  Also, if any of the identified
            entities or records cannot be found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /bulk-data/analyze:
    post:
      tags:
        - Bulk Data
      summary: Analyze a bulk data set of records. (Supports SSE / Supports Web Sockets)
      description: |
        Provides a means to analyze a bulk data file of records prior to loading
        it.  The records are encoded as a JSON array of JSON objects, a single
        JSON object per line in JSON-lines file format, or as a CSV with one
        record per row.  The data should be in pre-mapped format using JSON
        property names or CSV column names as described by the
        [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification).

        **SCALABILITY NOTE:** This operation can be invoked in three ways.  In
        order of increasingly better scalability these are listed below:
          1. Standard HTTP Request/Response
          2. HTTP Request with SSE Response (see below)
          3. HTTP Upgrade Request for Web Sockets (see below)

        Standard HTTP Request/Response (method 1) has the worst scalability
        because a long-running operation will tie up a Web Server thread **and**
        continue until complete even if the client aborts the operation since
        no data is written back to the client until complete and therefore the
        terminated connection will not be detected.  SSE (method 2) mitigates
        the problem of detecting when a client has aborted the operation
        because periodic progress responses are written to the client and
        therefore a terminated connection will be detected.  However, the best
        way to invoke this operation is via Web Sockets (method 3) which not
        only can detect disconnection of the client, but it also upgrades the
        request to use its own thread outside the Web Server thread pool.

        **SSE NOTE:** This end-point supports "Server-sent Events" (SSE) via the
        `text/event-stream` media type.  This support is activated by adding the
        `Accept: text/event-stream` header to a request to override the
        default `application/json` media type.  Further, the end-point will behave
        similarly to its standard operation but will produce `progress` events
        at regular intervals that are equivalent to its `200` response schema.
        Upon success, the final event will be `completed` with the same response
        schema as a `200` response.  Upon failure, the final event will be
        `failed` with same `SzErrorResponse` schema as the `4xx` or `5xx`.

        **WEB SOCKETS NOTE**: If invoking via Web Sockets then the client may
        send text or binary chunks of the JSON, JSON-Lines or CSV bulk data file
        as messages.  In Web Sockets, text messages are *always* sent as UTF-8.
        If the file's character encoding is unknown then the client should send
        binary messages and the server will attempt to auto-detect the character
        encoding.  Each message should adhere to the maximum message size
        specified by the `webSocketsMessageMaxSize` property returned by the
        `GET /server-info` end-point.  The end of file is detected when the
        number of seconds specified by the `eofSendTimeout` query parameter have
        elapsed without a new message being received.
      operationId: analyzeBulkRecords
      parameters:
        - $ref: '#/components/parameters/progressPeriodParam'
        - $ref: '#/components/parameters/eofSendTimeoutParam'
      requestBody:
        description: |
          The bulk record data as a single JSON record per line, a JSON array,
          or a CSV.  Further, `multipart/form-data` can be provided with the
          "data" property representing the record data as described above.  Set
          your content type accordingly.  The data should be in pre-mapped
          format using JSON property names or CSV column names as described by
          the [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification).
        required: true
        content:
          text/plain; charset=UTF-8:
            schema:
              type: string
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              bulkDataCSVExample:
                $ref: '#/components/examples/bulkDataCSVExample'
              bulkDataJsonLinesExample:
                $ref: '#/components/examples/bulkDataJsonLinesExample'
              bulkDataJsonExample:
                $ref: '#/components/examples/bulkDataJsonExample'
          text/plain:
            schema:
              type: string
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              bulkDataCSVExample:
                $ref: '#/components/examples/bulkDataCSVExample'
              bulkDataJsonLinesExample:
                $ref: '#/components/examples/bulkDataJsonLinesExample'
              bulkDataJsonExample:
                $ref: '#/components/examples/bulkDataJsonExample'
          application/x-jsonlines; charset=UTF-8:
            schema:
              type: string
            examples:
              seeTextPlainExamples:
                $ref: '#/components/examples/seeTextPlainJsonLinesExamples'
          application/x-jsonlines:
            schema:
              type: string
            examples:
              seeTextPlainExamples:
                $ref: '#/components/examples/seeTextPlainJsonLinesExamples'
          application/json; charset=UTF-8:
            schema:
              type: string
            examples:
              seeTextPlainExamples:
                $ref: '#/components/examples/seeTextPlainJsonExamples'
          application/json:
            schema:
              type: string
            examples:
              seeTextPlainExamples:
                $ref: '#/components/examples/seeTextPlainJsonExamples'
          text/csv; charset=UTF-8:
            schema:
              type: string
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              bulkDataCSVExample:
                $ref: '#/components/examples/bulkDataCSVExample'
          text/csv:
            schema:
              type: string
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              bulkDataCSVExample:
                $ref: '#/components/examples/bulkDataCSVExample'
          multipart/form-data:
            schema:
              type: object
              properties:
                  body:
                    type: string
                    format: binary
      responses:
        '200':
          description: Successful response.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzBulkDataAnalysisResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzBulkDataAnalysisResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzBulkDataAnalysisResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /bulk-data/load:
    post:
      tags:
        - Bulk Data
      summary: Load the records in the provided bulk data set. (Supports SSE / Supports Web Sockets)
      description: |
        Provides a means to load a bulk data file of records.  The records are
        encoded as a JSON array of JSON objects, a single JSON object per line
        in JSON-lines file format, or as a CSV with one record per row.  The
        data should be in pre-mapped format using JSON property names or CSV
        column names as described by the
        [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification).

        **SCALABILITY NOTE:** This operation can be invoked in three ways.  In
        order of increasingly better scalability these are listed below:
          1. Standard HTTP Request/Response
          2. HTTP Request with SSE Response (see below)
          3. HTTP Upgrade Request for Web Sockets (see below)

        Standard HTTP Request/Response (method 1) has the worst scalability
        because a long-running operation will tie up a Web Server thread **and**
        continue until complete even if the client aborts the operation since
        no data is written back to the client until complete and therefore the
        terminated connection will not be detected.  SSE (method 2) mitigates
        the problem of detecting when a client has aborted the operation
        because periodic progress responses are written to the client and
        therefore a terminated connection will be detected.  However, the best
        way to invoke this operation is via Web Sockets (method 3) which not
        only can detect disconnection of the client, but it also upgrades the
        request to use its own thread outside the Web Server thread pool.

        **SSE NOTE:** This end-point supports "Server-sent Events" (SSE) via the
        `text/event-stream` media type.  This support is activated by adding the
        `Accept: text/event-stream` header to a request to override the
        default `application/json` media type.  Further, the end-point will behave
        similarly to its standard operation but will produce `progress` events
        at regular intervals that are equivalent to its `200` response schema.
        Upon success, the final event will be `completed` with the same response
        schema as a `200` response.  Upon failure, the final event will be
        `failed` with same `SzErrorResponse` schema as the `4xx` or `5xx`.

        **WEB SOCKETS NOTE**: If invoking via Web Sockets then the client may
        send text or binary chunks of the JSON, JSON-Lines or CSV bulk data file
        as messages.  In Web Sockets, text messages are *always* sent as UTF-8.
        If the file's character encoding is unknown then the client should send
        binary messages and the server will attempt to auto-detect the character
        encoding.  Each message should adhere to the maximum message size
        specified by the `webSocketsMessageMaxSize` property returned by the
        `GET /server-info` end-point.  The end of file is detected when the
        number of seconds specified by the `eofSendTimeout` query parameter have
        elapsed without a new message being received.
      operationId: loadBulkRecords
      parameters:
        - name: dataSource
          description: |
            Used to set the overriding data source for the records.  This data
            source will be assigned to every record **unless** the record's
            data source (including blank data source) has a specific mapping
            specified by a `mapDataSources` or `mapDataSource` parameters.  If
            this parameter is **not** provided and no specific overrides are
            provided for a record then the data source specified in the inbound
            record is used directly.  If the record has no data source and no
            override is provided then it will fail to load.
          in: query
          required: false
          schema:
            type: string
          examples:
            CUSTOMERS:
              value: CUSTOMERS
            EMPLOYEES:
              value: EMPLOYEES
        - name: mapDataSources
          description: |
            A URL-encoded JSON object whose properties are interpreted as
            data source codes to map from and whose corresponding values are
            interpretted as data source codes to map to.  For example,
            `{"EMPL": "EMPLOYEES"}` (url-encoded of course) would map all
            records with inbound data source `EMPL` to `EMPLOYEES`.  To map
            only inbound records with no data source to a specific data source
            you would use an empty JSON property (e.g.: `{"": "CUSTOMERS"}`).
            If the `dataSource` parameter is **not** provided and no specific
            overrides are provided for a record with this parameter or via
            `mapDataSource` then the data source specified in the inbound
            record is used directly.  If the record has no data source and no
            overriding or mapped data source is provided for an empty data
            source then the record will fail to load.

            **NOTE**: If both this parameter and the `mapDataSource` parameter
            is provided then the mappings are merged with the more ad-hoc
            `mapDataSource` parameter taking precedence since it is likely being
            used for debugging and diagnostic purposes to avoid the URL
            encoding.

            Here are some examples of encoding this parameter:

            - **JavaScript Example**
              ```javascript
                var dataSourceMap = {
                  "": "CUSTOMERS",
                  "EMPL": "EMPLOYEES",
                  "VEND": "VENDORS"
                };
                var mapDataSources = JSON.stringify(dataSourceMap);
                var urlPath = "/bulk-data/load?mapDataSources="
                            + encodeURIComponent(mapDataSources);
              ```

            - **Java Example**
              ```java
                JsonObjectBuilder builder = Json.createObjectBuilder();
                builder.add("", "CUSTOMERS");
                builder.add("EMPL", "EMPLOYEES");
                builder.add("VEND", "VENDORS");
                JsonObject dataSourceMap = builder.build();

                String mapDataSources = dataSourceMap.toString();
                String encodedMap     = URLEncoder.encode(mapDataSources, "UTF-8");
                String urlPath = "/bulk-data/load?mapDataSources=" + encodedMap;
              ```

            In both of the above examples the `urlPath` variable is set to:
            ```json

            /bulk-data/load?mapDataSources=%7B%22%22%3A%22CUSTOMERS%22%2C%22EMPL%22%3A%22EMPLOYEES%22%2C%22VEND%22%3A%22VENDORS%22%7D

            ```
          in: query
          required: false
          schema:
            type: string
          examples:
            notSpecifiedExample:
              summary: Not specified
              value:
            mapEmptyExample:
              summary: Single mapping for missing data source
              value: >-
                {
                  "": "CUSTOMERS"
                }
            mapMultipleExample:
              summary: Multiple data source mappings
              value: >-
                {
                  "": "CUSTOMERS",
                  "EMPL": "EMPLOYEES",
                  "VEND": "VENDORS"
                }
        - name: mapDataSource
          description: |
            As an alternative to the `mapDataSources` parameter you may specify
            the `mapDataSource` parameter zero or more times to add additional
            data source mappings or **override** data source mappings from
            `mapDataSources`.  If you are using this API programmatically
            then you should typically use the `mapDataSources` parameter
            instead of this one.  But when manually constructing a URL in the
            browser address bar, in a command-line tool like `curl` or in a REST
            client browser extension for debugging or testing purposes, encoding
            the JSON value for `mapDataSources` can be unwieldy.  This parameter
            (which is multi-valued) lets you specify delimited strings that
            begin with the delimiter character, followed by the original
            data source name, then the delimiter character and the new data
            source name.  You should only have to URL-encode the delimiter you
            choose and maybe spaces.  For example, `:EMPL:EMPLOYEES` or
            `|EMPL|EMPLOYEES` (url-encoded of course) would map all records with
            inbound data source `EMPL` to `EMPLOYEES`.  To map only inbound
            records with no data source to a specific data source you would
            begin the value with two repeated delimiter characters followed by
            the new data source value (e.g.: `||CUSTOMERS` or `::CUSTOMERS`).
            If the `dataSource` parameter is **not** provided and no specific
            overrides are provided for a record with this parameter or the
            `mapDataSources` parameter then the data source specified in the
            inbound record is used directly.  If the record has no data source
            and no overriding or mapped data source is provided for an empty
            data source then the record will fail to load.
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          examples:
            noMappingsSpecified:
              summary: No data source mappings specified
              value: [ ]
            singleSpecificOverrideExample:
              summary: Map a single specific data source
              value: [ ":CUST:CUSTOMERS" ]
            multipleSpecificOverridesExample:
              summary: Map multiple specific data sources
              value: [ ":CUST:CUSTOMERS", ":EMPL:EMPLOYEES" ]
            multipleSpecificOverridesWithEmptyExample:
              summary: Map multiple specific data sources with empty mapping
              value: [ "::CUSTOMERS", ":EMPL:EMPLOYEES", ":VENDOR:VENDORS" ]
        - name: maxFailures
          description: |
            The maximum number of failures that can occur before the bulk
            load operation is aborted.  If the value is less-than or equal-to
            zero (0) then the operation will continue regardless of the number
            of errors that occur.
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 0
        - $ref: '#/components/parameters/progressPeriodParam'
        - $ref: '#/components/parameters/eofSendTimeoutParam'
      requestBody:
        description: |
          The bulk record data as a single JSON record per line, a JSON array,
          or a CSV.  Further, `multipart/form-data` can be provided with the
          "data" property representing the record data as described above.  Set
          your content type accordingly.  The data should be in pre-mapped
          format using JSON property names or CSV column names as described by
          the [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification).
        required: true
        content:
          text/plain; charset=UTF-8:
            schema:
              type: string
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              bulkDataCSVExample:
                $ref: '#/components/examples/bulkDataCSVExample'
              bulkDataJsonLinesExample:
                $ref: '#/components/examples/bulkDataJsonLinesExample'
              bulkDataJsonExample:
                $ref: '#/components/examples/bulkDataJsonExample'
          text/plain:
            schema:
              type: string
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              bulkDataCSVExample:
                $ref: '#/components/examples/bulkDataCSVExample'
              bulkDataJsonLinesExample:
                $ref: '#/components/examples/bulkDataJsonLinesExample'
              bulkDataJsonExample:
                $ref: '#/components/examples/bulkDataJsonExample'
          application/x-jsonlines; charset=UTF-8:
            schema:
              type: string
            examples:
              seeTextPlainExamples:
                $ref: '#/components/examples/seeTextPlainJsonLinesExamples'
          application/x-jsonlines:
            schema:
              type: string
            examples:
              seeTextPlainExamples:
                $ref: '#/components/examples/seeTextPlainJsonLinesExamples'
          application/json; charset=UTF-8:
            schema:
              type: string
            examples:
              seeTextPlainExamples:
                $ref: '#/components/examples/seeTextPlainJsonExamples'
          application/json:
            schema:
              type: string
            examples:
              seeTextPlainExamples:
                $ref: '#/components/examples/seeTextPlainJsonExamples'
          text/csv; charset=UTF-8:
            schema:
              type: string
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              bulkDataCSVExample:
                $ref: '#/components/examples/bulkDataCSVExample'
          text/csv:
            schema:
              type: string
            examples:
              chooseExample:
                $ref: '#/components/examples/chooseExample'
              bulkDataCSVExample:
                $ref: '#/components/examples/bulkDataCSVExample'
          multipart/form-data:
            schema:
              type: object
              properties:
                body:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successful response
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzBulkLoadResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzBulkLoadResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzBulkLoadResponse'
        '403':
          description: >-
            If the server was started in read-only mode and so the operation
            is not permitted.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
            default:
              schema:
                $ref: '#/components/schemas/SzErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  examples:
    chooseExample:
      summary: -- choose an example --
      value: >-

    seeTextPlainJsonLinesExamples:
      summary: -- see text/plain examples for JSON-lines --
      value: >-
        JSON-lines examples with content type application/x-jsonlines do not
        render properly in Swagger UI as they are escaped as JSON strings.
        Choose the various text/plain content types to see them correctly.

    seeTextPlainJsonExamples:
      summary: -- see text/plain examples for JSON --
      value: >-
        JSON examples with content type application/json do not render
        properly in Swagger UI as they are escaped as JSON strings.  Choose
        the various text/plain content types to see them correctly.

    noDataSources:
      summary: No data sources in content body
      value: >-

    singleDataSourceUnquotedString:
      summary: Single data source as an unquoted string
      value: >-
        CUSTOMERS
    singleDataSourceString:
      summary: Single data source as a string
      value: >-
        "CUSTOMERS"
    singleDataSourceStringArray:
      summary: Single data source in a string array
      value: >-
        ["CUSTOMERS"]
    multipleDataSourcesStringArray:
      summary: Multiple data sources in a string array
      value: >-
        ["CUSTOMERS", "EMPLOYEES"]
    singleDataSourceObjectNoId:
      summary: Single data source as an SzDataSource object
      value: >-
        {"dataSourceCode": "CUSTOMERS"}
    singleDataSourceObjectArrayNoId:
      summary: Single data source as an SzDataSource array
      value: >-
        [ {"dataSourceCode": "CUSTOMERS"} ]
    singleDataSourceObjectWithId:
      summary: Single data source as an SzDataSource object with ID
      value: >-
        {
          "dataSourceCode": "CUSTOMERS",
          "dataSourceId": 1000
        }
    singleDataSourceObjectArrayWithId:
      summary: Single data source as an SzDataSource array with ID
      value: >-
        [
          {
            "dataSourceCode": "CUSTOMERS",
            "dataSourceId": 1000
          }
        ]
    multipleDataSourcesObjectArrayWithId:
      summary: Multiple data sources as an SzDataSource array with IDs
      value: >-
        [
          {
            "dataSourceCode": "CUSTOMERS",
            "dataSourceId": 1000
          },
          {
            "dataSourceCode": "EMPLOYEES",
            "dataSourceId": 1001
          }
        ]
    multipleDataSourcesMixed:
      summary: Multiple data sources in a mixed array
      value: >-
        [
          "CUSTOMERS",
          {
            "dataSourceCode": "EMPLOYEES"
          },
          {
            "dataSourceCode": "VENDOR",
            "dataSourceId": 1002
          }
        ]
    simpleFlatRecordExample:
      summary: Simple flat JSON record
      value: >-
        {
          "NAME_FIRST": "JANE",
          "NAME_LAST": "SCHMOE",
          "PHONE_NUMBER": "559-555-1212",
          "ADDR_LINE1": "653 STATE ROUTE 7",
          "ADDR_CITY": "FRESNO",
          "ADDR_STATE": "CA",
          "ADDR_POSTAL_CODE": "55073-1234"
        }
    complexFlatRecordExample:
      summary: Complex flat JSON record
      value: >-
        {
          "NAME_FIRST": "JANE",
          "NAME_LAST": "SCHMOE",
          "HOME_PHONE_NUMBER": "559-555-1212",
          "WORK_PHONE_NUMBER": "559-555-1414",
          "HOME_ADDR_LINE1": "653 STATE ROUTE 7",
          "HOME_ADDR_CITY": "FRESNO",
          "HOME_ADDR_STATE": "CA",
          "HOME_ADDR_POSTAL_CODE": "55073-1234"
          "WORK_ADDR_LINE1": "701 E MAIN STREET",
          "WORK_ADDR_CITY": "FOWLER",
          "WORK_ADDR_STATE": "CA",
          "WORK_ADDR_POSTAL_CODE": "93625"
        }
    simpleHierarchicalRecordExample:
      summary: Simple hierarchical JSON record
      value: >-
        {
          "NAMES": [
            {
              "NAME_FIRST": "JANE",
              "NAME_LAST": "SCHMOE"
            }
          ],
          "PHONE_NUMBERS": [
            {
              "PHONE_NUMBER": "559-555-1212"
            }
          ],
          "ADDRESSES": [
            {
              "ADDR_LINE1": "653 STATE ROUTE 7",
              "ADDR_CITY": "FRESNO",
              "ADDR_STATE": "CA",
              "ADDR_POSTAL_CODE": "55073-1234"
            }
          ]
        }
    complexHierarchicalRecordExample:
      summary: Complex hierarchical JSON record
      value: >-
        {
          "NAMES": [
            {
              "NAME_TYPE": "PRIMARY",
              "NAME_FIRST": "JANE",
              "NAME_LAST": "SCHMOE"
            },
            {
              "NAME_TYPE": "MAIDEN",
              "NAME_FIRST": "JANE",
              "NAME_LAST": "SMITH"
            }
          ],
          "PHONE_NUMBERS": [
            {
              "PHONE_TYPE": "HOME",
              "PHONE_NUMBER": "559-555-1212"
            },
            {
              "PHONE_TYPE": "WORK",
              "PHONE_NUMBER": "559-555-1414"
            }
          ],
          "ADDRESSES": [
            {
              "ADDR_TYPE": "HOME",
              "ADDR_LINE1": "653 STATE ROUTE 7",
              "ADDR_CITY": "FRESNO",
              "ADDR_STATE": "CA",
              "ADDR_POSTAL_CODE": "55073-1234"
            },
            {
              "ADDR_TYPE": "WORK",
              "ADDR_LINE1": "701 E MAIN STREET",
              "ADDR_CITY": "FOWLER",
              "ADDR_STATE": "CA",
              "ADDR_POSTAL_CODE": "93625"
            }
          ]
        }
    noEntitiesExample:
      summary: No entities specified
      value: [ ]
    noRecordsExample:
      summary: No records specified
      value: [ ]
    singleEntityByEntityIdExample:
      summary: Single entity by entity ID
      value: [ 987654 ]
    multipleEntitiesByEntityIdExample:
      summary: Multiple entities by entity ID
      value: [ 987654, 765432 ]
    singleEntityByDelimitedRecordIdExample:
      summary: Single entity by delimiter-encoded record ID
      value: [ ":CUSTOMERS:GHI789" ]
    singleRecordByDelimitedRecordIdExample:
      summary: Single record by delimiter-encoded record ID
      value: [ ":CUSTOMERS:GHI789" ]
    multipleEntitiesByDelimitedRecordIdExample:
      summary: Multiple entities by delimiter-encoded record ID
      value: [ ":CUSTOMERS:GHI789", ":EMPLOYEES:JKL321" ]
    multipleRecordsByDelimitedRecordIdExample:
      summary: Multiple records by delimiter-encoded record ID
      value: [ ":CUSTOMERS:GHI789", ":EMPLOYEES:JKL321" ]
    singleEntityByJsonRecordIdExample:
      summary: Single entity by JSON-encoded record ID
      value: [ '{"src":"CUSTOMERS","id":"GHI789"}' ]
    singleRecordByJsonRecordIdExample:
      summary: Single record by JSON-encoded record ID
      value: [ '{"src":"CUSTOMERS","id":"GHI789"}' ]
    multipleEntitiesByJsonRecordIdExample:
      summary: Multiple entities by JSON-encoded record ID
      value: [ '{"src":"CUSTOMERS","id":"GHI789"}', '{"src":"EMPLOYEES","id":"JKL321"}' ]
    multipleRecordsByJsonRecordIdExample:
      summary: Multiple records by JSON-encoded record ID
      value: [ '{"src":"CUSTOMERS","id":"GHI789"}', '{"src":"EMPLOYEES","id":"JKL321"}' ]
    multipleEntitiesByMixedRecordIdExample:
      summary: Multiple entities by mixed-encoded record ID
      value: [ ":CUSTOMERS:GHI789", '{"src":"EMPLOYEES","id":"JKL321"}' ]
    multipleRecordsByMixedRecordIdExample:
      summary: Multiple records by mixed-encoded record ID
      value: [ ":CUSTOMERS:GHI789", '{"src":"EMPLOYEES","id":"JKL321"}' ]
    noEntitiesArrayExample:
      summary: No entities specified
      value:
    noRecordsArrayExample:
      summary: No records specified
      value:
    singleEntityByEntityIdArrayExample:
      summary: Single entity by entity ID
      value: '[987654]'
    multipleEntitiesByEntityIdArrayExample:
      summary: Multiple entities by entity ID
      value: '[987654,765432]'
    singleEntityByDelimitedRecordIdArrayExample:
      summary: Single entity by delimiter-encoded record ID
      value: '[":CUSTOMERS:GHI789"]'
    singleRecordByDelimitedRecordIdArrayExample:
      summary: Single record by delimiter-encoded record ID
      value: '[":CUSTOMERS:GHI789"]'
    multipleEntitiesByDelimitedRecordIdArrayExample:
      summary: Multiple entities by delimiter-encoded record ID
      value: '[":CUSTOMERS:GHI789",":EMPLOYEES:JKL321"]'
    multipleRecordsByDelimitedRecordIdArrayExample:
      summary: Multiple records by delimiter-encoded record ID
      value: '[":CUSTOMERS:GHI789",":EMPLOYEES:JKL321"]'
    singleEntityByJsonRecordIdArrayExample:
      summary: Single entity by JSON-encoded record ID
      value: '[{"src":"CUSTOMERS","id":"GHI789"}]'
    singleRecordByJsonRecordIdArrayExample:
      summary: Single record by JSON-encoded record ID
      value: '[{"src":"CUSTOMERS","id":"GHI789"}]'
    multipleEntitiesByJsonRecordIdArrayExample:
      summary: Multiple entities by JSON-encoded record ID
      value: '[{"src":"CUSTOMERS","id":"GHI789"},{"src":"EMPLOYEES","id":"JKL321"}]'
    multipleRecordsByJsonRecordIdArrayExample:
      summary: Multiple records by JSON-encoded record ID
      value: '[{"src":"CUSTOMERS","id":"GHI789"},{"src":"EMPLOYEES","id":"JKL321"}]'
    multipleEntitiesByMixedRecordIdArrayExample:
      summary: Multiple entities by mixed-encoded record ID
      value: '[":CUSTOMERS:GHI789",{"src":"EMPLOYEES","id":"JKL321"}]'
    multipleRecordsByMixedRecordIdArrayExample:
      summary: Multiple records by mixed-encoded record ID
      value: '[":CUSTOMERS:GHI789",{"src":"EMPLOYEES","id":"JKL321"}]'
    ssnSearchExample:
      summary: Social security number
      value: >-
        {
          "SSN_NUMBER": "111-22-3333"
        }
    nameAndBirthDateSearchExample:
      summary: Name and date of birth
      value: >-
        {
          "NAME_FULL": "JANE SMITH",
          "DATE_OF_BIRTH": "03-SEP-1987"
        }
    nameAndAddressSearchExample:
      summary: Name and address
      value: >-
        {
          "NAME_FULL": "JANE SMITH",
          "ADDR_LINE1": "653 STATE ROUTE 7",
          "ADDR_CITY": "FRESNO",
          "ADDR_STATE": "CA",
          "ADDR_POSTAL_CODE": "55073-1234"
        }
    bulkDataCSVExample:
      summary: Bulk records in CSV format
      value: >-
        NAME_FIRST,NAME_LAST,HOME_PHONE_NUMBER,CELL_PHONE_NUMBER,HOME_ADDR_FULL

        SALLY,SCHMOE,559-555-1212,559-555-1414,"653 STATE ROUTE 7; FRESNO, CA 55073-1234"

        JOE,SCHMOE,559-555-1212,559-555-1616,"653 STATE ROUTE 7; FRESNO, CA 55073-1234"

        JOHN,DOE,559-555-1717,559-555-1919,"501 E MAIN STREET; FOWLER, CA 93625"

        JANE,DOE,559-555-1717,559-555-1313,"501 E MAIN STREET; FOWLER, CA 93625"
    bulkDataJsonLinesExample:
      summary: >-
        Bulk records in "JSON Lines" format (i.e.: one record per line)
      value: >-
        {"NAME_FIRST": "SALLY", "NAME_LAST": "SCHMOE", "PHONE_NUMBERS": [ { "PHONE_TYPE": "HOME", "PHONE_NUMBER": "559-555-1212" }, { "PHONE_TYPE": "CELL", "PHONE_NUMBER": "559-555-1414" } ], "ADDRESSES": [ { "ADDR_TYPE": "HOME", "ADDR_FULL": "653 STATE ROUTE 7; FRESNO, CA 55073-1234" } ] }

        {"NAME_FIRST": "JOE", "NAME_LAST": "SCHMOE", "PHONE_NUMBERS": [ { "PHONE_TYPE": "HOME", "PHONE_NUMBER": "559-555-1212" }, { "PHONE_TYPE": "CELL", "PHONE_NUMBER": "559-555-1616" } ], "ADDRESSES": [ { "ADDR_TYPE": "HOME", "ADDR_FULL": "653 STATE ROUTE 7; FRESNO, CA 55073-1234" } ] }

        {"NAME_FIRST": "JOHN", "NAME_LAST": "DOE", "PHONE_NUMBERS": [ { "PHONE_TYPE": "HOME", "PHONE_NUMBER": "559-555-1717" }, { "PHONE_TYPE": "CELL", "PHONE_NUMBER": "559-555-1919" } ], "ADDRESSES": [ { "ADDR_TYPE": "HOME", "ADDR_FULL": "501 E MAIN STREET; FOWLER, CA 93625" } ] }

        {"NAME_FIRST": "JANE", "NAME_LAST": "DOE", "PHONE_NUMBERS": [ { "PHONE_TYPE": "HOME", "PHONE_NUMBER": "559-555-1717" }, { "PHONE_TYPE": "CELL", "PHONE_NUMBER": "559-555-1313" } ], "ADDRESSES": [ { "ADDR_TYPE": "HOME", "ADDR_FULL": "501 E MAIN STREET; FOWLER, CA 93625" } ] }
    bulkDataJsonExample:
      summary: >-
        Bulk records in JSON format (i.e.: JSON array)
      value: >-
        [
          {
            "NAMES": [
              {
                "NAME_FIRST": "SALLY",
                "NAME_LAST": "SCHMOE"
              }
            ],
            "PHONE_NUMBERS": [
              {
                "PHONE_TYPE": "HOME",
                "PHONE_NUMBER": "559-555-1212"
              },
              {
                "PHONE_TYPE": "CELL",
                "PHONE_NUMBER": "559-555-1414"
              }
            ],
            "ADDRESSES": [
              {
                "ADDR_TYPE": "HOME",
                "ADDR_LINE1": "653 STATE ROUTE 7",
                "ADDR_CITY": "FRESNO",
                "ADDR_STATE": "CA",
                "ADDR_POSTAL_CODE": "55073-1234"
              }
            ]
          },
          {
            "NAMES": [
              {
                "NAME_FIRST": "JOE",
                "NAME_LAST": "SCHMOE"
              }
            ],
            "PHONE_NUMBERS": [
              {
                "PHONE_TYPE": "HOME",
                "PHONE_NUMBER": "559-555-1212"
              },
              {
                "PHONE_TYPE": "CELL",
                "PHONE_NUMBER": "559-555-1616"
              }
            ],
            "ADDRESSES": [
              {
                "ADDR_TYPE": "HOME",
                "ADDR_LINE1": "653 STATE ROUTE 7",
                "ADDR_CITY": "FRESNO",
                "ADDR_STATE": "CA",
                "ADDR_POSTAL_CODE": "55073-1234"
              }
            ]
          },
          {
            "NAMES": [
              {
                "NAME_FIRST": "JOHN",
                "NAME_LAST": "DOE"
              }
            ],
            "PHONE_NUMBERS": [
              {
                "PHONE_TYPE": "HOME",
                "PHONE_NUMBER": "559-555-1717"
              },
              {
                "PHONE_TYPE": "CELL",
                "PHONE_NUMBER": "559-555-1919"
              }
            ],
            "ADDRESSES": [
              {
                "ADDR_TYPE": "HOME",
                "ADDR_LINE1": "501 E MAIN STREET",
                "ADDR_CITY": "FOWLER",
                "ADDR_STATE": "CA",
                "ADDR_POSTAL_CODE": "93625"
              }
            ]
          },
          {
            "NAMES": [
              {
                "NAME_FIRST": "JANE",
                "NAME_LAST": "DOE"
              }
            ],
            "PHONE_NUMBERS": [
              {
                "PHONE_TYPE": "HOME",
                "PHONE_NUMBER": "559-555-1717"
              },
              {
                "PHONE_TYPE": "CELL",
                "PHONE_NUMBER": "559-555-1313"
              }
            ],
            "ADDRESSES": [
              {
                "ADDR_TYPE": "HOME",
                "ADDR_LINE1": "501 E MAIN STREET",
                "ADDR_CITY": "FOWLER",
                "ADDR_STATE": "CA",
                "ADDR_POSTAL_CODE": "93625"
              }
            ]
          }
        ]
    bulkDataMultipartCSVExample:
      summary: Bulk records as multipart CSV
      value: >-
        ------WebKitFormBoundarytZEPvKNPgkuBvg4F
        Content-Disposition: form-data; name="data"; filename="Co-workers.csv"
        Content-Type: text/csv

        ------WebKitFormBoundarytZEPvKNPgkuBvg4F
        NAME_FIRST,NAME_LAST,HOME_PHONE_NUMBER,CELL_PHONE_NUMBER,HOME_ADDR_FULL
        SALLY,SCHMOE,559-555-1212,559-555-1414,"653 STATE ROUTE 7; FRESNO, CA 55073-1234"
        JOE,SCHMOE,559-555-1212,559-555-1616,"653 STATE ROUTE 7; FRESNO, CA 55073-1234"
        JOHN,DOE,559-555-1717,559-555-1919,"501 E MAIN STREET; FOWLER, CA 93625"
        JANE,DOE,559-555-1717,559-555-1313,"501 E MAIN STREET; FOWLER, CA 93625"
  parameters:
    withRawQueryParam:
      in: query
      name: withRaw
      required: false
      description: >-
        Whether or not to include the raw JSON response from the underlying
        native API.  This raw response may include additional details but
        lack some of the abstraction the standard response provides.  If
        true, then the 'rawData' field in the response will be a non-null
        value and contain the additional details.
      schema:
        type: boolean
        default: false
    withRelatedQueryParam:
      in: query
      name: withRelated
      required: false
      description: >-
        Controls how to handle the first-degree related entities.  The possible
        values are:
          * `NONE` - Do not include any data on first-degree related entities --
             this is the fastest option from a performance perspective because
             related entities do not have to be retrieved.
          * `PARTIAL` - **(default value)** Include only partial stub
             information for related entities with the `partial` property of the
             `SzRelatedEntity` instances set to `true`.  Obtaining additional
             information requires subsequent API calls.
          * `FULL` - Include full data on the first-degree related entities
             according to the `featureMode` and `detailLevel` **unless**
             `forceMinimal` is `true`.  This option obtains the entity network
             at one degree for the requested entity and will populate up to 1000
             related entities as much as possible with respect to the
             `featureMode` and `detailLevel`.  Related entities beyond the first
             1000 will be left incomplete and have their `partial` property set
             to `true` regardless of the `detailLevel` and `featureMode`.  If
             this value is specified along with `forceMinimal=true` then
             `PARTIAL` is used instead.
      schema:
        default: PARTIAL
        $ref: '#/components/schemas/SzRelationshipMode'
    featureModeQueryParam:
      in: query
      name: featureMode
      required: false
      description: >-
        The method by which feature values should be included for entities
        returned in the response.  The possible values are:
          * `NONE` - Do not include any feature values -- this is the fastest
                     option from a performance perspective because feature
                     values do not have to be retrieved.
          * `REPRESENTATIVE` - Include only a single representative value per
                               "unique" value of a feature.  If there are
                               multiple values that are near duplicates then
                               only one value is included and the others are
                               suppressed.
          * `WITH_DUPLICATES` - ** (default value) ** Group near-duplicate
                                feature values and return a representative value
                                along with its near duplicate values.
          * `ATTRIBUTED` - Same as `WITH_DUPLICATES` but with record-level
                           references attributing each feature to the record(s)
                           that provided it for the entity along with any
                           usage type that might have been associated with the
                           feature at the record level.
      schema:
        default: WITH_DUPLICATES
        $ref: '#/components/schemas/SzFeatureMode'
    detailLevelQueryParam:
      in: query
      name: detailLevel
      required: false
      description: >-
        Specifies the level of detail desired for the entity data.  Details for
        features of entities as well as the related entities of entities are
        controlled by `featureMode`, `withInternalFeatures`, and
        `withFeatureStats`.  If not specified the value defaults to `VERBOSE`.
        Possible values are:
          * `BARE_MINIMAL` - The entities returned will include only their
                             entity ID's.  No record information is returned
                             and if related entities are included, they too will
                             only be described by their entity ID's and will
                             **not** include any matching info.
          * `NETWORK_MINIMAL` - Identical to `BARE_MINIMAL` except in the case
                                of related entities being included they will
                                also include related matching info.
          * `MINIMAL` - The entities returned will include at most their
                        entity ID's as well as identifiers for their
                        constituent records (i.e.: data source code and record
                        ID for each record).  This detail level is optimized for
                        the fastest possible processing time.
          * `BRIEF` - Builds upon `MINIMAL` to add the entity name and related
                      entity match info when related entity match info when
                      related entities are included.  This detail level aims to
                      maintain as much speed as possible while providing names
                      and relationship information for rendering a graph.
          * `SUMMARY` - Identical to `BRIEF` except that individual record
                        identifier information is excluded, leaving only the
                        record summary (i.e.: a record count by data source
                        code).  This reduces the size of the JSON document for
                        large entities with thousands of records.  It may take
                        longer to process than `BRIEF` but less data is
                        returned as well, speeding up network transfer times.
          * `VERBOSE` - Combines `BRIEF` and `SUMMARY` and then adds the
                        original JSON data for each record, the record-level
                        matching info, as well as formatted record data.  NOTE:
                        the record-level matching info returned via "how" and
                        "why" is often more useful than that embedded in the
                        entity.  Further, the formatted record data, while
                        readable, is not formatted according to locale (i.e.:
                        address, name and date formatting may not appear as
                        expected to a user).
      schema:
        default: VERBOSE
        $ref: '#/components/schemas/SzDetailLevel'
    withRelationshipsQueryParam:
      in: query
      name: withRelationships
      description: >-
        Set to `true` to include partial information of related entities for
        the returned entities.  This defaults to `false`.
      required: false
      schema:
        type: boolean
        default: false
    whyWithFeatureStatsQueryParam:
      in: query
      name: withFeatureStats
      description: >-
        Set to `false` to suppress resolution statistics for features.  This
        defaults to `true` for why operations.
      required: false
      schema:
        type: boolean
        default: true
    whyWithInternalFeaturesQueryParam:
      in: query
      name: withInternalFeatures
      description: >-
        Set to `false` to suppress "expressed" features that are derived
        composite keys such as `FULL_NAME` + `DATE_OF_BIRTH`.  This
        defaults to `true` for why operations.
      required: false
      schema:
        type: boolean
        default: true
    withFeatureStatsQueryParam:
      in: query
      name: withFeatureStats
      description: >-
        Set to `true` to include resolution statistics for features.  This
        defaults to `false`.
      required: false
      schema:
        type: boolean
        default: false
    withInternalFeaturesQueryParam:
      in: query
      name: withInternalFeatures
      description: >-
        Set to `true` to include "expressed" features that are derived composite
        keys such as name + date of birth keys.  This defaults to `false`.
      required: false
      schema:
        type: boolean
        default: false
    includeOnlyQueryParam:
      in: query
      name: includeOnly
      description: >-
        Optional parameter that can be specified zero or more times to
        indicate which `SzAttributeSearchResultType`'s should be included
        in the search results.  If not specified then all match types are
        included.  *NOTE*: This parameter is ignored unless the underlying
        native Senzing API is version 2.4.1 or later.
      required: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/SzAttributeSearchResultType'
      examples:
        notSpecifiedExample:
          summary: Not specified - include all search results
          value:
        includeOnlyMatches:
          summary: Only include matches
          value: [ "MATCH" ]
        includeOnlyMatchesAndPossibleMatches:
          summary: Only include matches and possible matches.
          value: [ "MATCH", "POSSIBLE_MATCH" ]
        includeAllButNameOnlyMatches:
          summary: Include all but name-only matches.
          value: [ "MATCH", "POSSIBLE_MATCH", "POSSIBLE_RELATION" ]
        includeOnlyNameOnlyMatches:
          summary: Only include name-only matches.
          value: [ "NAME_ONLY_MATCH" ]
    withInfoQueryParam:
      in: query
      name: withInfo
      description: >-
        Set to `true` to include resolution information related to loading, and
        `false` to exclude it.  This defaults to `false`.
      required: false
      schema:
        type: boolean
        default: false
    loadIdQueryParam:
      in: query
      name: loadId
      required: false
      description: >-
        The optional load ID to associate with the loaded record.
      schema:
        type: string
    forceMinimalQueryParam:
      in: query
      name: forceMinimal
      required: false
      description: >-
        Whether (or not) to force the minimum entity detail in the response
        which will consist of nothing more than an entity ID and record
        identifying information (i.e.: data source code and record ID) for each
        constituent record of an entity.  Unlike `detailLevel=MINIMAL` setting
        this to `true` precludes the addition of feature information via other
        parameters.  Setting this to `true` provides the fastest response to an
        entity query operation because no additional data needs to be retrieved
        other than what is directly accessible.  Setting this parameter to
        `true` overrules other parameters governing the retrieval of features
        or related entities.
      schema:
        type: boolean
        default: false
    dataSourceCodePathParam:
      in: path
      name: dataSourceCode
      required: true
      description: >-
        The data source code identifying the data source.
      schema:
        type: string
      examples:
        TEST:
          value: TEST
        CUSTOMERS:
          value: CUSTOMERS
        EMPLOYEES:
          value: EMPLOYEES
    recordIdPathParam:
      in: path
      name: recordId
      required: true
      description: >-
        The identifier that uniquely identifies the requested record
        within a given data source.  This may have been specified
        when the record was loaded or generated automatically.
      schema:
        type: string
    progressPeriodParam:
      in: query
      name: progressPeriod
      required: false
      description: >-
        The suggested maximum time between SSE `progress` events specified in
        milliseconds.  If not specified then the default of `3000` milliseconds
        (i.e.: 3 seconds) is used.  This parameter is NOT used if the operation
        is not producing an SSE response (i.e.: `text/event-stream` media type
        was not requested via the `Accept` header).
      schema:
        type: integer
        format: int64
        default: 3000
    eofSendTimeoutParam:
      in: query
      name: eofSendTimeout
      required: false
      description: >-
        The number of seconds to wait for an additional Web Sockets message
        before assuming end-of-file (EOF) when using this end-point via Web
        Sockets protocol.  If this number of seconds elapses with no additional
        incoming data then the server assumes that there are no more file chunks
        forthcoming.  If not specified then the default of `3` seconds is used.
        This parameter is NOT used if the operation is not invoked via the Web
        Sockets (`ws://`) protocol.  **NOTE**: This is specified in seconds,
        **not** milliseconds.
      schema:
        type: integer
        format: int32
        default: 3
  responses:
    ServerError:
      description: Unexpected server error occurred.
      content:
        application/json; charset=UTF-8:
          schema:
            $ref: '#/components/schemas/SzErrorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/SzErrorResponse'
        default:
          schema:
            $ref: '#/components/schemas/SzErrorResponse'
  schemas:
    SzMeta:
      description: >-
        Represents the meta data returned with each response.
      type: object
      properties:
        server:
          description: >-
            The descriptive name of the server that produced the response.
          type: string
        httpMethod:
          $ref: '#/components/schemas/SzHttpMethod'
        httpStatusCode:
          description: >-
            The HTTP status response code.
          type: integer
          format: int16
        timestamp:
          description: >-
            The timestamp of the operation's execution.
          type: string
          format: date-time
        version:
          description: >-
            The version number of the server.
          type: string
        restApiVersion:
          description: >-
            The REST API specification version implemented by the server.
          type: string
        nativeApiVersion:
          description: >-
            The version of the underlying native Senzing API product.
          type: string
        nativeApiBuildVersion:
          description: >-
            The build version of the underlying native Senzing API product.
          type: string
        nativeApiBuildNumber:
          description: >-
            The build number of the underlying native Senzing API product.
          type: string
        nativeApiBuildDate:
          description: >-
            The build date of the underlying native Senzing API product.
          type: string
          format: date-time
        configCompatibilityVersion:
          description: >-
            The config compatilibility version of the underlying native Senzing
            API product.
          type: string
        timings:
          description: >-
            The timing measurements that were taken where the keys are
            identifying what was timed and the values are the number of
            milliseconds.
          type: object
          nullable: true
          additionalProperties:
            type: integer
            format: int64
    SzLinks:
      description: >-
        Represents the default links returned with each response.
      type: object
      properties:
        self:
          type: string
        openApiSpecification:
          type: string
    SzBaseResponse:
      description: >-
        Represents the base information included in all responses sans the
        actual data for the response.
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/SzMeta'
        links:
          $ref: '#/components/schemas/SzLinks'
    SzErrorResponse:
      description: >-
        The response describing an error that occurred.
      allOf:
        - $ref: '#/components/schemas/SzBaseResponse'
        - type: object
          properties:
            errors:
              type: array
              items:
                $ref: '#/components/schemas/SzError'
    SzResponseWithRawData:
      description: >-
        Extends the BaseResponse to add the rawData field.
      allOf:
        - $ref: '#/components/schemas/SzBaseResponse'
        - type: object
          properties:
            rawData:
              description: >-
                The RAW result from the underlying native API function.
              type: object
              nullable: true
              additionalProperties: {}
    SzOpenApiSpecResponse:
      description: >-
        Extends the BaseResponse to describe a response containing the
        Open API specification in JSON format as the data.
      allOf:
        - $ref: '#/components/schemas/SzBaseResponse'
        - type: object
          properties:
            data:
              description: >-
                This Open API specification in JSON format.
              type: object
              nullable: false
              additionalProperties: {}
    SzOpenApiSpecResponseOrRawJson:
      description: >-
        This represents the possible return type for an Open API specification
        which can be an instance of `SzOpenApiSpecResponse` or raw JSON of the
        Open API specification.
      oneOf:
        - $ref: '#/components/schemas/SzOpenApiSpecResponse'
        - type: object
          additionalProperties: {}
    SzLicenseResponseData:
      description: >-
        Represents the data segment included with an `SzLicenseResponse`
      type: object
      properties:
        license:
          $ref: '#/components/schemas/SzLicenseInfo'
    SzLicenseResponse:
      description: >-
        The response containing the license information.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzLicenseResponseData'
    SzVersionResponse:
      description: >-
        The response containing the version information.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzVersionInfo'
    SzServerInfoResponse:
      description: >-
        The response containing the server info.
      allOf:
        - $ref: '#/components/schemas/SzBaseResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzServerInfo'
    SzAttributeTypesResponseData:
      description: >-
        Describes the data associated with the `SzAttributeTypesResponse`.
      type: object
      properties:
        attributeTypes:
          description: >-
            The list of attribute types.
          type: array
          items:
            $ref: '#/components/schemas/SzAttributeType'
    SzAttributeTypesResponse:
      description: >-
        The response containing attribute type information.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzAttributeTypesResponseData'
    SzAttributeTypeResponseData:
      description: >-
        Describes the data segment associated with `SzAttributeTypeResponse`
      type: object
      properties:
        attributeType:
          $ref: '#/components/schemas/SzAttributeType'
    SzAttributeTypeResponse:
      description: >-
        The response containing information for a single attribute type.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzAttributeTypeResponseData'
    SzDataSourceResponseData:
      description: >-
        Describes the data associated with `SzDataSourceResponse`
      type: object
      properties:
        dataSource:
          description: >-
            The requested data source as an `SzDataSource` object.
          $ref: '#/components/schemas/SzDataSource'
    SzDataSourceResponse:
      description: >-
        The response describing a data source.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzDataSourceResponseData'
    SzDataSourcesResponseData:
      description: >-
        Describes the data for `SzDataSourceResponse`.
      type: object
      properties:
        dataSources:
          description: >-
            The list of data source codes for the configured data
            sources.
          type: array
          items:
            type: string
        dataSourceDetails:
          description: >-
            The list of `SzDataSource` instances describing the data
            sources that are configured.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SzDataSource'
    SzDataSourcesResponse:
      description: >-
        The response describing the configured data sources.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzDataSourcesResponseData'
    SzConfigResponse:
      description: >-
        The response containing raw configuration in the rawData field.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
    SzLoadRecordResponseData:
      description: >-
        Describes the data segment of `SzLoadRecordResponse`.
      type: object
      properties:
        recordId:
          description: >-
            The record ID of the record that was loaded.
          type: string
        info:
          description: >-
            The optionally requested info associated with the load.
          $ref: '#/components/schemas/SzResolutionInfo'
    SzLoadRecordResponse:
      description: >-
        Describes the response when a record is successfully loaded.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzLoadRecordResponseData'
    SzReevaluateResponseData:
      description: >-
        Describes the data segment of `SzReevaluateResponse`.
      type: object
      properties:
        info:
          description: >-
            The optionally requested info associated with the load.
          $ref: '#/components/schemas/SzResolutionInfo'
    SzReevaluateResponse:
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzReevaluateResponseData'
    SzDeleteRecordResponseData:
      description: >-
        Describes the data segment of `SzDeleteRecordResponse`.
      type: object
      properties:
        info:
          description: >-
            The optionally requested info associated with the load.
          $ref: '#/components/schemas/SzResolutionInfo'
    SzDeleteRecordResponse:
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzDeleteRecordResponseData'
    SzRecordResponse:
      description: >-
        The response describing an entity record.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              type: object
              properties:
                record:
                  description: >-
                    The `SzEntityRecord` describing the matching record.
                  $ref: '#/components/schemas/SzEntityRecord'
    SzEntityResponse:
      description: >-
        The response describing a resolved entity and possibly its related
        entities.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzEntityData'
    SzVirtualEntityResponse:
      description: >-
        The response describing a simulated virtual entity and possibly its
        related entities.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzVirtualEntityData'
    SzAttributeSearchResponseData:
      description: >-
        Describes the data segment of the `SzAttributeSearchResponse`
      type: object
      properties:
        searchResults:
          description: >-
            The array of `AttributeSearchResult` instances describing the
            entities matching the specified entity search attributes
            including the `AttributeSearchResultType` for each.
          type: array
          items:
            $ref: '#/components/schemas/SzAttributeSearchResult'
    SzAttributeSearchResponse:
      description: >-
        The response describing the resolved entities found from a search.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzAttributeSearchResponseData'
    SzEntityPathResponse:
      description: >-
        The response describing a path between two resolved entities.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzEntityPathData'
    SzEntityNetworkResponse:
      description: >-
        The response describing a network of resolved entities.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SzEntityNetworkData'
    SzBulkDataAnalysisResponse:
      description: >-
        The response describing the analysis of bulk data records.
      allOf:
        - $ref: '#/components/schemas/SzBaseResponse'
        - type: object
          properties:
            data:
              description: >-
                The `SzBulkDataAnalysis` describing the analysis of the bulk
                records.
              $ref: '#/components/schemas/SzBulkDataAnalysis'
    SzBulkLoadResponse:
      description: >-
        The response describing the result of loading bulk data.
      allOf:
        - $ref: '#/components/schemas/SzBaseResponse'
        - type: object
          properties:
            data:
              description: >-
                The `SzBulkLoadResult` describing the load statistics from
                loading a bulk data set.
              $ref: '#/components/schemas/SzBulkLoadResult'
    SzWhyEntityResponse:
      description: >-
        The response describing the result of "why" operation.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              type: object
              properties:
                whyResults:
                  description: >-
                    The array of `SzWhyEntityResult` instances describing why
                    from each evaluated perspective within the entity.
                  type: array
                  items:
                    $ref: '#/components/schemas/SzWhyEntityResult'
                entities:
                  description: >-
                    The array of `SzEntityData` objects describing the entities
                    involved in the response.  This will include partial
                    information on the first-degree related entities to the
                    entity.
                  type: array
                  items:
                    $ref: '#/components/schemas/SzEntityData'
    SzWhyRecordsResponse:
      description: >-
        The response describing the result of "why" operation.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              type: object
              properties:
                whyResult:
                  description: >-
                    The `SzWhyRecordsResult` describing why from for the
                    specified records.
                  $ref: '#/components/schemas/SzWhyRecordsResult'
                entities:
                  description: >-
                    The array of `SzEntityData` objects describing the entities
                    involved in the response.  This will include partial
                    information on the first-degree related entities to the
                    entity.
                  type: array
                  items:
                    $ref: '#/components/schemas/SzEntityData'
    SzWhyEntitiesResponse:
      description: >-
        The response describing the result of "why entities" operation.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              type: object
              properties:
                whyResult:
                  description: >-
                    The `SzWhyEntitiesResult` describing why the two entities
                    did not resolve or why they related.
                  $ref: '#/components/schemas/SzWhyEntitiesResult'
                entities:
                  description: >-
                    The array of `SzEntityData` objects describing the entities
                    involved in the response.  This will include partial
                    information on the first-degree related entities to the
                    entity.
                  type: array
                  items:
                    $ref: '#/components/schemas/SzEntityData'
    SzError:
      description: >-
        Describes an error.
      type: object
      properties:
        code:
          description: The internal error code.
          type: string
          nullable: true
        message:
          description: The message describing the error.
          type: string
    SzBulkLoadError:
      description: >-
        Describes an error and the number of times it occurred.
      type: object
      properties:
        error:
          description: >-
            The error that occurred.
          $ref: '#/components/schemas/SzError'
        occurrenceCount:
          description: >-
            The number of times the error occurred while loading data
            from the bulk data set.
          type: integer
          format: int32
    SzHttpMethod:
      description: >-
        The HTTP method that was used for the operation.  The possible values
        are:
          * `GET` - An HTTP GET operation.
          * `POST` - An HTTP POST operation.
          * `PUT` - An HTTP PUT operation.
          * `PATCH` - An HTTP PATCH operation.
          * `DELETE` - An HTTP DELETE operation.
      type: string
      enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
    SzAttributeClass:
      description: >-
        Enumerates the various classes of attribute types (and features).
        This is a generalization over attribute type that is more general
        than feature type (NOTE: stand-alone attribute types such as
        "DATA_SOURCE" or "RECORD_ID" do not have a feature type, but do have
        an attribute class of "OBSERVATION").  Attribute class determines how
        attributes / features are grouped together (e.g.: "nameData" contains
        all name features and "identifierData" contains all identifier
        features).  The possible values are:
          * `ADDRESS` - Attributes pertaining to an address such as "POSTAL_CODE"
          * `CHARACTERISTIC` - Attributes pertaining to physical characteristics
                               of an entity.  Such as "BIRTH_DATE"
          * `IDENTIFIER` - Attributes pertaining to identifiers such as
                          drivers license number, passport number, or email
                          address.
          * `NAME` - Attributes pertaing to names such as "NAME_FIRST" or
                     "NAME_LAST"
          * `OBSERVATION` - Attributes pertaining to meta-data about the
                            observation (record) such as "RECORD_ID" or
                            "DATA_SOURCE"
          * `PHONE` - Attributes pertaining to phone numbers such
                      "PHONE_NUMBER" or "PHONE_EXTENSION"
          * `RELATIONSHIP` - Attributes pertaining to relationships such as
                             "RELATIONSHIP_TYPE".
          * `OTHER` - An attribute class for custom features or for attributes
                      that are loaded but not mapped.
      type: string
      enum:
        - ADDRESS
        - CHARACTERISTIC
        - IDENTIFIER
        - NAME
        - OBSERVATION
        - PHONE
        - RELATIONSHIP
        - OTHER
    SzFeatureMode:
      description: >-
        The method by which feature values should be included for entities
        returned in the response.  The possible values are:
          * `NONE` - Do not include any feature values -- this is the fastest
                     option from a performance perspective because feature
                     values do not have to be retrieved.
          * `ENTITY_NAME_ONLY` - Same as `NONE` in that no "features" are
                                 returned, but the singular entity name value
                                 is determined will be determined and returned.
          * `REPRESENTATIVE` - Include only a single representative value per
                               "unique" value of a feature.  If there are
                               multiple values that are near duplicates then
                               only one value is included and the others are
                               suppressed.
          * `WITH_DUPLICATES` - ** (default value) ** Group near-duplicate
                                feature values and return a representative value
                                along with its near duplicate values.
          * `ATTRIBUTED` - Same as `WITH_DUPLICATES` but with record-level
                           references attributing each feature to the record(s)
                           that provided it for the entity along with any
                           usage type that might have been associated with the
                           feature at the record level.
      type: string
      enum:
        - NONE
        - ENTITY_NAME_ONLY
        - REPRESENTATIVE
        - WITH_DUPLICATES
        - ATTRIBUTED
      default: WITH_DUPLICATES
    SzRelationshipMode:
      description: >-
        Controls how to handle the first-degree related entities.  The possible
        values are:
          * `NONE` - Do not include any data on first-degree related entities --
             this is the fastest option from a performance perspective because
             related entities do not have to be retrieved.
          * `PARTIAL` - **(default value)** Include only partial stub
             information for related entities with the `partial` property of the
             `SzRelatedEntity` instances set to `true`.  Obtaining additional
             information requires subsequent API calls.
          * `FULL` - Include full data on the first-degree related entities
             according to the `featureMode` and `detailLevel` **unless**
             `forceMinimal` is `true`.  This option obtains the entity network
             at one degree for the requested entity and will populate up to 1000
             related entities as much as possible with respect to the
             `featureMode` and `detailLevel`.  Related entities beyond the first
             1000 will be left incomplete and have their `partial` property set
             to `true` regardless of the `detailLevel` and `featureMode`.  If
             this value is specified along with `forceMinimal=true` then
             `PARTIAL` is used instead.
      type: string
      enum:
        - NONE
        - PARTIAL
        - FULL
      default: PARTIAL
    SzAttributeNecessity:
      description: >-
        Describes the necessity for this attribute type within the
        feature type.  Possible values are:
          * `REQUIRED` - The attribute for the attribute type must be
                         provided whenever the feature is provided (e.g.:
                         "PASSPORT_NUMBER" is required with the "PASSPORT"
                         feature).
          * `SUFFICIENT` - If no attributes for `REQUIRED` attribute types
                           are provided for the feature, then at least one
                           marked `SUFFICIENT` must be provided (e.g.:
                           "NAME_FULL" or "NAME_ORG" for the "NAME" feature)
          * `PREFERRED` - Attributes of `PREFERRED` attribute types are
                          optional, but providing them greatly enhances
                          accuracy for scoring and matching purposes (e.g.:
                          a "PASSPORT_COUNTRY" for "PASSPORT" feature)
          * `OPTIONAL` - Attributes of `OPTIONAL` attribute types are
                         optional and do not significantly affect accuracy
                         for scoring and matching purposes, but do provide
                         additional information (e.g.: "PASSPORT_ISSUE_DT"
                         for the "PASSPORT" feature)
      type: string
      enum:
        - REQUIRED
        - SUFFICIENT
        - PREFERRED
        - OPTIONAL
    SzDetailLevel:
      description: >-
        Describes the level of detail desired for entity data when obtained via
        the various endpoints that return entity data.  Details for features of
        entities as well as the related entities of entities are controlled by
        other flags.  Possible values are:
          * `BARE_MINIMAL` - The entities returned will include only their
                             entity ID's.  No record information is returned
                             and if related entities are included, they too will
                             only be described by their entity ID's and will
                             **not** include any matching info.
          * `NETWORK_MINIMAL` - Identical to `BARE_MINIMAL` except in the case
                                of related entities being included they will
                                also include related matching info.
          * `MINIMAL` - The entities returned will include at most their
                        entity ID's as well as identifiers for their
                        constituent records (i.e.: data source code and record
                        ID for each record).  This detail level is optimized for
                        the fastest possible processing time.
          * `BRIEF` - Builds upon `MINIMAL` to add the entity name and related
                      entity match info when related entity match info when
                      related entities are included.  This detail level aims to
                      maintain as much speed as possible while providing names
                      and relationship information for rendering a graph.
          * `SUMMARY` - Identical to `BRIEF` except that individual record
                        identifier information is excluded, leaving only the
                        record summary (i.e.: a record count by data source
                        code).  This reduces the size of the JSON document for
                        large entities with thousands of records.  It may take
                        longer to process than `BRIEF` but less data is
                        returned as well, speeding up network transfer times.
          * `VERBOSE` - Combines `BRIEF` and `SUMMARY` and then adds the
                        original JSON data for each record, the record-level
                        matching info, as well as formatted record data.  NOTE:
                        the record-level matching info returned via "how" and
                        "why" is often more useful than that embedded in the
                        entity.  Further, the formatted record data, while
                        readable, is not formatted according to locale (i.e.:
                        address, name and date formatting may not appear as
                        expected to a user).
      type: string
      enum:
        - BARE_MINIMAL
        - NETWORK_MINIMAL
        - MINIMAL
        - BRIEF
        - SUMMARY
        - VERBOSE
    SzAttributeType:
      description: >-
        Describes an attribute type that partially (or fully) describes a
        feature of an entity that may be loaded as part of a record or
        used as criteria in a search.
      type: object
      properties:
        attributeCode:
          description: >-
            The unique string that identifies the attribute type among all
            other attribute types.
          type: string
          nullable: false
        defaultValue:
          description: >-
            The default value assumed for the attribute when it is not
            provided but is required as part of a feature.
          type: string
          nullable: true
        necessity:
          $ref: '#/components/schemas/SzAttributeNecessity'
        attributeClass:
          $ref: '#/components/schemas/SzAttributeClass'
        featureType:
          description: >-
            Identifiers the feature type that this attribute type is an
            attribute of (if any).  For example, the "NAME_FIRST" attribute type
            would be an attribute of the "NAME" feature type and
            "PASSPORT_COUNTRY" would be an attribute of "PASSPORT" feature type.
            Some (advanced) attribute types are stand-alone and do not belong
            to a feature (e.g.: "RECORD_ID").
          type: string
          nullable: true
        advanced:
          description: >-
            Indicates if the attribute type is considered to be "advanced".
            Advanced attribute types usually require the user to have some
            knowledge of how the data is mapped in the entity repository
            (e.g.: "RECORD_ID" or "DATA_SOURCE").  An application may exclude
            displaying these as options if these things are being auto-generated
            or automatically selected for the user.  You may want to contact
            Senzing support before leveraging advanced attribute types in your
            application.
          type: boolean
          nullable: false
        internal:
          description: >-
            Whether or not an attribute type is typically generated internally
            based on other attribute types.  These are not commonly used by the
            user except in some rare cases.  Examples include pre-hashed
            versions of attributes that are hashed.
          type: boolean
          nullable: false
    SzEntityIdentifier:
      description: >-
        Identifies an entity by either its entity ID or by the data source
        code and record ID of one of its constituent records.  If a record ID
        is specified then it is either as a JSON-encoded `SzRecordId` or a
        delimited string where the first character is the delimiter, followed
        by the data source code, then the delimiter and the record ID (e.g.:
        `|CUSTOMERS|ABC123`).
      oneOf:
        - type: integer
          format: int64
        - $ref: '#/components/schemas/SzRecordId'
        - type: string
    SzRecordIdentifier:
      description: >-
        Identifies a record by its data source code and record ID.  This is
        either a JSON-encoded `SzRecordId` or a delimited string where the first
        character is the delimiter, followed by the data source code, then the
        delimiter and the record ID (e.g.: `|CUSTOMERS|ABC123`).
      oneOf:
        - $ref: '#/components/schemas/SzRecordId'
        - type: string
    SzEntityIdentifiers:
      description: >-
        Identifies zero or more entities by either its entity ID or by the
        data source code and record ID of one of their constituent records.
        Identifiers in the array are homogeneous, either all entity IDs or
        all `SzRecordId` instances containing the data-source-code/record-id
        pair.  If specified as record IDs they are either JSON-encoded
        `SzRecordId` instances or a delimited string where the first character
        is the delimiter, followed by the data source code, then the delimiter
        and the record ID (e.g.: `|CUSTOMERS|ABC123`).
      oneOf:
        - type: array
          items:
            type: integer
            format: int64
        - type: array
          items:
            $ref: '#/components/schemas/SzRecordId'
        - type: array
          items:
            type: string
        - type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/SzRecordId'
              - type: string
    SzRecordIdentifiers:
      description: >-
        Identifies zero or more records by their data source codes and record
        ID's.  Identifiers in the array are homogeneous, either all entity IDs or
        all RecordId instances containing the data-source-code/record-id pair.
        The record ID's are either JSON-encoded `SzRecordId` instances or a
        delimited string where the first character is the delimiter, followed
        by the data source code, then the delimiter and the record ID (e.g.:
        `|CUSTOMERS|ABC123`).
      oneOf:
        - type: array
          items:
            $ref: '#/components/schemas/SzRecordId'
        - type: array
          items:
            type: string
        - type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/SzRecordId'
              - type: string
    SzRecordId:
      description: >-
        Identifies a record by its data source code and record identifier.
        This abbreviated format is used in query parameters to identify
        records via JSON strings.
      type: object
      properties:
        src:
          description: >-
            The data source code that uniquely identifies the data source
            associated with the record.
          type: string
        id:
          description: >-
            The record ID that uniquely identifies a record within the
            respective data source.
          type: string
    SzLicenseInfo:
      description: >-
        Describes the Senzing product license.
      type: object
      properties:
        customer:
          type: string
          description: >-
            The customer information associated with the license.
        contract:
          type: string
          description: >-
            The contract information associated with the license.
        licenseType:
          type: string
          description: >-
            The description of the type of license.
        licenseLevel:
          type: string
          description: >-
            The description of the license level.
        billing:
          type: string
          description: >-
            The billing information associated with the license
        issuanceDate:
          type: string
          format: date-time
          description: >-
            The issuance date for the license.
        expirationDate:
          type: string
          format: date-time
          description: >-
            The expiration date for the license.
        recordLimit:
          type: integer
          format: int64
          description: >-
            The record limit associated with the license.
    SzVersionInfo:
      description: >-
        Describes the Senzing version information.
      type: object
      properties:
        apiServerVersion:
          type: string
          description: >-
            The version of the REST API Server implementation.
        restApiVersion:
          type: string
          description: >-
            The version of the REST API Specification that is implemented.
        nativeApiVersion:
          type: string
          description: >-
            The version for the underlying runtime native Senzing API.
        nativeApiBuildVersion:
          type: string
          description: >-
            The build version for the underlying runtime native Senzing API.
        nativeApiBuildNumber:
          type: string
          description: >-
            The build number for the underlying runtime native Senzing API.
        nativeApiBuildDate:
          type: string
          format: date-time
          description: >-
            The build date for the underlying runtime native Senzing API.
        configCompatibilityVersion:
          type: string
          description: >-
            The configuration compatibility version for the underlying runtime
            native Senzing API.
    SzFlaggedRecord:
      description: >-
        Describes a sample record from an `SzFlaggedEntity` including the
        triggered flags for that record.
      type: object
      properties:
        dataSource:
          description: >-
            The data source code associated with the sample record.
            type: string
          type: string
        recordId:
          description: >-
            The record ID identifying with the same record.
          type: string
        flags:
          description: >-
            The array of flags triggered by the sample record.
          type: array
          items:
            type: string
    SzFlaggedEntity:
      description: >-
        An entity that was flagged as relevant due to the resolution operation.
      type: object
      properties:
        entityId:
          description: >-
            The entity ID of the relevant entity.
          type: integer
          format: int64
        degrees:
          description: >-
            The number of degrees this entity is separated from the
            entity that was affected.
          type: integer
          format: int8
        flags:
          description: >-
            The array of flags that were triggered making this entity
            relevant.
          type: array
          items:
            type: string
        sampleRecords:
          description: >-
             An array of objects describing sample records from the
             relevant entity and the triggered flags for that record.
          type: array
          items:
            $ref: '#/components/schemas/SzFlaggedRecord'
    SzResolutionInfo:
      description: >-
        Provides information relevant to resolution of an entity either when
        loading a record or reevaluating an entity.
      type: object
      properties:
        dataSource:
          description: >-
            The data source for the record that was focus of the load or
            reevaluate operation.
          type: string
        recordId:
          description: >-
            The record ID for the record that was focus of the load or
            reevaluate operation.
          type: string
        affectedEntities:
          description: >-
            The array of entity ID's for the affected entities.
          type: array
          items:
            type: integer
            format: int64
        flaggedEntities:
          description: >-
            The entities that were flagged as relevant due to the resolution
            operation.
          type: array
          items:
            $ref: '#/components/schemas/SzFlaggedEntity'
    SzFeatureReference:
      description: >-
        Describes a record's reference to an entity feature along with the
        optional usage type with which the record references the feature.
      type: object
      properties:
        internalId:
          description: >-
            The internal feature ID identifying the feature so that it might
            be identified and referenced.
          type: integer
          format: int64
        usageType:
          description: >-
            The optional associated usage type (e.g.: "HOME or "WORK).  This is
            the usage type with which the record loaded the feature (if any).
            Other records in the same entity may have the same feature with a
            different usage type.
          type: string
          nullable: true
    SzEntityRecord:
      description: >-
        Describes a record (aka: observed entity) that has been loaded for
        a particular data source.
      type: object
      properties:
        dataSource:
          type: string
          description: >-
            The data source code identifying the source from which the record
            was loaded.
        recordId:
          type: string
          description: >-
            The identifier that uniquely identifies this record from other
            records from the same data source.  This may have been loaded with
            the record or automatically generated from the record's data.
        featureReferences:
          description: >-
            The optional array of record feature references to the entity
            features along with the record's usage type if any.
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SzFeatureReference'
        lastSeenTimestamp:
          description: >-
            The timestamp that the record was most recently loaded or updated.
          type: string
          format: date-time
        addressData:
          description: >-
            An array of addresses associated with the record that are formatted
            for readability.  These may be prefixed by a "usage type" if one
            was provided (e.g.: "HOME: 101 Main Street")
          type: array
          items:
            type: string
        characteristicData:
          description: |
            An array of characteristics associated with the record that are
            formatted for readability.  These will be prefixed by a
            characteristic type and optionally by a "usage type" if one was
            provided.

            **NOTE:** The `characteristicData` field is derived from the
            `ATTRIBUTE_DATA` field in the "raw data" JSON.
          type: array
          items:
            type: string
        identifierData:
          description: >-
            An array of entity data associated with the record where the items
            are formatted for readability.  These will be prefixed by an
            identifier type and may be prefixed by a "usage type" if one was
            provided (e.g.: "ID: 123456789" or "EMAIL: WORK: joe@nowhere.com")
          type: array
          items:
            type: string
        nameData:
          description: >-
            An array of names associated with the record that are formatted for
            readability.  These may be prefixed by a "usage type" if one was
            provided (e.g.: "Joe Schmoe" or "AKA: Joseph P. Schmoe")
          type: array
          items:
            type: string
        phoneData:
          description: >-
            An array of phone numbers associated with the record that are
            formatted for readability.  These may be prefixed by a "usage type"
            if one was provided (e.g.: "HOME: 702-555-1212")
          type: array
          items:
            type: string
        relationshipData:
          description: >-
            An array of relationship data items associated with the record that
            describes disclosed relationships.
          type: array
          items:
            type: string
        otherData:
          description: >-
            An array of associated data items that were loaded with the record
            but not normally recognized or used for entity resolution.  This
            array usually contains useful information from the source system.
          type: array
          items:
            type: string
        originalSourceData:
          description: >-
            The JSON representation of the original data record that was
            loaded.
          type: object
          additionalProperties: {}
    SzMatchedRecord:
      description: >-
        Provides the additional fields to an SzEntityRecord that describe
        how it matched to the entity that it belongs to.
      allOf:
        - $ref: '#/components/schemas/SzEntityRecord'
        - type: object
          properties:
            matchKey:
              description: >-
                The match key describing what features matched between
                the first record in the resolved entity and this record.
                This is blank for the first record.
              type: string
            resolutionRuleCode:
              description: >-
                The code identifying the resolution rule that matched this
                record to the first record in the resolved entity.  This is
                blank for the first record.
              type: string
            matchLevel:
              description: >-
                The integer "match level" describing how the first record in
                the resolved entity matched to this record.  This is zero for
                the first record and usually one (1) for other records.
              type: integer
              format: int32
    SzDataSourceRecordSummary:
      description: >-
        Describes the number of records associated with a specific data source
        for a given resolved entity.  Optionally, if the complete set of records
        has been retrieved for the associated entity, then this may also contain
        the "top 10" record IDs for the associated data source.
      type: object
      properties:
        dataSource:
          description: >-
            The data source code identifying the data source for which the
            record breakdown is being described.
          type: string
        recordCount:
          description: >-
            The number of records from the respective data source that are
            part of the associated resolved entity.
          type: integer
          format: int32
        topRecordIds:
          description: >-
            The optional array of string record ID's identifying the top 10
            records for the associated entity from the respective data source.
            This may be null or an empty array if the data was not available.
          type: array
          nullable: true
          items:
            type: string
    SzEntityFeatureStatistics:
      description: >-
        Describes the entity resolution statistics for the feature value.
      type: object
      properties:
        usedForCandidates:
          description: >-
            Indicates if the feature is used for finding candidates during
            entity resolution.
          type: boolean
        usedForScoring:
          description: >-
            Indicates if the feature is used for scoring during entity
            resolution.
          type: boolean
        entityCount:
          description: >-
            The number of entities having this feature value.
          type: integer
          format: int64
        candidateCapReached:
          description: >-
            Indicates if this feature value is no longer being used to find
            candidates because too many entities share the same value.
          type: boolean
        scoringCapReached:
          description: >-
            Indicates if this feature value is no longer being used in entity
            scoring because too many entities share the same value.
          type: boolean
        suppressed:
          description: >-
            Indicates if this value was suppressed in favor of a more complete
            value.
          type: boolean
    SzEntityFeatureDetail:
      description: >-
        Describes the details of an entity feature value, optionally including
        statistics if they have been requested.
      type: object
      properties:
        internalId:
          description: >-
            The internal ID for the feature value.
          type: integer
          format: int64
        featureValue:
          description: >-
            The feature value.
          type: string
        statistics:
          description: >-
            The `SzEntityFeatureStatistics` describing the statistics for the
            feature value.  This may be `null` if the statistics were not
            requested.
          nullable: true
          $ref: '#/components/schemas/SzEntityFeatureStatistics'
    SzEntityFeature:
      description: >-
        Describes a feature for an entity as well as including any close values
        for the feature that were considered to be duplicate values for
        entity resolution purposes.
      type: object
      properties:
        primaryId:
          description: >-
            The internal ID for the primary feature value.
          type: integer
          format: int64
        primaryValue:
          description: >-
            The primary value for the feature.
          type: string
        usageType:
          description: >-
            The optional associated usage type (e.g.: "HOME" or "WORK")
          type: string
          nullable: true
        duplicateValues:
          description: >-
            The array of values that are close enough to the primary value
            for the feature that they are considered to be duplicate values for
            the purpose of entity resolution.
          type: array
          items:
            type: string
        featureDetails:
          description: >-
            The array of `SzEntityFeatureDetail` instances describing the each
            of the clustered feature values in detail.
          type: array
          items:
            $ref: '#/components/schemas/SzEntityFeatureDetail'
    SzResolvedEntity:
      description: >-
        Describes a resolved entity that is made up of one or more
        SzMatchedRecord instances.
      type: object
      properties:
        entityId:
          description: >-
            The unique numeric ID identifying the entity.
          type: integer
          format: int64
        entityName:
          description: >-
            The name associated with this entity that is considered the
            best name among all the associated names.
          type: string
        bestName:
          description: >-
            Usually the same as the entityName property, but this may differ
            if the entity was found based on a name search.  In such a case,
            this field represents the name that most closely matches the name
            that was searched on.
          type: string
        recordSummaries:
          description: >-
            The array of DataSourceRecordSummary instances describing the
            number of records associated with each data source that contributes
            to this entity.
          type: array
          items:
            $ref: '#/components/schemas/SzDataSourceRecordSummary'
        nameData:
          description: >-
            An array of names associated with the entity that are formatted for
            readability.  These may be prefixed by a "usage type" if one was
            provided (e.g.: "Joe Schmoe" or "AKA: Joseph P. Schmoe")
          type: array
          items:
            type: string
        characteristicData:
          description: >-
            An array of characteristics associated with the entity that are
            formatted for readability.  These will be prefixed by a
            characteristic type and optionally by a "usage type" if one was
            provided.

            **NOTE:** The `characteristicData` field is derived from the
            feature data values that contribute to the `ATTRIBUTE_DATA` field
            at the record level in the "raw data" JSON.
          type: array
          items:
            type: string
        addressData:
          description: >-
            An array of addresses associated with the entity that are formatted
            for readability.  These may be prefixed by a "usage type" if one
            was provided (e.g.: "HOME: 101 Main Street")
          type: array
          items:
            type: string
        phoneData:
          description: >-
            An array of phone numbers associated with the entity that are
            formatted for readability.  These may be prefixed by a "usage type"
            if one was provided (e.g.: "HOME: 702-555-1212")
          type: array
          items:
            type: string
        identifierData:
          description: >-
            An array of entity data associated with the entity where the items
            are formatted for readability.  These will be prefixed by an
            identifier type and may be prefixed by a "usage type" if one was
            provided (e.g.: "ID: 123456789" or "EMAIL: WORK: joe@nowhere.com")
          type: array
          items:
            type: string
        relationshipData:
          description: >-
            An array of relationship data items associated with the entity that
            describes disclosed relationships.
          type: array
          items:
            type: string
        otherData:
          description: >-
            An array of associated data items that were loaded with the entity's
            records but not normally recognized or used for entity resolution.
            This array usually contains useful information from the source
            systems.
          type: array
          items:
            type: string
        records:
          description: >-
            The array of `SzMatchedRecord` instances describing the records
            associated with this entity.
          type: array
          items:
            $ref: '#/components/schemas/SzMatchedRecord'
        features:
          description: >-
            The map of string feature names to arrays of SzEntityFeature instances
            describing the values associated with each respective feature name.
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/SzEntityFeature'
        partial:
          description: >-
            If true then this `SzResolvedEntity` has complete features and
            records, otherwise they are not provided.  Also, the
            recordSummary items may be missing the topRecordIds if partial
            is true.  This can be true for partially retrieved related
            entities or if features are suppressed, if the detail level has
            suppressed records or related matching info (in the case of related
            entities) or if the force-minimal response flag has been been
            specified.
          type: boolean
        lastSeenTimestamp:
          description: >-
            The timestamp that the entity was last seen (i.e.: most recent
            record was loaded).
          type: string
          format: date-time
    SzBaseRelatedEntity:
      description: >-
        Provides the additional fields to an SzResolvedEntity that describe
        an entity's relationship to another.  This serves as a basis for
        SzAttributeSearchResult and SzRelatedEntity.
      allOf:
        - $ref: '#/components/schemas/SzResolvedEntity'
        - type: object
          properties:
            matchLevel:
              description: >-
                The integer "match level" describing how the related entity
                matched to the primary resolved entity.
              type: integer
              format: int32
            matchKey:
              description: >-
                The match key describing what features matched between
                the primary resolved entity and the related entity.
              type: string
            resolutionRuleCode:
              description: >-
                The code identifying the resolution rule that related
                this entity to the primary resolved entity.
              type: string
    SzRelationshipType:
      description: >-
        Describes how an entity is related to another (either a possible match,
        a discovered possible relationship or a disclosed relationship)
      type: string
      enum:
        - POSSIBLE_MATCH
        - POSSIBLE_RELATION
        - DISCLOSED_RELATION
    SzMatchLevel:
      description: >-
        Describes the various match levels describing how two records resolve
        against each other.  The possible values are:
          * `NO_MATCH` - No match was found between the records.
          * `RESOLVED` - The records resolved to the same entity.
          * `POSSIBLY_SAME` - The records were not close enough to resolve
            but may represent the same entity if more data was provided.
          * `POSSIBLY_RELATED` - The records share some attributes that
            suggest a relationship.
          * `NAME_ONLY` - The records match in name only.
          * `DISCLOSED` - An explicit relationship has been disclosed between
            the records.
      type: string
      enum:
        - NO_MATCH
        - RESOLVED
        - POSSIBLY_SAME
        - POSSIBLY_RELATED
        - NAME_ONLY
        - DISCLOSED
    SzRelatedEntity:
      description: >-
        Provides a description of an entity that is related to a
        ResolvedEntity.  This describes how the entity is related and may
        be missing the complete features and record list of a ResolvedEntity.
      allOf:
        - $ref: '#/components/schemas/SzBaseRelatedEntity'
        - type: object
          properties:
            disclosed:
              description: >-
                A boolean flag indicating if this related entity
                represents a disclosed relationship.
              type: boolean
            ambiguous:
              description: >-
                A boolean flag indicating if this related entity
                represents an ambiguous relationship.
              type: boolean
            relationType:
              $ref: '#/components/schemas/SzRelationshipType'
    SzEntityData:
      description: >-
        Describes an entity and the entities related to that entity at
        one degree of separation.
      type: object
      properties:
        resolvedEntity:
          description: The ResolvedEntity describing the primary entity.
          $ref: '#/components/schemas/SzResolvedEntity'
        relatedEntities:
          description: >-
            The array of RelatedEntity instances describing the possible
            matches, discovered relationships, and disclosed relationships.
          type: array
          items:
            $ref: '#/components/schemas/SzRelatedEntity'
    SzVirtualEntityData:
      description: >-
        Describes the data associated with an `SzVirtualEntityResponse`
        which currently includes only an `SzResolvedEntity`.
      type: object
      properties:
        resolvedEntity:
          description: The ResolvedEntity describing the primary entity.
          $ref: '#/components/schemas/SzResolvedEntity'
    SzAttributeSearchResultType:
      description: >-
        Describes how the entity matching the search attributes would have
        entity resolved against those attributes (either a match, possible
        match, discovered relationship or name only match).  The possible values
        are:
           * `MATCH` - The search criteria matches the entity and would resolve
             against it.
           * `POSSIBLE_MATCH` - The search criteria comes close to matching the
             entity but not close enough that it would resolve against it.
           * `POSSIBLE_RELATION` - The search criteria would not match against
             the entity but some features are the same and relate them.
           * `NAME_ONLY_MATCH` - The search criteria matches the entity in name
             only which is not strong enough for a relationship, but provides
             for a weak search match.
      type: string
      enum:
        - MATCH
        - POSSIBLE_MATCH
        - POSSIBLE_RELATION
        - NAME_ONLY_MATCH
    SzAttributeSearchResult:
      description: >-
        Describes an entity that matched attribute search criteria and how
        it matched against that criteria.
      allOf:
        - $ref: '#/components/schemas/SzBaseRelatedEntity'
        - type: object
          properties:
            resultType:
              $ref: '#/components/schemas/SzAttributeSearchResultType'
            bestNameScore:
              description: >-
                The best name score between the search criteria and this
                matched search entity.  The higher the score the closer the
                name match.  This uses either the full name score or
                organization name score.  If none exist then this filed is
                omitted.
              type: integer
              format: int32
            featureScores:
              description: >-
                The map of feature types to arrays of `SzSearchFeatureScore`
                instances for that feature type.
              nullable: true
              type: object
              additionalProperties:
                type: array
                items:
                  $ref: '#/components/schemas/SzSearchFeatureScore'
            relatedEntities:
              description: >-
                The array of RelatedEntity instances describing the possible
                matches, discovered relationships, and disclosed relationships.
              type: array
              items:
                $ref: '#/components/schemas/SzRelatedEntity'
    SzEntityPath:
      description: >-
        Describes a path between two entities using the entity IDs of the
        entities in the path.
      type: object
      properties:
        startEntityId:
          description: The starting entity ID for the path.
          nullable: false
          type: integer
          format: int64
        endEntityId:
          description: The ending entity ID for the path.
          nullable: false
          type: integer
          format: int64
        entityIds:
          description: >-
            The array of entity IDs identifying the entities on the path
            in order of how are they are connected on the path.  This is
            null if there is no path between the entities.
          nullable: true
          type: array
          items:
            type: integer
            format: int64
    SzEntityPathData:
      description: >-
        Describes a path between two entities using the entity IDs of the
        entities in the path and includes the data from the actual entities
        on the path.
      type: object
      properties:
        entityPath:
          $ref: '#/components/schemas/SzEntityPath'
        entities:
          description: >-
            The array of `SzEntityData` objects describing the entities on the
            path.  This will include partial information on the first-degree
            related entities to the entity.
          type: array
          items:
            $ref: '#/components/schemas/SzEntityData'
    SzEntityNetworkData:
      description: >-
        Describes a network of paths between entities using the entity IDs of
        the entities in the path and includes the data from the actual entities
        in the network.
      type: object
      properties:
        entityPaths:
          description: >-
            The array of `SzEntityPath` objects describing the paths that make
            up the entity network (including island networks).
          type: array
          items:
            $ref: '#/components/schemas/SzEntityPath'
        entities:
          description: >-
            The array of `SzEntityData` objects describing the entities on the
            path.  This may only include partial information on the entities at
            the edge of the network.
          type: array
          items:
            $ref: '#/components/schemas/SzEntityData'
    SzServerInfo:
      description: >-
        Provides information about which server features are enabled and which
        are not enabled.
      type: object
      properties:
        concurrency:
          description: >-
            The number of Senzing worker threads pooled for handling requests.
          type: integer
          format: int32
          nullable: false
        activeConfigId:
          description: >-
            The active configuration ID being used by the API server.  This
            is still available if the server was started with a static file
            configuration via the `G2CONFIGFILE` initialization property.
          type: integer
          format: int32
          nullable: false
        dynamicConfig:
          description: >-
            Whether or not the server will automatically pickup the latest
            default configuration if it changes.
          type: boolean
          nullable: false
        readOnly:
          description: >-
            Whether or not the server was started in read-only mode.  If in
            read-only mode then operations that modify the repository (e.g.:
            loading records or configuring new data sources) are not allowed.
          type: boolean
          nullable: false
        adminEnabled:
          description: >-
            Whether or not admin features are enabled.  If admin features are
            not enabled then the configuration cannot be modified.
          type: boolean
          nullable: false
        webSocketsMessageMaxSize:
          description: >-
            The maximum size for inbound text or binary messages when invoking
            end-points via Web Sockets `ws://` protocol.
          type: integer
          format: int32
          nullable: false
        infoQueueConfigured:
          description: >-
            Whether or not an asynchronous INFO queue has been configured for
            automatically sending "INFO" messages when records are loaded,
            reevaluated or deleted.
          type: boolean
          nullable: false
    SzDataSource:
      description: Describes a data source.
      type: object
      properties:
        dataSourceCode:
          description: The data source code.
          type: string
          nullable: false
        dataSourceId:
          description: >-
            The data source ID. The value can be null when used for input in
            creating a data source to indicate that the data source ID should
            be auto-generated.
          type: integer
          format: int32
          nullable: true
    SzDataSourceDescriptor:
      description: >-
        Describes a data source either as only its data source code or as an
        `SzDataSource` object.
      oneOf:
        - type: string
        - $ref: '#/components/schemas/SzDataSource'
    SzDataSourceRecordAnalysis:
      description: >-
        Provides statistics specific to a given data source of the records
        found in bulk data.
      type: object
      properties:
        dataSource:
          description: >-
            The data source code identifying the data source for which the
            statistics are being provided.  This is `null` if the statistics
            pertain to those records with no data source defined in the
            source data.
          type: string
          nullable: true
        recordCount:
          description: >-
            The number of records having the associated data source.
          type: integer
          format: int32
        recordsWithRecordIdCount:
          description: >-
            The number of records having the associated data source that
            include a `RECORD_ID` value.
          nullable: false
          type: integer
          format: int32
    SzBaseBulkLoadResult:
      description: >-
        Provides statistics specific common to all bulk load results regardless
        of how they are aggregated.
      type: object
      properties:
        recordCount:
          description: >-
            The number of records found in the bulk data set with the aggregate
            group.  This may not match the number of "observed entities" once
            loaded since some records may be exact duplicates.
          type: integer
          format: int32
        loadedRecordCount:
          description: >-
            The number of records successfully loaded from the bulk data set
            within the aggregate group.  This may not match the number
            of "observed entities" loaded since some records may be exact
            duplicates.
          type: integer
          format: int32
        incompleteRecordCount:
          description: >-
            The number of records from the bulk data set within the aggregate
            group that are missing a `DATA_SOURCE` value.
          type: integer
          format: int32
        failedRecordCount:
          description: >-
            The number of records from the bulk data set within the aggregate
            group that failed to load.
          type: integer
          format: int32
        topErrors:
          description: >-
            The array of top error occurrences with the number of times they
            occurred when loading records with the associated data source.
          type: array
          items:
            $ref: '#/components/schemas/SzBulkLoadError'
    SzDataSourceBulkLoadResult:
      description: >-
        Provides bulk data load statistics specific to a given data source.
      allOf:
        - $ref: '#/components/schemas/SzBaseBulkLoadResult'
        - type: object
          properties:
            dataSource:
              description: >-
                The data source code identifying the data source for which the
                load statistics are being provided.
              type: string
              nullable: false
    SzBulkDataStatus:
      description: >-
        Describes the status of a bulk data operation:
          * `NOT_STARTED` - The bulk data operation has not started.
          * `IN_PROGRESS` - If bulk data operation is in progress.
          * `ABORTED` - The bulk data operation was aborted.
          * `COMPLETED` - The bulk data operation completed normally.
      type: string
      enum:
        - NOT_STARTED
        - IN_PROGRESS
        - ABORTED
        - COMPLETED
    SzBulkDataAnalysis:
      description: >-
        Describes the analysis performed against a set of bulk data records
        described as a JSON array, JSON Lines format or CSV format.
      type: object
      properties:
        status:
          description: >-
            The state of the bulk load.
          $ref: '#/components/schemas/SzBulkDataStatus'
        characterEncoding:
          description: >-
            The character encoding used to process the bulk data.
          nullable: false
          type: string
        mediaType:
          description: >-
            The media type of the bulk data.
          nullable: false
          type: string
        recordCount:
          description: >-
            The number of records found in the bulk data.  This may not match
            the number of "observed entities" once loaded since some records
            may be exact duplicates.
          nullable: false
          type: integer
          format: int32
        recordsWithRecordIdCount:
          description: >-
            The number of records provided that include a `RECORD_ID` value.
          nullable: false
          type: integer
          format: int32
        recordsWithDataSourceCount:
          description: >-
            The number of records provided that include a `DATA_SOURCE` value.
          nullable: false
          type: integer
          format: int32
        analysisByDataSource:
          description: >-
            The array of `SzDataSourceRecordAnalysis` elements providing statistics on the records by data source.
          nullable: false
          type: array
          items:
            $ref: '#/components/schemas/SzDataSourceRecordAnalysis'
    SzBulkLoadResult:
      description: >-
        Describes the result from loading a set of bulk data records
        described as a JSON array, JSON Lines format or CSV format.
      allOf:
        - $ref: '#/components/schemas/SzBaseBulkLoadResult'
        - type: object
          properties:
            status:
              description: >-
                The state of the bulk load.
              $ref: '#/components/schemas/SzBulkDataStatus'
            characterEncoding:
              description: >-
                The character encoding used to process the bulk data.
              nullable: false
              type: string
            mediaType:
              description: >-
                The media type of the bulk data.
              nullable: false
              type: string
            missingDataSourceCount:
              description: >-
                The number of records that are incomplete because they are
                missing the `DATA_SOURCE` field.
              nullable: false
              type: integer
              format: int32
            resultsByDataSource:
              description: >-
                The array of `SzDataSourceBulkDataResult` elements describing
                the load statistics by data source.
              nullable: false
              type: array
              items:
                $ref: '#/components/schemas/SzDataSourceBulkLoadResult'
    SzFocusRecordId:
      description: >-
        Identifies a focus record for an `SzWhyResult`.
      type: object
      properties:
        dataSource:
          description: >-
            The data source code that uniquely identifies the data source
            associated with the record.
          type: string
        recordId:
          description: >-
            The record ID that uniquely identifies a record within the
            respective data source.
          type: string
    SzScoringFrequency:
      description: >-
        Enumerates the various scoring behavior frequencies for entity features.
        This indicates the number of entities that would typically share the
        same value for a feature of this type.  The possible values are:
          * `ALWAYS_ONE` - The feature value belongs to exactly one entity so
                           if two records share this value they will always
                           merge together.
          * `ONE` - The feature value typically belongs to one entity (like a
                    Social Security Number, Tax ID or Drivers License Number)
          * `FEW` - The feature value typically belongs to at most a few
                    entities (like an Address or Phone Number).
          * `MANY` - The feature value can belong to many entities (like a
                     date of birth)
          * `VERY_MANY` - The feature can belong to very many entities (like
                          a gender).
          * `NAME` - A special frequency used for name features since they have
                     unique properties.
      type: string
      enum:
        - ALWAYS_ONE
        - ONE
        - FEW
        - MANY
        - VERY_MANY
        - NAME
    SzScoringBehavior:
      description: >-
        Describes the scoring behavior for a feature / feature type.
      type: object
      properties:
        code:
          description: >-
            The code identifying the behavior.
          type: string
        frequency:
          description: >-
            The number of entities that that would typically share the same
            value for a feature of type.  This value can only be `null` if the
            frequency is unknown for the scoring behavior code that is returned.
          nullable: true
          $ref: '#/components/schemas/SzScoringFrequency'
        exclusive:
          description: >-
            `true` if an entity should typically have only one value for
            a feature of this type (like a Social Security Number, Date of
            Birth) and `false` if the entity can typically have multiple values
            for the feature type (like Address or Phone Number).  This value is
            `null` if exclusivity is not applicable to the scoring behavior such
            as with special scoring behaviors like `NAME`.
          type: boolean
          nullable: true
        stable:
          description: >-
            `true` if the feature value for the feature type remains constant
            for an entity over time (like a Date of Birth), and `false` if it
            can can change for the entity over time (like a Home Address).  This
            is `null` if the stability is not applicable to the scoring behavior
            such as with special behaviors like `NAME`.
          type: boolean
          nullable: true
    SzScoringBucket:
      description: >-
        Describes the scoring bucket that a feature score falls into.  The
        range of scores constitute different buckets depending on the feature
        type..  The possible values are:
            * `NOT_SCORED` - The respective features were not scored.
            * `SAME` - The two feature values are considered to be the same.
            * `CLOSE` - The two feature values are considered to be close.
            * `LIKELY` - The two feature values are similar, but not enough to
                         be considered `CLOSE`.
            * `PLAUSIBLE` - It's possible that the two feature values are the
                            same but almost just as likely that they are not.
            * `UNLIKELY` - It's unlikely that the two feature values represent
                           the same value.
            * `NO_CHANCE` - The two feature values obviously represent different
                            values.
      type: string
      enum:
        - NOT_SCORED
        - SAME
        - CLOSE
        - LIKELY
        - PLAUSIBLE
        - UNLIKELY
        - NO_CHANCE
    SzScoredFeature:
      description: >-
        A description of a feature that has been scored against another feature.
      type: object
      properties:
        featureId:
          description: >-
            The identifier uniquely identifying the feature.
          type: integer
          format: int64
        featureType:
          description: >-
            The feature type of the feature.
          type: string
        featureValue:
          description: >-
            The value of the feature that was scored.
          type: string
        usageType:
          description: >-
            The usage type assigned to the feature value.  This field is
            optional and may be excluded if the value is missing.
          type: string
    SzNameScoring:
      description: >-
        Describes the scoring details between two names.
      type: object
      properties:
        fullNameScore:
          description: >-
            The full name score.  This field is omitted if there is not a
            full name score (e.g.: with an organization name)
          type: integer
          format: int32
        surnameScore:
          description: >-
            The surname score.  This field is omitted if there is not a
            surname score (e.g.: with an organization name or if there were no
            surnames to compare)
          type: integer
          format: int32
        givenNameScore:
          description: >-
            The given name score.  This field is omitted if there is not a
            given name score (e.g.: with an organization name or if there were
            no given names to compare)
          type: integer
          format: int32
        generationScore:
          description: >-
            The generation match score.  This field is omitted if there is not a
            generation match score (e.g.: with an organization name or if there
            were no generations to compare)
          type: integer
          format: int32
        orgNameScore:
          description: >-
            The organization name score.  This field is omitted if there is not
            a organization name score (e.g.: with an personal name)
          type: integer
          format: int32
    SzFeatureScore:
      description: >-
        Describes the scoring between two `SzScoredFeature` instances.
      type: object
      properties:
        featureType:
          description: >-
            The feature type of the features being scored.
          type: string
        inboundFeature:
          description: >-
            The inbound feature described as an `SzScoredFeature`.
          $ref: '#/components/schemas/SzScoredFeature'
        candidateFeature:
          description: >-
            The feature that was a candidate match for the inbound feature (also
            described as an `SzScoredFeature`).
          $ref: '#/components/schemas/SzScoredFeature'
        score:
          description: >-
            The integer score between the two feature values (typically from 0
            to 100).  If this is a name feature, then this value is the "best"
            value from the `SzNameScoring` instance described by
            `nameScoringDetails` (in order of precedence the first of these
            values that exists: `orgNameScore`, `fullNameScore`,
            `surnameScore` and then `givenNameScore`).
          type: integer
          format: int32
        nameScoringDetails:
          description: >-
            The name scoring values if this score is for a name feature.  This
            property is omitted if not a name feature.
          $ref: '#/components/schemas/SzNameScoring'
        scoringBucket:
          description: >-
            The `SzScoringBucket` describing the meaning of the `score`.
          $ref: '#/components/schemas/SzScoringBucket'
        scoringBehavior:
          description: >-
            The `SzScoringBehavior` describing the scoring behavior for the
            features.
          $ref: '#/components/schemas/SzScoringBehavior'
    SzSearchFeatureScore:
      description: >-
        Describes the scoring between two search features.
      type: object
      properties:
        featureType:
          description: >-
            The feature type of the features being scored.
          type: string
        inboundFeature:
          description: >-
            The inbound feature value as a string.
          type: string
        candidateFeature:
          description: >-
            The feature value that was a candidate match for the inbound
            feature as a string.
          type: string
        score:
          description: >-
            The integer score between the two feature values (typically from 0
            to 100).  If this is a name feature, then this value is the "best"
            value from the `SzNameScoring` instance described by
            `nameScoringDetails` (in order of precedence the first of these
            values that exists: `orgNameScore`, `fullNameScore`,
            `surnameScore` and then `givenNameScore`).
          type: integer
          format: int32
        nameScoringDetails:
          description: >-
            The name scoring values if this score is for a name feature.  This
            property is omitted if not a name feature.
          $ref: '#/components/schemas/SzNameScoring'
    SzCandidateKey:
      description: >-
        Describes a candidate key that triggered the scoring of two entities.
      type: object
      properties:
        featureId:
          description: >-
            The identifier for the candidate feature.
          type: integer
          format: int64
        featureType:
          description: >-
            The feature type for the candidate feature.
          type: string
        featureValue:
          description: >-
            The feature value for the candidate feature.
          type: string
    SzRelationDirection:
      description: >-
        The HTTP method that was used for the operation.  The possible values
        are:
          * `OUTBOUND` - The relationship goes in the direction from the first
                         entity to the second entity.
          * `INBOUND` - The relationship goes in the direction from the second
                        entity to the first entity.
          * `BIDIRECTIONAL` - The relationship goes in both directions between
                              the two entities.
      type: string
      enum:
        - INBOUND
        - OUTBOUND
        - BIDIRECTIONAL
    SzRelatedFeatures:
      description: >
        Describes a pair of features that triggered a relationship between the
        respective records.
      type: object
      properties:
        feature1:
          description: >-
            The first related feature.
          $ref: '#/components/schemas/SzScoredFeature'
        feature2:
          description: >-
            The second related feature.
          $ref: '#/components/schemas/SzScoredFeature'
    SzDisclosedRelation:
      description: >-
        Describes a relationship that is disclosed between two records so that
        the respective entities are related.
      type: object
      properties:
        domain:
          description: >-
            The domain of the relationship (e.g.: spouses, parent/child,
            employer/employee, corporate hierarchy, etc...)
          nullable: false
          type: string
        direction:
          description: >-
            The direction of the relationship.
          $ref: '#/components/schemas/SzRelationDirection'
        roles1:
          description: >-
            The relationship roles (aka: usage types) assigned to the first
            entity in the relationship.
          type: array
          items:
            type: string
          uniqueItems: true
        roles2:
          description: >-
            The relationship roles (aka: usage types) assigned to the second
            entity in the relationship.
          type: array
          items:
            type: string
          uniqueItems: true
        relatedFeatures:
          description: >-
            The array of `SzRelatedFeatures` instances that the disclosed
            relationship is composed of.
          type: array
          items:
            $ref: '#/components/schemas/SzRelatedFeatures'
    SzWhyMatchInfo:
      description: >-
        The match info describing why two entities (or records) resolve or
        relate to one another.
      type: object
      properties:
        whyKey:
          description: >-
            The why key indicating the components of the match (similar to the
            match key).
          nullable: false
          type: string
        matchLevel:
          description: >-
            The match level describing how the records relate to each other.
          nullable: false
          $ref: '#/components/schemas/SzMatchLevel'
        resolutionRule:
          description: >-
            The resolution rule that triggered the match.
          nullable: true
          type: string
        candidateKeys:
          description: >-
            The map of feature types to arrays of `SzCandidateKey` instances
            for that feature type.
          nullable: true
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/SzCandidateKey'
        featureScores:
          description: >-
            The map of feature types to arrays of `SzFeatureScore` instances
            for that feature type.
          nullable: true
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/SzFeatureScore'
        disclosedRelations:
          description: >-
            The list of `SzDisclosedRelation` instances describing any
            disclosed relationships between two entities.  If the match info
            pertains to a single entity or if there are no disclosed relations
            between the two entities then this property is absent.
          nullable: true
          type: array
          items:
            $ref: '#/components/schemas/SzDisclosedRelation'
    SzWhyPerspective:
      description: >-
        Describes the perspective used in evaluating why an entity resolved
        or why two records may or may not resolve.  The answer to "why" is
        dependent on which "record" you are comparing against the other
        "records".  Internally, it is not always based on "record" because
        multiple records that are effectively identical collapse into a single
        perspective.
      properties:
        internalId:
          description: >-
            The internal ID uniquely identifying this perspective from others
            in the complete "why" response.
          nullable: false
          type: integer
          format: int64
        entityId:
          description: >-
            The associated entity ID for the perspective.
          nullable: false
          type: integer
          format: int64
        focusRecords:
          description: >-
            The array of `SzFocusRecordId` instances identifying the effectively
            identical records that are being compared against the other records.
          nullable: false
          type: array
          items:
            $ref: '#/components/schemas/SzFocusRecordId'
    SzWhyEntityResult:
      description: >-
        Describes why an entity resolved.
      type: object
      properties:
        perspective:
          description: >-
            The `SzWhyPerspective` identifying and describing the perspective
            for this why result.
          $ref: '#/components/schemas/SzWhyPerspective'
        matchInfo:
          description: >-
            The `SzWhyMatchInfo` providing the details of the result.
          nullable: false
          $ref: '#/components/schemas/SzWhyMatchInfo'
    SzWhyEntitiesResult:
      description: >-
        Describes why two entities did not resolve or why they related.
      type: object
      properties:
        entityId1:
          description: >-
            The entity ID of the first entity.
          nullable: false
          type: integer
          format: int64
        entityId2:
          description: >-
            The entity ID of the second entity.
          nullable: false
          type: integer
          format: int64
        matchInfo:
          description: >-
            The `SzWhyMatchInfo` providing the details of the result.
          nullable: false
          $ref: '#/components/schemas/SzWhyMatchInfo'
    SzWhyRecordsResult:
      description: >-
        Describes why two records might resolve.
      type: object
      properties:
        perspective1:
          description: >-
            The `SzWhyPerspective` identifying and describing the perspective
            from the first record.
          $ref: '#/components/schemas/SzWhyPerspective'
        perspective2:
          description: >-
            The `SzWhyPerspective` identifying and describing the perspective
            from the second record.
          $ref: '#/components/schemas/SzWhyPerspective'
        matchInfo:
          description: >-
            The `SzWhyMatchInfo` providing the details of the result.
          nullable: false
          $ref: '#/components/schemas/SzWhyMatchInfo'
    SzHowMatchInfo:
      description: >-
        The match info describing how a step in an entity's resolution completed
        and why the two virtual entities were resolved.
      type: object
      properties:
        matchKey:
          description: >-
            The match key indicating the components of the match.
          nullable: false
          type: string
        resolutionRule:
          description: >-
            The resolution rule that triggered the match.
          nullable: true
          type: string
        featureScores:
          description: >-
            The map of feature types to arrays of `SzFeatureScore` instances
            for that feature type.
          nullable: true
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/SzFeatureScore'
    SzVirtualEntityRecord:
      description: >-
        Describes a record that belongs to a virtual entity.  This identifies
        the record as well as its internal ID to understand which records in
        the virtual entity are considered to be duplicates of each other.
      type: object
      properties:
        dataSource:
          description: >-
            The data source code that uniquely identifies the data source
            associated with the record.
          type: string
          nullable: false
        recordId:
          description: >-
            The record ID that uniquely identifies a record within the
            respective data source.
          type: string
          nullable: false
        internalId:
          description: >-
            The unique internal ID for the record.  Those records having the
            same value for this field are effectively identical for the purpose
            of entity resolution and automatically bound together.
          type: string
          nullable: false
    SzVirtualEntity:
      description: >-
        Describes a virtual entity that describes an interim resolution step
        for an actual entity.  Virtual entities that consist of a single record
        (or multiple "identical" records) are considered singletons and are the
        initial building blocks in how an entity is resolved.  Those with
        multiple distinct records are compound virtual entities formed from
        resolving two virtual entities.
      type: object
      properties:
        virtualEntityId:
          description: >-
            The unique identifier that distinguishes this virtual entity from
            all other virtual entities among all steps in a "how" result.
          type: string
          nullable: false
        singleton:
          description: >-
            Indicates if the virtual entity consists of a a single record or
            one or more effectively identical records (i.e.: with the same
            internal ID) with a value of `true`.  If this virtual entity
            comprises multiple distinct records then this is `false`.
          type: boolean
          nullable: false
        records:
          description: >-
            The array of `SzVirtualEntityRecords` identifying the constituent
            records of the virtual entity.  Those records in the array with the
            same `internalId` property are effectively identical for the
            purposes of entity resolution.
          type: array
          items:
            $ref: '#/components/schemas/SzVirtualEntityRecord'
    SzResolutionStep:
      description: >-
        Describes a single step in describing how an entity was created.  Each
        step consists of either the formation of a new "virtual entity" from
        two records, the adding of a record to an existing virtual entity to
        create a new virtual entity, or the resolving of two virtual entities
        into a new virtual entity consisting of all the records.
      type: object
      properties:
        stepNumber:
          description: >-
            The step number indicating the order of this step relative to other
            steps if the steps were flattened to be linear.  However, the
            non-linear nature of entity resolution means that the ordering of
            the steps is only relevant within a single branch of the resolution
            tree.
          type:  integer
          format: int32
          nullable: false
        inboundVirtualEntity:
          description: >-
            The `SzVirtualEntity` describing the inbound virtual entity.
          nullable: false
          $ref: '#/components/schemas/SzVirtualEntity'
        candidateVirtualEntity:
          description: >-
            The `SzVirtualEntity` describing the candidate virtual entity.
          nullable: false
          $ref: '#/components/schemas/SzVirtualEntity'
        matchInfo:
          description: >-
            The `SzHowMatchInfo` describing how the two virtual entities
            matched each other.
          nullable: false
          $ref: '#/components/schemas/SzHowMatchInfo'
        resolvedVirtualEntityId:
          description: >-
            The virtual entity ID identifying the virtual entity that resulted
            from resolving the inbound and candidate virtual entities.
          nullable: false
          type: string
    SzHowEntityResult:
      description: >-
        Describes the result of the "how entity" operation as a mapping of
        non-singleton virtual entity ID's to their corresponding
        `SzResolutionStep` instances as well as an array of `SzVirtualEntity`
        instances describing the possible final states for the entity.
        **NOTE**: If there are more than one possible final states then the
        entity requires reevaluation, while a result with a single final state
        does not require reevaluation.
      type: object
      properties:
        finalStates:
          description: >-
            The array of `SzVirtualEntity` instances describing the possible
            final states for the entity.  If there are more than one elements
            in the array then the entity requires reevaluation.  If there is
            only a single element in the array, then reevaluation is not
            required.  This array will always have at least one element.
          nullable: false
          type: array
          items:
            $ref: '#/components/schemas/SzVirtualEntity'
        resolutionSteps:
          description: >-
            The map of virtual entity ID's for non-singleton virtual entities
            to `SzResolutionStep` instances describing how the virtual entity 
            for the respective virtual entity ID was formed.  Since singleton
            virtual entities are base building blocks, they do not have an
            associated how step.  They are simply formed by the loading of a
            record to the repository.
          nullable: false
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SzResolutionStep'
    SzHowEntityResponse:
      description: >-
        The response describing the result of the "how entity" operation.
      allOf:
        - $ref: '#/components/schemas/SzResponseWithRawData'
        - type: object
          properties:
            data:
              description: >-
                The data field is the `SzHowEntityResult` itself.
              $ref: '#/components/schemas/SzHowEntityResult'
tags:
  - name: Admin
    description: Administrative operations.
  - name: Config
    description: Configuration operations.
  - name: Entity Data
    description: Entity and record data operations.
  - name: Entity Graph
    description: Entity relationship connections for graphing.
  - name: Bulk Data
    description: Preparation and loading of bulk data.