Schema Setup
Overview of how to prepare schemas for identity resolution.
Overview
In order to make the resolution process scalable across agencies, a standardized identity resolution schema is used to canonicalize data fields across systems. Attest's identity resolution API defines a canonical identity schema for use across agencies.In order to meet the requirements of this identity resolution schema, each participating agency MUST define a schema mapping file for its existing system of record.
Mapping schema files ensures the identity resolution API is able to:
Understand the naming conventions of specific fields across agencies
Use a single standard field name and definition for consistent matching results.
This process ensures field-level consistency in a scenario where Agency A uses the field nameGender whereas Agency B uses the field name Sex.
Constructing Schemas
Schema field objects are made up of the following structure:
"referenceIdentifier": {
"field": "DOB"
"format": "%Y/%M/%D"
}
...
// Object structure
"[resolver_field_name]": {
"field": "[field_name_in_import_file]",
"format": "[date_format_in_import_file]"
},
...Schema files MUST use conventional JSON file structure and syntax standards. Schema files MUST contain the following fields in order to process the import file.
If an agency does not record an optional field such as middleName implementors must OMIT the field from the schema file.
Schema Field Requirements
Field
Description
Format
name
string
Name of the agency or organization
None
referenceIdentifier
integer
Agency/organization-specific reference identifier, unique per individual
None
firstName
string
First name of the individual
None
middleName *
string
Middle name of the individual
None
lastName
string
Last name of the individual
None
gender*
string
Gender of the individual
Variety of formats are accepted
F/ Female
dateOfBirth
string
Date of birth of the individual
MUST match the import file format including use of "/" or "-"
%M/%D/%Y or
%Y-%M-%D
* Indicates a field that is not required in the schema file.
Example Schema Files
Schema/CSV Naming Conventions
The JSON file and corresponding agency CSV must be named exactly the same so the mapping can occur effectively, for example:
Not using the same naming convention for the two will return the following error:
The sandbox environment used for testing purposes can be easily reset, however, a lightweight naming/versioning process when creating the schema file SHOULD be used. An example naming convention could be the agency_abbrevation plus the date of the upload/testing:
Validating JSON Schema Files
Prior to executing the adapter locally, to check for any JSON formatting or JSON schema errors. Implementors SHOULD use a JSON schema validator tool to validate the structure of the schema file. A variety of schema validators are available online including the following:
Using the examples below, a valid JSON schema file constructed for an agency should return a valid result when compared to the schema definition file.
Troubleshooting Invalid JSON Schemas
In the event that a schema file created does not conform to the JSON schema file specification listed above, the adapter will return the following error:
If this error is returned be sure to complete the step labeled Validating JSON Schema Files.
Last updated
Was this helpful?