REST data source JSON format

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

For Hypersync apps that retrieve data from a REST data source, the RestDataSourceBase class makes it possible to extract, transform, and sort multiple data sets without writing code. The /json/dataSource.json file is used to define these datasets.

At the top level, a dataSource.json file should expose an object with three properties:

• baseUrl
• dataSets
• messages

Note: Only dataSets is required. The other two properties are both optional.

baseUrl

The baseUrl property defines a common root URL for all endpoints in the dataSets collection. When specified in the dataSource.json file, each dataset’s url value is treated as relative to this base URL.

If your datasets reference APIs that do not share a common root, omit the baseUrl property and provide full URLs in each dataset definition.

dataSets

A dataset is a named object that represents a specific data item or collection (e.g. an array) retrievable from a data source.

Datasets can—and should—be reused across multiple proof types, and they can also support non-proof scenarios such as collecting user data during the validateCredentials process.

Each entry in the dataSets object corresponds to a single dataset used by your custom Hypersync app.

Each dataset object contains the following properties:

Transforming data

Objects returned from a REST API often need formatting before being shown to users. The transform property defines which fields to include in the dataset. Each property name becomes the dataset field, and its value maps to the corresponding field in the API’s JSON response.

The simplest transformation is renaming fields. For example, in the JSONata example below, the dataset field realname maps to the API property full_name. The realname field is then referenced in your proof.json.

Transform with JSONata

Sometimes API data needs to be transformed before it can be used in a dataset. The Hypersync SDK supports transformations using JSONata, a powerful query and transformation language with an extensive library of expressions.

Examples

• Map the API field full_name to the dataset field owner, using username as a fallback if full_name is empty.
• Combine values from the roles array into a single string for the role field.
• Convert the last_login_time value from a Unix timestamp (seconds) to a readable date.

Refer to the official JSONata documentation for a complete list of operators and functions.

Example

{
  "$schema": "https://cdn.jsdelivr.net/gh/Hyperproof/hypersync-sdk/schema/restDataSource.schema.json",
  "baseUrl": "https://THE_SERVICE.com/api/v2",
  "dataSets": {
    "users": {
            "description": "Returns a list of all the users",
            "documentation": "",
            "url": "/v1/objects/user",
            "transform": {
                "username": "username",
                "realname": "full_name",
                "owner": "[(full_name) = ''] ? username : full_name",
                "email": "email",
                "role": "$join([roles], ', ')"
                "enabled": "enabled",
                "last_login_time": "$fromMillis(last_login_time * 1000)",
            },
            "result": "array"
        }
    }
}

Transform with value lookups

APIs often return values that need to be remapped for readability or consistency. For example, an API might return a user status of active or deactivated, which you may want to display as "Active" and "Inactive".

The valueLookups object in the dataSource.json enables this mapping without writing code. Each property acts as a map; keys represent the original API values, and their corresponding values define the replacement strings.

Once defined, mappings in valueLookups can be applied in your datasets using the $vlookup function.

Example

{
  "$schema": "https://cdn.jsdelivr.net/gh/Hyperproof/hypersync-sdk/schema/restDataSource.schema.json",
  "baseUrl": "https://THE_SERVICE.com/api/v2",
  "dataSets": {
    "currentUser": {
      "description": "Returns information about the authorized user.",
      "documentation": "https://THE_SERVICE.com/docs/api/users/me",
      "url": "users/me",
      "transform": {
        "username": "username",
        "firstName": "givenName",
        "lastName": "surname"
      },
      "result": "object"
    },
    "groups": {
      "description": "Returns a list of all the groups in My Service.",
      "documentation": "https://THE_SERVICE.com/docs/api/groups",
      "url": "groups",
      "transform": {
        "id": "id",
        "groupName": "groupName",
        "members": "memberCount"
      },
      "result": "array"
    },
    "users": {
      "description": "Returns a list of all the users in My Service.",
      "documentation": "https://THE_SERVICE.com/docs/api/users",
      "url": "users",
      "transform": {
        "id": "id",
        "firstName": "givenName",
        "lastName": "surname",
        "email": "emailAddress",
        "status": "$vlookup('statuses', status)"
      },
      "result": "array"
    }
  },
  "valueLookups": {
    "statuses": {
      "active": "Active",
      "deactivated": "Inactive"
    }
  }
}