From 7afd7130cca84b84ae54eb5a07a42fb170a578ce Mon Sep 17 00:00:00 2001 From: Ara Winters Date: Mon, 14 Sep 2020 16:33:34 -0700 Subject: [PATCH] #39 updated CHANGELOG, travis.yml, api yaml. --- .travis.yml | 3 +- CHANGELOG.md | 12 + senzing-api.yaml | 5819 ++++++++++++++++++++++++++++++++++++++++------ 3 files changed, 5065 insertions(+), 769 deletions(-) diff --git a/.travis.yml b/.travis.yml index a664a31..5b7aa81 100644 --- a/.travis.yml +++ b/.travis.yml @@ -16,7 +16,7 @@ cache: install: - travis_wait npm install - - travis_wait npm install -g @angular/cli@7.1.4 + - travis_wait npm install -g @angular/cli@10.0.0 - ng version # - chromedriver --version @@ -27,4 +27,3 @@ script: - npm run test:headless - npm run build:docs - npm run build -# - npm run e2e:headless diff --git a/CHANGELOG.md b/CHANGELOG.md index 69f840a..1245fe0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), [markdownlint](https://dlaa.me/markdownlint/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## 2.1.0 + +Compatibility release for framework upgrade to Angular 10: see [https://blog.angular.io/version-10-of-angular-now-available-78960babd41](https://blog.angular.io/version-10-of-angular-now-available-78960babd41) + +Major updates to most dependency versions have also been made which should improve file sizes, security, and stability. + +The following Senzing projects have also been updated to operate on Angular 10, +see the following links for associated tickets: +- [sdk-components-ng/issues/143](https://github.com/Senzing/sdk-components-ng/issues/143) +- [rest-api-client-ng/issues/39](https://github.com/Senzing/rest-api-client-ng/issues/39) +- [sdk-graph-components/issues/37](https://github.com/Senzing/sdk-graph-components/issues/37) + ## 2.0.0 - 2020-07-06 ### Added to 2.0.0 diff --git a/senzing-api.yaml b/senzing-api.yaml index 8e37e6a..5d379d4 100644 --- a/senzing-api.yaml +++ b/senzing-api.yaml @@ -1,12 +1,40 @@ openapi: 3.0.1 info: title: Senzing REST API - version: "1.4" + version: "2.0.0" 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). +

