Source references
Source references can provide users with rich information about where the data they see in i2 Analyze records came from. By adding source references to the record data that a service returns, you enable extra functionality in the client, including the ability to associate and view images with your records.
Source references provide up to five pieces of information about the source of an i2 Analyze record:
- The type of the source that data in the record came from
- The name of the source
- A description of the source
- The location of the source, which might be a URL
- An image of the source, which might also be an image for the record
When you return source reference information from a service, only the name is mandatory.
To add source references to the record data that your service returns to clients, you must arrange to include a sourceReference
object as a peer of the properties
object in your response from the acquire endpoint.
In your code that generates responses from the acquire endpoint, add at least the following extra content:
{ ... "properties": { ... }, "sourceReference": { "source": { "name": "source_name" } }, ... }
To give users the best experience, add a type and a description for your source that align with the definitions in the source reference schema for the deployment:
... "sourceReference": { "source": { "name": "source_name", "type": "source_type", "description": "source_description" } }, ...
If the data in the external source has associated images, you can arrange for users to see an image for a record when they view it by adding an
image
field to thesource
object:"source": { ... "image": "image_url" }
You can similarly include the location of the source in the source reference by adding a
location
field and setting it to either a URL or a text description.
Completing these steps in your service code means that source references are present in the records that users retrieve and view. Source references are optional, so you can control whether to include them for all records, or just for records of particular types. Finally, source references have the same features in entity and link records, so you do not need to write different code for those two cases.
Example
The following JSON structure provides an example of an entity object that contains a source reference:
{
"id": "123",
"typeId": "ET1",
"version": 1,
"properties": {
"PT16": "MANHATTAN"
},
"sourceReference": {
"source": {
"name": "Source Dataset",
"type": "Open source data",
"description": "A source reference to the corresponding record from the dataset.",
"location": "https://data.cityofnewyork.us/resource/7x9x-zpz6.json?$where=cmplnt_num=123456789",
"image": "https://github.com/i2group/analyze-connect/blob/gh-pages/content/schemas/images/nypd-dataset-webpage.png?raw=true"
}
}
}