+ NOTE: 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 + the similarly to its stand 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`) [https://docs.senzing.com](https://docs.senzing.com) + +servers: + - url: http://localhost:8250 + - url: '{protocol}://{host}:{port}' + variables: + protocol: + enum: + - http + - https + default: http + host: + default: localhost + port: + default: '8250' + paths: /heartbeat: get: @@ -35,6 +63,8 @@ paths: - Admin summary: Get the license information. operationId: license + parameters: + - $ref: '#/components/parameters/withRawQueryParam' responses: '200': description: Successful response @@ -48,12 +78,12 @@ paths: default: schema: $ref: '#/components/schemas/SzLicenseResponse' - /data-sources: + /version: get: tags: - - Config - summary: Get a list of configured data sources. - operationId: listDataSources + - Admin + summary: Get the full version information. + operationId: version parameters: - $ref: '#/components/parameters/withRawQueryParam' responses: @@ -62,84 +92,180 @@ paths: content: application/json; charset=UTF-8: schema: - $ref: '#/components/schemas/SzDataSourcesResponse' + $ref: '#/components/schemas/SzVersionResponse' application/json: schema: - $ref: '#/components/schemas/SzDataSourcesResponse' + $ref: '#/components/schemas/SzVersionResponse' default: schema: - $ref: '#/components/schemas/SzDataSourcesResponse' - '5XX': - $ref: '#/components/responses/ServerError' - /data-sources/{dataSourceCode}/records/{recordId}: + $ref: '#/components/schemas/SzVersionResponse' + /server-info: get: tags: - - Entity Data - summary: Get an entity record by data source and record ID. - operationId: getDataSourceRecord - parameters: - - $ref: '#/components/parameters/dataSourceCodePathParam' - - $ref: '#/components/parameters/recordIdPathParam' - - $ref: '#/components/parameters/withRawQueryParam' + - Admin + summary: Get info regarding the server's state and supported features. + operationId: getServerInfo responses: '200': - description: Successul response + description: Successful response content: application/json; charset=UTF-8: schema: - $ref: '#/components/schemas/SzRecordResponse' + $ref: '#/components/schemas/SzServerInfoResponse' application/json: schema: - $ref: '#/components/schemas/SzRecordResponse' + $ref: '#/components/schemas/SzServerInfoResponse' default: schema: - $ref: '#/components/schemas/SzRecordResponse' - '404': - description: If data source or record ID are not found. + $ref: '#/components/schemas/SzServerInfoResponse' + /attribute-types: + get: + tags: + - Config + summary: Get a list of configured attribute types. + 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/SzErrorResponse' + $ref: '#/components/schemas/SzAttributeTypesResponse' application/json: schema: - $ref: '#/components/schemas/SzErrorResponse' + $ref: '#/components/schemas/SzAttributeTypesResponse' default: schema: - $ref: '#/components/schemas/SzErrorResponse' - '5XX': + $ref: '#/components/schemas/SzAttributeTypesResponse' + '500': $ref: '#/components/responses/ServerError' - /entities/{entityId}: + /attribute-types/{attributeCode}: get: tags: - - Entity Data - summary: Get a resolved entity by entity ID. - operationId: getEntityByEntityId + - Config + summary: Get the attribute type identified by the attribute code. + operationId: getAttributeType 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/withRelatedQueryParam' - - $ref: '#/components/parameters/withRawQueryParam' + - 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/SzEntityResponse' + $ref: '#/components/schemas/SzAttributeTypeResponse' application/json: schema: - $ref: '#/components/schemas/SzEntityResponse' + $ref: '#/components/schemas/SzAttributeTypeResponse' default: schema: - $ref: '#/components/schemas/SzEntityResponse' + $ref: '#/components/schemas/SzAttributeTypeResponse' '404': - description: If the entity ID is not found. + description: >- + If the specified attribute code is not recognized. content: application/json; charset=UTF-8: schema: @@ -150,34 +276,172 @@ paths: default: schema: $ref: '#/components/schemas/SzErrorResponse' - '5XX': + '500': $ref: '#/components/responses/ServerError' - /data-sources/{dataSourceCode}/records/{recordId}/entity: + /data-sources: get: tags: - - Entity Data - summary: Get a resolved entity by data source and record ID. - operationId: getEntityByRecordId + - Config + summary: Get a list of configured data sources. + operationId: getDataSources parameters: - - $ref: '#/components/parameters/dataSourceCodePathParam' - - $ref: '#/components/parameters/recordIdPathParam' - - $ref: '#/components/parameters/withRelatedQueryParam' - $ref: '#/components/parameters/withRawQueryParam' responses: '200': - description: default response + description: Successful response content: application/json; charset=UTF-8: schema: - $ref: '#/components/schemas/SzEntityResponse' + $ref: '#/components/schemas/SzDataSourcesResponse' application/json: schema: - $ref: '#/components/schemas/SzEntityResponse' + $ref: '#/components/schemas/SzDataSourcesResponse' default: schema: - $ref: '#/components/schemas/SzEntityResponse' - '404': - description: If data source or record ID are not found. + $ref: '#/components/schemas/SzDataSourcesResponse' + '500': + $ref: '#/components/responses/ServerError' + post: + tags: + - Config + summary: >- + 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. + 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: @@ -188,166 +452,233 @@ paths: default: schema: $ref: '#/components/schemas/SzErrorResponse' - '5XX': + '500': $ref: '#/components/responses/ServerError' - /entities: + /data-sources/{dataSourceCode}: get: tags: - - Entity Data - summary: >- - Search for entities that would match or relate to the provided - entity features. - operationId: searchByAttributes + - Config + summary: Gets the details on the specified data source. + operationId: getDataSource parameters: - - name: attrs - description: >- - The record JSON describing the entity attributes in the same - format as how an entity record would be loaded. The specified - attributes will be treated as a hypothetical record being loaded - and the result will be anything that would have matched or related - to it. - in: query - required: true - schema: - type: object - additionalProperties: {} - example: >- - { - "NAME_TYPE": "PRIMARY", - "NAME_FIRST": "JANE", - "NAME_LAST": "SMITH", - "ADDR_TYPE": "HOME", - "ADDR_LINE1": "653 STATE ROUTE 7", - "ADDR_CITY": "FRESNO", - "ADDR_STATE": "CA", - "ADDR_POSTAL_CODE": "55073-1234" - } - - $ref: '#/components/parameters/withRawQueryParam' + - $ref: '#/components/parameters/dataSourceCodePathParam' + - $ref: '#/components/parameters/withRawQueryParam' responses: '200': description: Successful response content: application/json; charset=UTF-8: schema: - $ref: '#/components/schemas/SzAttributeSearchResponse' + $ref: '#/components/schemas/SzDataSourceResponse' application/json: schema: - $ref: '#/components/schemas/SzAttributeSearchResponse' + $ref: '#/components/schemas/SzDataSourceResponse' default: schema: - $ref: '#/components/schemas/SzAttributeSearchResponse' - '400': + $ref: '#/components/schemas/SzDataSourceResponse' + '500': + $ref: '#/components/responses/ServerError' + /entity-types: + get: + tags: + - Config + summary: Get a list of configured entity types. + operationId: getEntityTypes + parameters: + - name: entityClass description: >- - If the specified attrs parameter is missing or is not formatted - properly. + If specified, this filters the list of returned entity types to + those having the specified entity class. If not specified then no + filtering on entity class is performed and all are returned. At + this time, the only supported entity class is `ACTOR`, however, + in the future this will change. + in: query + required: false + schema: + type: string + examples: + ACTOR: + summary: >- + ACTOR (e.g.: people, companies or organizations). + value: ACTOR + - $ref: '#/components/parameters/withRawQueryParam' + responses: + '200': + description: Successful response content: application/json; charset=UTF-8: schema: - $ref: '#/components/schemas/SzErrorResponse' + $ref: '#/components/schemas/SzEntityTypesResponse' application/json: schema: - $ref: '#/components/schemas/SzErrorResponse' + $ref: '#/components/schemas/SzEntityTypesResponse' default: schema: - $ref: '#/components/schemas/SzErrorResponse' - '5XX': + $ref: '#/components/schemas/SzEntityTypesResponse' + '500': $ref: '#/components/responses/ServerError' - /entity-paths: - get: + post: tags: - - Entity Graph + - Config summary: >- - Finds a path between two entities identified by entity ID or by - data sources and record IDs of constituent records. You may provide - entity IDs or data source and record IDs to identify the from/to - entities in the path, but you may not mix and match. - operationId: findPathByEntityID + Obtains the current default configuration, adds the specified entity + types and sets the modified configuration as the new default + configuration -- returning the set of all configured entity types. + operationId: addEntityTypes parameters: - - name: from - description: >- - The EntityIdentifier for the first entity for the path either as an - entity ID or a JSON-encoded RecordId for the constituent record. - Whatever format is used for the "from" parameter must match the - format of the "to" parameter. - in: query - required: true - schema: - $ref: '#/components/schemas/SzEntityIdentifier' - - name: to - description: >- - The EntityIdentifier for the last entity for the path either as an - entity ID or a JSON-encoded record ID for the constituent record. - Whatever format is used for the "to" parameter must match the - format of the "from" parameter. - in: query - required: true - schema: - $ref: '#/components/schemas/SzEntityIdentifier' - - name: maxDegrees - description: >- - The maximum number of degrees to look for a path from the first - entity to the last entity. - in: query - required: false - schema: - type: integer - format: int8 - minimum: 0 - maximum: 100 - default: 3 - - name: x - description: >- - Multi-valued query parameter containing EntityIdentifier 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 RecordId instances identifying records that are part of the - resolved entities to avoid. If this parameter is not provided, then - the default is to NOT exclude any entities. - in: query - required: false - schema: - $ref: '#/components/schemas/SzEntityIdentifiers' - - 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 + - name: entityType + description: >- + The multi-valued query parameter where each value is an entity type + code identifying entity types to be created. + in: query + required: false + style: form + explode: true + schema: + type: array + items: + type: string + examples: + singleDataSourceExample: + summary: Specify a single entity type + value: [ VEHICLE ] + multipleDataSourcesExample: + summary: Specify multiple entity types + value: [ VEHICLE, VESSEL ] + - name: entityClass + description: | + The optional single-valued query parameter to specify the entity + class to use for all created entity types (i.e.: it is associated + with all values of `entityType` specified). This defaults to a + value of `ACTOR` which is the only valid value at this time. In + the future additional values may be allowed. + + *NOTE*: In the future, when other values are allowed and if creating + entity types with different classes then you can fully described + each entity type with its class using an array of `SzEntityType` + objects in the request body. + in: query + required: false + schema: + type: string + default: ACTOR + examples: + ACTOR: + summary: >- + ACTOR (e.g.: people, companies or organizations). + value: ACTOR + requestBody: 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 + The optional request body to describe the entity types to be created. + This can be specified as an alternative to the `entityType` parameter + or in addition to it. The content must be an array of string entity + type codes or `SzEntityType` objects. It may also be a plain-text + unquoted string that is simply a single entity type code. required: false - schema: - type: array - items: - type: string - - $ref: '#/components/parameters/withRawQueryParam' + content: + application/json; charset=UTF-8: + schema: + oneOf: + - type: array + items: + $ref: '#/components/schemas/SzEntityTypeDescriptor' + - $ref: '#/components/schemas/SzEntityTypeDescriptor' + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + noEntityTypes: + $ref: '#/components/examples/noEntityTypes' + singleTypeString: + $ref: '#/components/examples/singleEntityTypeString' + singleTypeStringArray: + $ref: '#/components/examples/singleEntityTypeStringArray' + multipleTypesStringArray: + $ref: '#/components/examples/multipleEntityTypesStringArray' + singleTypeObjectNoId: + $ref: '#/components/examples/singleEntityTypeObjectNoId' + singleTypeObjectArrayNoId: + $ref: '#/components/examples/singleEntityTypeObjectArrayNoId' + singleTypeObjectWithId: + $ref: '#/components/examples/singleEntityTypeObjectWithId' + singleTypeObjectArrayWithId: + $ref: '#/components/examples/singleEntityTypeObjectArrayWithId' + multipleTypesObjectArrayWithId: + $ref: '#/components/examples/multipleEntityTypesObjectArrayWithId' + multipleTypesObjectArrayWithIdAndClass: + $ref: '#/components/examples/multipleEntityTypesObjectArrayWithIdAndClass' + multipleTypesMixed: + $ref: '#/components/examples/multipleEntityTypesMixed' + application/json: + schema: + oneOf: + - type: array + items: + $ref: '#/components/schemas/SzEntityTypeDescriptor' + - $ref: '#/components/schemas/SzEntityTypeDescriptor' + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + noEntityTypes: + $ref: '#/components/examples/noEntityTypes' + singleTypeString: + $ref: '#/components/examples/singleEntityTypeString' + singleTypeStringArray: + $ref: '#/components/examples/singleEntityTypeStringArray' + multipleTypesStringArray: + $ref: '#/components/examples/multipleEntityTypesStringArray' + singleTypeObjectNoId: + $ref: '#/components/examples/singleEntityTypeObjectNoId' + singleTypeObjectArrayNoId: + $ref: '#/components/examples/singleEntityTypeObjectArrayNoId' + singleTypeObjectWithId: + $ref: '#/components/examples/singleEntityTypeObjectWithId' + singleTypeObjectArrayWithId: + $ref: '#/components/examples/singleEntityTypeObjectArrayWithId' + multipleTypesObjectArrayWithId: + $ref: '#/components/examples/multipleEntityTypesObjectArrayWithId' + multipleTypesObjectArrayWithIdAndClass: + $ref: '#/components/examples/multipleEntityTypesObjectArrayWithIdAndClass' + multipleTypesMixed: + $ref: '#/components/examples/multipleEntityTypesMixed' + text/plain; charset=UTF=8: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + noEntityTypes: + $ref: '#/components/examples/noEntityTypes' + singleTypeUnquotedString: + $ref: '#/components/examples/singleEntityTypeUnquotedString' + text/plain: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + noEntityTypes: + $ref: '#/components/examples/noEntityTypes' + singleTypeUnquotedString: + $ref: '#/components/examples/singleEntityTypeUnquotedString' responses: '200': description: Successful response content: application/json; charset=UTF-8: schema: - $ref: '#/components/schemas/SzEntityPathResponse' + $ref: '#/components/schemas/SzEntityTypesResponse' application/json: schema: - $ref: '#/components/schemas/SzEntityPathResponse' + $ref: '#/components/schemas/SzEntityTypesResponse' default: schema: - $ref: '#/components/schemas/SzEntityPathResponse' - '400': + $ref: '#/components/schemas/SzEntityTypesResponse' + '403': description: >- - If the 'from' or 'to' parameters are missing or if any of the - parameters are not formatted as expected. + 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: @@ -358,86 +689,248 @@ paths: default: schema: $ref: '#/components/schemas/SzErrorResponse' - '5XX': + '500': $ref: '#/components/responses/ServerError' - /entity-networks: + /entity-types/{entityTypeCode}: get: tags: - - Entity Graph - summary: >- - Finds the entity network around one or more entities identified by - their entity IDs or by the data source codes and record ID's of their - constituent records. 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. - operationId: findNetworkByEntityID + - Config + summary: Gets the details on the specified entity type. + operationId: getEntityType parameters: - - name: e - description: >- - The multi-valued query parameter where each value is formatted as an - EntityIdentifier which may be 64-bit integer entity IDs or - JSON-encoded RecordId for the constituent records. The format for - all of the provided identifiers must be the same (i.e.: all entity - IDs or all data-source / record-id combos). - in: query - required: true - schema: - $ref: '#/components/schemas/SzEntityIdentifiers' - - name: maxDegrees - description: >- - The maximum number of degrees to look for a path between the - specified entities. - in: query - required: false - schema: - type: integer - format: int8 - minimum: 0 - maximum: 100 - default: 5 - - 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. - in: query - required: false - schema: - type: integer - format: int8 - minimum: 0 - maximum: 100 - default: 1 - - name: maxEntities + - $ref: '#/components/parameters/entityTypeCodePathParam' + - $ref: '#/components/parameters/withRawQueryParam' + responses: + '200': + description: Successful response + content: + application/json; charset=UTF-8: + schema: + $ref: '#/components/schemas/SzEntityTypeResponse' + application/json: + schema: + $ref: '#/components/schemas/SzEntityTypeResponse' + default: + schema: + $ref: '#/components/schemas/SzEntityTypeResponse' + '500': + $ref: '#/components/responses/ServerError' + /entity-classes: + get: + tags: + - Config + summary: >- + Get a list of configured entity classes. Currently the only supported + entity class is `ACTOR`. + operationId: getEntityClasses + parameters: + - $ref: '#/components/parameters/withRawQueryParam' + responses: + '200': + description: Successful response + content: + application/json; charset=UTF-8: + schema: + $ref: '#/components/schemas/SzEntityClassesResponse' + application/json: + schema: + $ref: '#/components/schemas/SzEntityClassesResponse' + default: + schema: + $ref: '#/components/schemas/SzEntityClassesResponse' + '500': + $ref: '#/components/responses/ServerError' + /entity-classes/{entityClassCode}: + get: + tags: + - Config + summary: >- + Gets the details on the specified entity class. NOTE: Currently the + only supported entity class is `ACTOR`, but this will change in the + future. + operationId: getEntityClass + parameters: + - $ref: '#/components/parameters/entityClassCodePathParam' + - $ref: '#/components/parameters/withRawQueryParam' + responses: + '200': + description: Successful response + content: + application/json; charset=UTF-8: + schema: + $ref: '#/components/schemas/SzEntityClassResponse' + application/json: + schema: + $ref: '#/components/schemas/SzEntityClassResponse' + default: + schema: + $ref: '#/components/schemas/SzEntityClassResponse' + '500': + $ref: '#/components/responses/ServerError' + /entity-classes/{entityClassCode}/entity-types: + get: + tags: + - Config + summary: >- + Get a list of configured entity types for the identified entity class. + NOTE: Currently the only supported entity class is `ACTOR`, but this + will change in the future. + operationId: getEntityTypesByClass + parameters: + - $ref: '#/components/parameters/entityClassCodePathParam' + - $ref: '#/components/parameters/withRawQueryParam' + responses: + '200': + description: Successful response + content: + application/json; charset=UTF-8: + schema: + $ref: '#/components/schemas/SzEntityTypesResponse' + application/json: + schema: + $ref: '#/components/schemas/SzEntityTypesResponse' + default: + schema: + $ref: '#/components/schemas/SzEntityTypesResponse' + '500': + $ref: '#/components/responses/ServerError' + post: + tags: + - Config + summary: >- + Obtains the current default configuration, adds the specified entity + types and sets the modified configuration as the new default + configuration -- returning the set of all configured entity types. + operationId: addEntityTypesForClass + parameters: + - $ref: '#/components/parameters/entityClassCodePathParam' + - name: entityType + description: >- + The multi-valued query parameter where each value is an entity type + code identifying entity types to be created. + in: query + required: false + style: form + explode: true + schema: + type: array + items: + type: string + examples: + singleDataSourceExample: + summary: Specify a single entity type + value: [ VEHICLE ] + multipleDataSourcesExample: + summary: Specify multiple entity types + value: [ VEHICLE, VESSEL ] + requestBody: description: >- - The maximum number of entities to return to prevent responses - that are too large. - in: query + The optional request body to describe the entity types to be created. + This can be specified as an alternative to the `entityType` parameter + or in addition to it. The content must be an array of `SzEntityType` + objects and the entity classes in the `SzEntityType` objects must + match the entity class in the path. required: false - schema: - type: integer - format: int32 - minimum: 0 - default: 1000 - - $ref: '#/components/parameters/withRawQueryParam' + content: + application/json; charset=UTF-8: + schema: + type: array + items: + $ref: '#/components/schemas/SzEntityTypeDescriptor' + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + noEntityTypes: + $ref: '#/components/examples/noEntityTypes' + singleTypeString: + $ref: '#/components/examples/singleEntityTypeString' + singleTypeStringArray: + $ref: '#/components/examples/singleEntityTypeStringArray' + multipleTypesStringArray: + $ref: '#/components/examples/multipleEntityTypesStringArray' + singleTypeObjectNoId: + $ref: '#/components/examples/singleEntityTypeObjectNoId' + singleTypeObjectArrayNoId: + $ref: '#/components/examples/singleEntityTypeObjectArrayNoId' + singleTypeObjectWithId: + $ref: '#/components/examples/singleEntityTypeObjectWithId' + singleTypeObjectArrayWithId: + $ref: '#/components/examples/singleEntityTypeObjectArrayWithId' + multipleTypesObjectArrayWithId: + $ref: '#/components/examples/multipleEntityTypesObjectArrayWithId' + multipleTypesObjectArrayWithIdAndClass: + $ref: '#/components/examples/multipleEntityTypesObjectArrayWithIdAndClass' + multipleTypesMixed: + $ref: '#/components/examples/multipleEntityTypesMixed' + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/SzEntityTypeDescriptor' + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + noEntityTypes: + $ref: '#/components/examples/noEntityTypes' + singleTypeString: + $ref: '#/components/examples/singleEntityTypeString' + singleTypeStringArray: + $ref: '#/components/examples/singleEntityTypeStringArray' + multipleTypesStringArray: + $ref: '#/components/examples/multipleEntityTypesStringArray' + singleTypeObjectNoId: + $ref: '#/components/examples/singleEntityTypeObjectNoId' + singleTypeObjectArrayNoId: + $ref: '#/components/examples/singleEntityTypeObjectArrayNoId' + singleTypeObjectWithId: + $ref: '#/components/examples/singleEntityTypeObjectWithId' + singleTypeObjectArrayWithId: + $ref: '#/components/examples/singleEntityTypeObjectArrayWithId' + multipleTypesObjectArrayWithId: + $ref: '#/components/examples/multipleEntityTypesObjectArrayWithId' + multipleTypesObjectArrayWithIdAndClass: + $ref: '#/components/examples/multipleEntityTypesObjectArrayWithIdAndClass' + multipleTypesMixed: + $ref: '#/components/examples/multipleEntityTypesMixed' + text/plain; charset=UTF=8: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + noEntityTypes: + $ref: '#/components/examples/noEntityTypes' + singleTypeUnquotedString: + $ref: '#/components/examples/singleEntityTypeUnquotedString' + text/plain: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + noEntityTypes: + $ref: '#/components/examples/noEntityTypes' + singleTypeUnquotedString: + $ref: '#/components/examples/singleEntityTypeUnquotedString' responses: '200': description: Successful response content: application/json; charset=UTF-8: schema: - $ref: '#/components/schemas/SzEntityNetworkResponse' + $ref: '#/components/schemas/SzEntityTypesResponse' application/json: schema: - $ref: '#/components/schemas/SzEntityNetworkResponse' + $ref: '#/components/schemas/SzEntityTypesResponse' default: schema: - $ref: '#/components/schemas/SzEntityNetworkResponse' - '400': + $ref: '#/components/schemas/SzEntityTypesResponse' + '403': description: >- - If the 'entityIds' parameters is missing or if any of the - parameters are not formatted as expected. + 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: @@ -448,127 +941,2726 @@ paths: default: schema: $ref: '#/components/schemas/SzErrorResponse' - '5XX': + '500': $ref: '#/components/responses/ServerError' -components: - 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: >- - Whether or not to pull the complete features and records for - first-degree related entities (i.e.: the RelatedEntity instances - will have the "partial" flag set to true rather than false). If - false, then all returned RelatedEntity instances will only contain - partial data (the default). - schema: - type: boolean - default: false - dataSourceCodePathParam: - in: path - name: dataSourceCode - required: true - description: >- - The data source code identifying the data source with which - the requested record is associated. - schema: - type: string - 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 - 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: - SzBaseResponse: - description: >- - Represents the base information included in all responses sans the - actual data for the response. - type: object - properties: - meta: - type: object - properties: - httpMethod: - type: string - enum: - - GET - - POST - - PUT - - PATCH - - DELETE - httpStatusCode: - type: integer - format: int16 - timestamp: - type: string - format: date-time - links: - type: object - properties: - self: - type: string - SzErrorResponse: - 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. + /entity-classes/{entityClassCode}/entity-types/{entityTypeCode}: + get: + tags: + - Config + summary: Gets the details on the specified entity type. + operationId: getEntityTypeByClass + parameters: + - $ref: '#/components/parameters/entityClassCodePathParam' + - $ref: '#/components/parameters/entityTypeCodePathParam' + - $ref: '#/components/parameters/withRawQueryParam' + responses: + '200': + description: Successful response + content: + application/json; charset=UTF-8: + schema: + $ref: '#/components/schemas/SzEntityTypeResponse' + application/json: + schema: + $ref: '#/components/schemas/SzEntityTypeResponse' + default: + schema: + $ref: '#/components/schemas/SzEntityTypeResponse' + '500': + $ref: '#/components/responses/ServerError' + /configs/active: + get: + tags: + - Config + summary: >- + Gets the current active configuration as raw JSON, no interpretation. + 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. + 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. + 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 - nullable: true additionalProperties: {} - SzLicenseResponse: + 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. + 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. + 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. + 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. + 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. + operationId: getEntityByRecordId + parameters: + - $ref: '#/components/parameters/dataSourceCodePathParam' + - $ref: '#/components/parameters/recordIdPathParam' + - $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. + 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/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' + /entities: + get: + tags: + - Entity Data + summary: >- + Search for entities that would match or relate to the provided + entity features. + operationId: searchByAttributes + 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: + summary: Social security number + value: >- + { + "SSN_NUMBER": "111-22-3333" + } + nameAndBirthDateExample: + summary: Name and date of birth + value: >- + { + "NAME_FULL": "JANE SMITH", + "DATE_OF_BIRTH": "03-SEP-1987" + } + nameAndAddressExample: + 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" + } + - 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/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' + /entities/{entityId}: + get: + tags: + - Entity Data + summary: Get a resolved entity by entity ID. + 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/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. + 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/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' + /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. + 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/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' + /reevaluate-entity: + post: + tags: + - Entity Data + summary: Reevaluate an entity identified by its entity ID. + 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' + /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. You may provide + entity IDs or data source and record IDs to identify the from/to + entities in the path, but you may not mix and match. + 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. + in: query + required: false + schema: + type: integer + format: int8 + minimum: 0 + maximum: 100 + 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/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 identified by + their entity IDs or by the data source codes and record ID's of their + constituent records. 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. + 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`. + in: query + required: false + schema: + type: integer + format: int8 + minimum: 0 + maximum: 100 + 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/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 the 'e' entity identifiers parameter is 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' + /bulk-data/analyze: + post: + tags: + - Bulk Data + summary: Analyze a bulk data set of records. (Supports SSE) + operationId: analyzeBulkRecords + parameters: + - $ref: '#/components/parameters/progressPeriodParam' + 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: + application/x-jsonlines; charset=UTF-8: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + bulkDataJsonLinesExample: + $ref: '#/components/examples/bulkDataJsonLinesExample' + application/x-jsonlines: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + bulkDataJsonLinesExample: + $ref: '#/components/examples/bulkDataJsonLinesExample' + application/json; charset=UTF-8: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + bulkDataJsonExample: + $ref: '#/components/examples/bulkDataJsonExample' + application/json: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + bulkDataJsonExample: + $ref: '#/components/examples/bulkDataJsonExample' + 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' + 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' + 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) + 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: entityType + description: >- + Used to set the overriding entity type for the records. This entity + type will be assigned to every record **unless** the record's + entity type (including blank entity type) has a specific mapping + specified by a `mapEntityTypes` or `mapEntityType` parameters. If + this parameter is **not** provided and no specific overrides are + provided for a record then the entity type specified in the inbound + record is used directly. If the record has no entity type and no + override is provided then `GENERIC` will be used. + in: query + required: false + schema: + type: string + examples: + GENERIC: + value: GENERIC + PERSON: + value: PERSON + COMPANY: + value: COMPANY + - name: mapEntityTypes + description: | + A URL-encoded JSON object whose properties are interpreted as + entity type codes to map from and whose corresponding values are + interpretted as entity type codes to map to. For example, + `{"COMPANY": "ORGANIZATION"}` (url-encoded of course) would map all + records with inbound entity type `COMPANY` to `ORGANIZATION`. To + map only inbound records with no entity type to a specific entity + type you would use an empty JSON property (e.g.: `{"": "PERSON"}`). + If the `entityType` parameter is **not** provided and no specific + overrides are provided for a record with this parameter or via + `mapEntityType` then the entity type specified in the inbound + record is used directly. If the record has no entity type and no + overriding or mapped entity type is provided for an empty entity + type then `GENERIC` will be used. + + **NOTE**: If both this parameter and the `mapEntityType` parameter + is provided then the mappings are merged with the more ad-hoc + `mapEntityType` 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 entityTypeMap = { + "": "PERSON", + "ORG": "ORGANIZATION", + "COMP": "ORGANIZATION" + }; + var mapEntityTypes = JSON.stringify(entityTypeMap); + var urlPath = "/bulk-data/load?mapEntityTypes=" + + encodeURIComponent(mapEntityTypes); + ``` + + - **Java Example** + ```java + JsonObjectBuilder builder = Json.createObjectBuilder(); + builder.add("", "PERSON"); + builder.add("ORG", "ORGANIZATION"); + builder.add("COMP", "ORGANIZATION"); + JsonObject entityTypeMap = builder.build(); + + String mapEntityTypes = entityTypeMap.toString(); + String encodedMap = URLEncoder.encode(mapEntityTypes, "UTF-8"); + String urlPath = "/bulk-data/load?mapEntityTypes=" + encodedMap; + ``` + + In both of the above examples the `urlPath` variable is set to: + ```json + + /bulk-data/load?mapEntityTypes=%7B%22%22%3A%22PERSON%22%2C%22ORG%22%3A%22ORGANIZATION%22%2C%22COMP%22%3A%22ORGANIZATION%22%7D + + ``` + in: query + required: false + schema: + type: string + examples: + notSpecifiedExample: + summary: Not specified + value: + mapEmptyExample: + summary: Single mapping for missing entity types + value: >- + { + "": "PERSON" + } + mapMultipleExample: + summary: Multiple entity type mappings + value: >- + { + "": "PERSON", + "ORG": "ORGANIZATION", + "COMP": "ORGANIZATION" + } + - name: mapEntityType + description: | + As an alternative to the `mapEntityTypes` parameter you may specify + the `mapEntityType` 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 entity type and no + overriding or mapped entity type is provided for an empty entity + type then `GENERIC` will be used. + 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: [ ":COMP:COMPANY" ] + multipleSpecificOverridesExample: + summary: Map multiple specific data sources + value: [ ":COMP:COMPANY", ":ORG:ORGANIZATION" ] + multipleSpecificOverridesWithEmptyExample: + summary: Map multiple specific data sources with empty mapping + value: [ "::GENERIC", ":COMP:COMPANY", ":ORG:ORGANIZATION" ] + - $ref: '#/components/parameters/progressPeriodParam' + 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: + application/x-jsonlines; charset=UTF-8: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + bulkDataJsonLinesExample: + $ref: '#/components/examples/bulkDataJsonLinesExample' + application/x-jsonlines: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + bulkDataJsonLinesExample: + $ref: '#/components/examples/bulkDataJsonLinesExample' + application/json; charset=UTF-8: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + bulkDataJsonExample: + $ref: '#/components/examples/bulkDataJsonExample' + application/json: + schema: + type: string + examples: + chooseExample: + $ref: '#/components/examples/chooseExample' + bulkDataJsonExample: + $ref: '#/components/examples/bulkDataJsonExample' + 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' + 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' + 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: + 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 + } + ] + noEntityTypes: + summary: No entity types in content body + value: + singleEntityTypeUnquotedString: + summary: Single entity type as an unquoted string + value: >- + PERSON + singleEntityTypeString: + summary: Single entity type as a string + value: >- + "PERSON" + singleEntityTypeStringArray: + summary: Single entity type in a string array + value: >- + ["PERSON"] + multipleEntityTypesStringArray: + summary: Multiple entity types in a string array + value: >- + ["PERSON", "COMPANY"] + singleEntityTypeObjectNoId: + summary: Single entity type as an SzEntityType object + value: >- + {"entityTypeCode": "PERSON"} + singleEntityTypeObjectArrayNoId: + summary: Single entity type as an SzEntityType array + value: >- + [ {"entityTypeCode": "PERSON"} ] + singleEntityTypeObjectWithId: + summary: Single entity type as an SzEntityType object with ID + value: >- + { + "entityTypeCode": "PERSON", + "entityTypeId": 1000 + } + singleEntityTypeObjectArrayWithId: + summary: Single entity type as an SzEntityType array with ID + value: >- + [ + { + "entityTypeCode": "PERSON", + "entityTypeId": 1000 + } + ] + multipleEntityTypesObjectArrayWithId: + summary: Multiple entity types as an SzEntityType array with IDs + value: >- + [ + { + "entityTypeCode": "PERSON", + "entityTypeId": 1000 + }, + { + "entityTypeCode": "COMPANY", + "entityTypeId": 1001 + } + ] + multipleEntityTypesObjectArrayWithIdAndClass: + summary: >- + Multiple entity types as an SzEntityType array with IDs and classes + value: >- + [ + { + "entityTypeCode": "PERSON", + "entityClassCode": "ACTOR", + "entityTypeId": 1000 + }, + { + "entityTypeCode": "COMPANY", + "entityClassCode": "ACTOR", + "entityTypeId": 1001 + }, + { + "entityTypeCode": "SCHOOL", + "entityClassCode": "ACTOR", + "entityTypeId": 1002 + } + ] + multipleEntityTypesMixed: + summary: Multiple data sources in a mixed array + value: >- + [ + "PERSON", + { + "entityTypeCode": "COMPANY" + }, + { + "entityTypeCode": "SCHOOL", + "entityTypeId": 1002 + }, + { + "entityTypeCode": "HOSPITAL", + "entityClassCode": "ACTOR", + "entityTypeId": 1003 + } + ] + 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: [ ] + 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" ] + multipleEntitiesByDelimitedRecordIdExample: + summary: Multiple entities by delimiter-encoded record ID + value: [ ":CUSTOMERS:GHI789", ":EMPLOYEES:JKL321" ] + singleEntityByJsonRecordIdExample: + summary: Single entity 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"}' ] + multipleEntitiesByMixedRecordIdExample: + summary: Multiple entities by mixed-encoded record ID + value: [ ":CUSTOMERS:GHI789", '{"src":"EMPLOYEES","id":"JKL321"}' ] + noEntitiesArrayExample: + summary: No entities 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"]' + multipleEntitiesByDelimitedRecordIdArrayExample: + summary: Multiple entities by delimiter-encoded record ID + value: '[":CUSTOMERS:GHI789",":EMPLOYEES:JKL321"]' + singleEntityByJsonRecordIdArrayExample: + summary: Single entity 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"}]' + multipleEntitiesByMixedRecordIdArrayExample: + summary: Multiple entities by mixed-encoded record ID + value: '[":CUSTOMERS:GHI789",{"src":"EMPLOYEES","id":"JKL321"}]' + 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. + This option obtains entity network at one degree for the requested + entity and will fully populate up to 1000 related entities and sets + the `partial` property of those `SzRelatedEntity` instances to + `false`. Related entities beyond the first 1000 will be left + incomplete and have their `partial` property will be set to `true`. + 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` - Group near-duplicate feature values and return + a representative value along with its near + duplicate values. + schema: + default: WITH_DUPLICATES + $ref: '#/components/schemas/SzFeatureMode' + 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 + 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 + may consist of nothing more than an entity ID. This provides the + fastest response to an entity query operation because no additional data + needs to be retrieved other than what is directly accessible. This + 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 + entityTypeCodePathParam: + in: path + name: entityTypeCode + required: true + description: >- + The entity type code identifying the entity type. + schema: + type: string + examples: + TEST: + value: TEST + GENERIC: + value: GENERIC + PERSON: + value: PERSON + COMPANY: + value: COMPANY + entityClassCodePathParam: + in: path + name: entityClassCode + required: true + description: >- + The entity class code identifying the entity class. Currently, the + only recognized value is `ACTOR`. Other values will yield a 404 error. + schema: + type: string + examples: + ACTOR: + summary: >- + ACTOR (e.g.: people, companies or organizations). + value: ACTOR + 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: string + default: 3000 + 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: + SzBaseResponse: + description: >- + Represents the base information included in all responses sans the + actual data for the response. + type: object + properties: + meta: + type: object + properties: + 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: + type: string + restApiVersion: + 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 + links: + type: object + properties: + self: + type: string + 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: {} + SzLicenseResponse: + description: >- + The response containing the license information. + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + - type: object + properties: + data: + type: object + properties: + license: + $ref: '#/components/schemas/SzLicenseInfo' + 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' + SzAttributeTypesResponse: + description: >- + The response containing attribute type information. + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + - type: object + properties: + data: + type: object + properties: + attributeTypes: + description: >- + The list of attribute types. + type: array + items: + $ref: '#/components/schemas/SzAttributeType' + SzAttributeTypeResponse: + description: >- + The response containing information for a single attribute type. + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + - type: object + properties: + data: + type: object + properties: + attributeType: + $ref: '#/components/schemas/SzAttributeType' + SzDataSourceResponse: + description: >- + The response describing a data source. + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + - type: object + properties: + data: + type: object + properties: + dataSource: + description: >- + The requested data source as an `SzDataSource` object. + $ref: '#/components/schemas/SzDataSource' + SzDataSourcesResponse: + description: >- + The response describing the configured data sources. + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + - type: object + properties: + data: + 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' + SzEntityTypeResponse: + description: >- + The response describing an entity type. + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + - type: object + properties: + data: + type: object + properties: + entityType: + description: >- + The requested entity type as an `SzEntityType` object. + $ref: '#/components/schemas/SzEntityType' + SzEntityTypesResponse: + description: >- + The response describing the configured entity types. + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + - type: object + properties: + data: + type: object + properties: + entityTypes: + description: >- + The list of entity type codes for the configured entity + types. + type: array + items: + type: string + entityTypeDetails: + description: >- + The list of `SzEntityType` instances describing the + configured entity types. + type: object + additionalProperties: + $ref: '#/components/schemas/SzEntityType' + SzEntityClassResponse: + description: >- + The response describing an entity class. + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + - type: object + properties: + data: + type: object + properties: + entityClass: + description: >- + The requested data source as an `SzEntityClass` object. + $ref: '#/components/schemas/SzEntityClass' + SzEntityClassesResponse: + description: >- + The response describing the configured entity classes. + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + - type: object + properties: + data: + type: object + properties: + entityClasses: + description: >- + The list of entity classes codes for the configured entity + classes. + type: array + items: + type: string + entityClassDetails: + description: >- + The list of `SzEntityClass` instances describing the + configured entity classes. + type: object + additionalProperties: + $ref: '#/components/schemas/SzEntityClass' + SzConfigResponse: + description: >- + The response containing raw configuration in the rawData field. + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + SzLoadRecordResponse: + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + - type: object + properties: + data: + 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' + SzReevaluateResponse: allOf: - $ref: '#/components/schemas/SzResponseWithRawData' - type: object properties: data: - $ref: '#/components/schemas/SzLicenseInfo' - SzDataSourcesResponse: + type: object + properties: + info: + description: >- + The optionally requested info associated with the + reevaluation. + $ref: '#/components/schemas/SzResolutionInfo' + SzDeleteRecordResponse: allOf: - $ref: '#/components/schemas/SzResponseWithRawData' - type: object @@ -576,13 +3668,14 @@ components: data: type: object properties: - dataSources: + info: description: >- - The list of data source codes that are configured. - type: array - items: - type: string + The optionally requested info associated with the + record deletion. + $ref: '#/components/schemas/SzResolutionInfo' SzRecordResponse: + description: >- + The response describing an entity record. allOf: - $ref: '#/components/schemas/SzResponseWithRawData' - type: object @@ -592,537 +3685,1728 @@ components: properties: record: description: >- - The EntityRecord describing the matching record. + 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' + SzAttributeSearchResponse: + description: >- + The response describing the resolved entities found from a search. + allOf: + - $ref: '#/components/schemas/SzResponseWithRawData' + - type: object + properties: + data: + type: object + properties: + searchResults: + description: >- + The array AttributeSearchResult instances describing the + entities matching the specified entity search attributes + including the AttributeSearchResultType for each. + type: array + items: + $ref: '#/components/schemas/SzAttributeSearchResult' + 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 `SzWhyEntityResults` 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' + 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. + * `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. + type: string + enum: + - NONE + - REPRESENTATIVE + - WITH_DUPLICATES + 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. + This option obtains entity network at one degree for the requested + entity and will fully populate up to 1000 related entities and sets + the `partial` property of those `SzRelatedEntity` instances to + `false`. Related entities beyond the first 1000 will be left + incomplete and have their `partial` property will be set to `true`. + 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 + 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 + 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 RecordId 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: + 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. + 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' + 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. + 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. + 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/SzResponseWithRawData' + - $ref: '#/components/schemas/SzEntityRecord' - type: object properties: - data: - $ref: '#/components/schemas/SzEntityData' - SzAttributeSearchResponse: + 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 + matchScore: + description: >- + The match score between the first record in the resolved + entity and this record. The higher the score the closer + the match. This is `null` for the first record in the + resolved entity. + type: integer + format: int32 + nullable: true + 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 + refScore: + description: >- + The ref score between the first record in the resolved entity + and this record. This is zero (0) for the first record in the + resolved entity. + 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. + 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 or if the minimal + response flag has been specified. + type: boolean + 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/SzResponseWithRawData' + - $ref: '#/components/schemas/SzResolvedEntity' - type: object properties: - data: - type: object - properties: - searchResults: - description: >- - The array AttributeSearchResult instances describing the - entities matching the specified entity search attributes - including the AttributeSearchResultType for each. - type: array - items: - $ref: '#/components/schemas/SzAttributeSearchResult' - SzEntityPathResponse: + matchLevel: + description: >- + The integer "match level" describing how the related entity + matched to the primary resolved entity. + type: integer + format: int32 + fullNameScore: + description: >- + The full name score between the primary resolved entity and + this related entity. The higher the score the closer the + name match. + type: integer + format: int32 + matchScore: + description: >- + The match score between the primary resolved entity and + this related entity. The higher the score the closer + the match. + type: integer + format: int32 + nullable: true + 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 + refScore: + description: >- + The ref score between the primary resolved entity and + this related entity. + type: integer + format: int32 + 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 + 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/SzResponseWithRawData' + - $ref: '#/components/schemas/SzBaseRelatedEntity' - type: object properties: - data: - $ref: '#/components/schemas/SzEntityPathData' - SzEntityNetworkResponse: + 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' + 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). + 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/SzResponseWithRawData' + - $ref: '#/components/schemas/SzBaseRelatedEntity' - type: object properties: - data: - $ref: '#/components/schemas/SzEntityNetworkData' - SzError: + resultType: + $ref: '#/components/schemas/SzAttributeSearchResultType' + 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 an error. + Describes a path between two entities using the entity IDs of the + entities in the path. type: object properties: - code: - description: The internal error code. - type: string - nullable: true - message: - description: The message describing the error. - type: string - 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. - oneOf: - - type: integer + startEntityId: + description: The starting entity ID for the path. + nullable: false + type: integer format: int64 - - $ref: '#/components/schemas/SzRecordId' - 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 RecordId instances containing the data-source-code/record-id pair. - oneOf: - - type: array - items: + endEntityId: + description: The ending entity ID for the path. + nullable: false type: integer format: int64 - - type: array - items: - $ref: '#/components/schemas/SzRecordId' - SzRecordId: + 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: >- - 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. + 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: - src: + entityPath: + $ref: '#/components/schemas/SzEntityPath' + entities: description: >- - The data source code that uniquely identifies the data source - associated with the record. - type: string - id: + 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 record ID that uniquely identifies a record within the - respective data source. - type: string - SzLicenseInfo: + 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: >- - Describes the Senzing product license. + Provides information about which server features are enabled and which + are not enabled. type: object properties: - customer: - type: string - description: >- - The customer information associated with the license. - contract: - type: string + concurrency: description: >- - The contract information associated with the license. - licenseType: - type: string + The number of Senzing worker threads pooled for handling requests. + type: integer + format: int32 + nullable: false + activeConfigId: description: >- - The description of the type of license. - licenseLevel: - type: string + 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: >- - The description of the license level. - billing: - type: string + Whether or not the server will automatically pickup the latest + default configuration if it changes. + type: boolean + nullable: false + readOnly: description: >- - The billing information associated with the license - issuanceDate: - type: string - format: date-time + 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: >- - The issuance date for the license. - expirationDate: + Whether or not admin features are enabled. If admin features are + not enabled then the configuration cannot be modified. + type: boolean + nullable: false + SzDataSource: + description: Describes a data source. + type: object + properties: + dataSourceCode: + description: The data source code. type: string - format: date-time + nullable: false + dataSourceId: description: >- - The expiration date for the license. - recordLimit: + 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: int64 - description: >- - The record limit associated with the license. - SzEntityRecord: - description: >- - Describes a record (aka: observed entity) that has been loaded for - a particular data source. + format: int32 + nullable: true + SzEntityType: + description: Describes an entity type. type: object properties: - dataSource: + entityTypeCode: + description: The entity type code. type: string - description: >- - The data source code identifying the source from which the record - was loaded. - recordId: + nullable: false + entityClassCode: + description: The entity class code associated with the entity type. type: string + nullable: false + entityTypeId: 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. - 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 - attributeData: - description: >- - An array of attributes associated with the record that are formatted - for readability. These will be prefixed by an attribtue type and - optionally by a "usage type" if one was provided. - 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: + The entity type ID. The value can be null when used for input in + creating an entity type to indicate that the entity type ID should + be auto-generated. + type: integer + format: int32 + nullable: true + SzEntityClass: + description: Describes an entity class. + type: object + properties: + entityClassCode: + description: The entity class code. + type: string + nullable: false + entityClassId: 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: + The entity class ID. The value can be null when used for input in + creating an entity class to indicate that the entity class ID + should be auto-generated. + type: integer + format: int32 + nullable: true + resolving: description: >- - The JSON representation of the original data record that was - loaded. - type: object - additionalProperties: {} - SzDataSourceRecordSummary: + Whether or not entities having entity types belong to this entity + class will resolve with each other. This is `true` if they will + resolve and `false` if they will not. + type: boolean + nullable: true + SzDataSourceDescriptor: 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. + Describes a data source either as only its data source code or as an + `SzDataSource` object. + oneOf: + - type: string + - $ref: '#/components/schemas/SzDataSource' + SzEntityTypeDescriptor: + description: >- + Describes an entity type either as only its entity type code or as an + `SzEntityType` object. + oneOf: + - type: string + - $ref: '#/components/schemas/SzEntityType' + SzEntityClassDescriptor: + description: >- + Describes an entity class either as only its entity class code or as an + `SzEntityClass` object. + oneOf: + - type: string + - $ref: '#/components/schemas/SzEntityClass' + 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 - record breakdown is being described. + 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 from the respective data source that are - part of the associated resolved entity. + The number of records having the associated data source. type: integer format: int32 - topRecordIds: + recordsWithRecordIdCount: 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 - SzEntityFeature: + The number of records having the associated data source that + include a `RECORD_ID` value. + nullable: false + type: integer + format: int32 + recordsWithEntityTypeCount: + description: >- + The number of records having the associated data source that + include an `ENTITY_TYPE` value. + nullable: false + type: integer + format: int32 + SzEntityTypeRecordAnalysis: 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. + Provides statistics specific to a given entity type of the records + found in bulk data. type: object properties: - primaryValue: - type: string - usageType: + entityType: description: >- - The optional associated usage type (e.g.: "HOME" or "WORK") + The entity type code identifying the entity type for which the + statistics are being provided. This is `null` if the statistics + pertain to those records with no entity type defined in the + source data. type: string nullable: true - duplicateValues: + recordCount: 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 - SzResolvedEntity: + The number of records having the associated entity type. + type: integer + format: int32 + recordsWithRecordIdCount: + description: >- + The number of records having the associated entity type that + include a `RECORD_ID` value. + nullable: false + type: integer + format: int32 + recordsWithDataSourceCount: + description: >- + The number of records having the associated entity type that + include a `DATA_SOURCE` value. + nullable: false + type: integer + format: int32 + SzBaseBulkLoadResult: description: >- - Describes a resolved entity that is made up of one or more EntityRecord - instances. + Provides statistics specific common to all bulk load results regardless + of how they are aggregated. type: object properties: - entityId: + recordCount: description: >- - The unique numeric ID identifying the entity. + 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: int64 - entityName: + format: int32 + loadedRecordCount: description: >- - The name associated with this entity that is considered the - best name among all the associated names. - type: string - bestName: + 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: >- - 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: + The number of records from the bulk data set within the aggregate + group that are missing either a `DATA_SOURCE` value or `ENTITY_TYPE` + value. + type: integer + format: int32 + failedRecordCount: 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: + The number of records from the bulk data set within the aggregate + group that failed to load. + type: integer + format: int32 + topErrors: 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") + The array of top error occurrences with the number of times they + occurred when loading records with the associated data source. type: array items: - type: string - attributeData: + $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 + SzEntityTypeBulkLoadResult: + description: >- + Provides bulk data load statistics specific to a given enitty type. + allOf: + - $ref: '#/components/schemas/SzBaseBulkLoadResult' + - type: object + properties: + entityType: + description: >- + The entity type code identifying the entity type 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: >- - An array of attributes associated with the entity that are formatted - for readability. These will be prefixed by an attribtue type and - optionally by a "usage type" if one was provided. - type: array - items: - type: string - addressData: + The state of the bulk load. + $ref: '#/components/schemas/SzBulkDataStatus' + characterEncoding: 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: + 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: >- - 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: + The number of records provided that include a `RECORD_ID` value. + nullable: false + type: integer + format: int32 + recordsWithDataSourceCount: 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") + The number of records provided that include a `DATA_SOURCE` value. + nullable: false + type: integer + format: int32 + recordsWithEntityTypeCount: + description: >- + The number of records provided that include a `ENTITY_TYPE` 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: - type: string - records: + $ref: '#/components/schemas/SzDataSourceRecordAnalysis' + analysisByEntityType: description: >- - The array of EntityRecord instances describing the records - associated with this entity. + The array of `SzEntityTypeRecordAnalysis` elements providing statistics on the records by entity type. + nullable: false type: array items: - $ref: '#/components/schemas/SzEntityRecord' - features: - description: >- - The map of string feature names to arrays of EntityFeature instances - describing the values associated with each respective feature name. - type: object - additionalProperties: - type: array - items: - $ref: '#/components/schemas/SzEntityFeature' - SzBaseRelatedEntity: + $ref: '#/components/schemas/SzEntityTypeRecordAnalysis' + SzBulkLoadResult: description: >- - Provides the additional fields to a ResolvedEntity that describe - an entity's relationship to another. This serves as a basis for - AttributeSearchResult and RelatedEntity. + 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/SzResolvedEntity' + - $ref: '#/components/schemas/SzBaseBulkLoadResult' - type: object properties: - matchLevel: - description: >- - The integer "match level" describing how the related entity - matched to the primary resolved entity. - type: integer - format: int32 - fullNameScore: - description: >- - The full name score between the primary resolved entity and - this related entity. The higher the score the closer the - name match. - type: integer - format: int32 - matchScore: - description: >- - The match score between the primary resolved entity and - this related entity. The higher the score the closer - the match. - type: integer - format: int32 - disclosed: - description: >- - A boolean flag indicating if this related entity - represents a disclosed relationship. - type: boolean - ambiguous: + status: description: >- - A boolean flag indicating if this related entity - represents an ambiguous relationship. - type: boolean - matchKey: + The state of the bulk load. + $ref: '#/components/schemas/SzBulkDataStatus' + characterEncoding: description: >- - The match key describing what features matched between - the primary resolved entity and the related entity. + The character encoding used to process the bulk data. + nullable: false type: string - resolutionRuleCode: + mediaType: description: >- - The code identifying the resolution rule that related - this entity to the primary resolved entity. + The media type of the bulk data. + nullable: false type: string - refScore: + missingDataSourceCount: description: >- - The ref score between the primary resolved entity and - this related entity. + The number of records that are incomplete because they are + missing the `DATA_SOURCE` field. + nullable: false type: integer format: int32 - partial: + missingEntityTypeCount: description: >- - If true then this RelatedEntity has complete features and - records, otherwise they are not provided. Also, the - recordSummary items will be missing the topRecordIds if partial - is true. - type: boolean - SzRelationshipType: + The number of records that are incomplete because they are + missing the `ENTITY_TYPE` 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' + resultsByEntityType: + description: >- + The array of `SzEntityTypeBulkDataResult` elements describing + the load statistics by entity type. + nullable: false + type: array + items: + $ref: '#/components/schemas/SzEntityTypeBulkLoadResult' + SzFocusRecordId: description: >- - Describes how an entity is related to another (either a possible match, - a discovered possible relationship or a disclosed relationship) + 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: - - POSSIBLE_MATCH - - POSSIBLE_RELATION - - DISCLOSED_RELATION - 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: - - type: object - properties: - relationType: - $ref: '#/components/schemas/SzRelationshipType' - - $ref: '#/components/schemas/SzBaseRelatedEntity' - SzEntityData: + - ALWAYS_ONE + - ONE + - FEW + - MANY + - VERY_MANY + - NAME + SzScoringBehavior: description: >- - Describes an entity and the entities related to that entity at - one degree of separation. + Describes the scoring behavior for a feature / feature type. type: object properties: - resolvedEntity: - description: The ResolvedEntity describing the primary entity. - $ref: '#/components/schemas/SzResolvedEntity' - relatedEntities: + code: description: >- - The array of RelatedEntity instances describing the possible - matches, discovered relationships, and disclosed relationships. - type: array - items: - $ref: '#/components/schemas/SzRelatedEntity' - SzAttributeSearchResultType: + 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 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). + 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: + * `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: - - MATCH - - POSSIBLE_MATCH - - POSSIBLE_RELATION - - NAME_ONLY_MATCH - SzAttributeSearchResult: + - SAME + - CLOSE + - LIKELY + - PLAUSIBLE + - UNLIKELY + - NO_CHANCE + SzScoredFeature: description: >- - Describes an entity that matched attribute search criteria and how - it matched against that criteria. - allOf: - - type: object - properties: - resultType: - $ref: '#/components/schemas/SzAttributeSearchResultType' - - $ref: '#/components/schemas/SzBaseRelatedEntity' - SzEntityPath: + 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. + type: string + SzFeatureScore: description: >- - Describes a path between two entities using the entity IDs of the - entities in the path. + Describes the scoring between two `SzScoredFeature` instances. type: object properties: - startEntityId: - description: The starting entity ID for the path. + 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) + type: integer + format: int32 + 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' + 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 + SzMatchInfo: + 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 + resolutionRule: + description: >- + The resolution rule that triggered the match. + nullable: false + type: string + candidateKeys: + description: >- + The map of feature types to arrays of `SzCandidateKey` instances + for that feature type. + nullable: false + 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: false + type: object + additionalProperties: + type: array + items: + $ref: '#/components/schemas/SzFeatureScore' + 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 - endEntityId: - description: The ending entity ID for the path. + entityId: + description: >- + The associated entity ID for the perspective. nullable: false type: integer format: int64 - entityIDs: + focusRecords: 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 + The array of `SzFocusRecordId` instances identifying the effectively + identical records that are being compared against the other records. + nullable: false type: array items: - type: integer - format: int64 - SzEntityPathData: + $ref: '#/components/schemas/SzFocusRecordId' + SzWhyEntityResult: 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. + Describes why an entity resolved. type: object properties: - entityPath: - $ref: '#/components/schemas/SzEntityPath' - entities: + perspective: description: >- - The array of EntityData 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: + The `SzWhyPerspective` identifying and describing the perspective + for this why result. + $ref: '#/components/schemas/SzWhyPerspective' + matchInfo: + description: >- + The `SzMatchInfo` providing the details of the result. + nullable: false + $ref: '#/components/schemas/SzMatchInfo' + SzWhyRecordsResult: 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. + Describes why two records might resolve. type: object properties: - entityPaths: + perspective1: description: >- - The array of EntityPath objects describing the paths that make up - the entity network (including island networks). - type: array - items: - $ref: '#/components/schemas/SzEntityPath' - entities: + The `SzWhyPerspective` identifying and describing the perspective + from the first record. + $ref: '#/components/schemas/SzWhyPerspective' + perspective2: description: >- - The array of EntityData 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' + The `SzWhyPerspective` identifying and describing the perspective + from the second record. + $ref: '#/components/schemas/SzWhyPerspective' + matchInfo: + description: >- + The `SzMatchInfo` providing the details of the result. + nullable: false + $ref: '#/components/schemas/SzMatchInfo' tags: - name: Admin description: Administrative operations. @@ -1132,4 +5416,5 @@ tags: 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.