Anatomy of a YAML file

This article lists all supported objects you can use inside your Data app YAML file and provides best practices guidance on using them. The object hierarchy is represented using dot notation. In other words, if you're looking at schema.types.title, this means that the schema object must be at the root level of your YAML file, it contains a collection of types and each type has a title property.

Sample Data App YAML file

In its most simple form, a complete Data app YAML file looks something like this:

kind: rest
baseUrl: "{url-to-the-3rd-party-rest-api}"
dateFormat: "yyyy-MM-dd'T'HH:mm:ss"
    uri: ""    
    verb: GET
        accept: "application/json"

            title: ""
            key: ""
                    name: ""
                    title: ""
                    type: ""
                uri: "{uri-path}"
                verb: GET
                    accept: "application/json"
                    collection: ""

You can use this template to start creating your first Data apps. You can also use the App Boilerplates tool to generate sample Data app templates.

YAML file properties


kind: rest

Currently the only supported kind for a Data app is rest. This kind indicates the app is pulling data from a REST API.


baseUrl: ""

This is the base url of your REST API. It will be used in combination with the endpoint uri paths specified in the download section of each type when downloading its data.


dateFormat: "yyyy-MM-dd'T'HH:mm:ss"

This setting allows you to specify the format of the date fields. The format should match the format coming from the API response. Examples:

  • dateFormat: "yyyy-MM-dd'T'HH:mm:ss"
  • dateFormat: "yyyy-MM-dd'T'HH:mm:ss'Z'"
  • dateFormat: "yyyy-MM-dd'T'HH:mm:ss.mmm'Z'"


      uri: "/planets"
      verb: "GET"
          Accept: "application/json"

Your Data app uses this object to perform a REST call on the specified uri during the connection set up steps. The app uses the response from this API call to determine successful connectivity (Response code between 200-399). While this is not a mandatory property it’s recommended to have one as this makes the identification of potential problems easier.


uri: ""

The URL on which the rest call will be made. A response code between 200 and 399 is expected.


verb: GET

The HTTP method (verb) to use. Supported methods are GET and POST.


    accept: "application/json"
    content-type: "application/json"

Any HTTP headers needed for the connection test request. If you must pass more that one header, list each ona new line


This is the start of the data type definition, where we define what tables and columns we’re going to pull from the API


This is the list of entities being pulled from the API. Defining at least one type is required.


    title: "Glossary"

The title for the type. This is what the user will see available for selection in the Add datasource screen.


    key: "nws_glossary"

This is the unique key that will serve as table name for the entity. It's used not only for persistence, but also in the insignt editor SQL when querying from the entity. It is recommended to prefix this with an acronym indicating the data source to distinguish similar table names from other data sources. For example, gtmhub_issues when we are querying the issues entity from the Quantive Results Data app)


The list of data fields to pull from the collection of results. At least one field is required but multiple can be specified where needed.

    name: "term"

The JavaScript notation to get to the field that you want within the JSON object


    title: "Term"

The name of the field (also used to determine the table column name) that will be visible UI.


    type: "string"

The data type for the table column where data for this field is stored. Supported options are:

  • string
  • double
  • integer
  • date
  • long

The download instructions for this entity. This defines what API call the Data app will make to fetch the items for that type.

  uri: "/glossary"

This is the api ednpoint uri. It is always append to the base URL to create the full API call

  verb: GET

Usually a GET, but may be another HTTP verb depending on your REST API.

      accept: "application/json"

All necessary headers for the call. This collection usually includes authorization header information when your REST API requires it. See Using connection parameters to store API tokens for more information on how you can ask users to provide an API token when setting up your Data app, and how you can use it in your YAML headers collection.

The responses object enables you to describe how your REST API JSON response looks like, and which elemnts from it contain the data you are interested in consuming.

    collection: "glossary"

If the REST API response contains multiple collections, specify which one contains the data for this type. If the root of the response is the list of items (i.e. the response is a JSON array) then leave this property with no value.

If the REST API endpoint implements paging, you must describe how the paging mechanism should work. The paging object has the following properties:

  • kind - it's always custom-rest
  • skipParamName - the name of the skip parameter in your REST API (for example, skip, fetch). The default is "skip".
  • takeParamName - the name of the take parameter in your REST API (for example, take, top, limit). The default is "take".
  • skip - how many items to skip in a single paged request. The default is 0.
  • take - how many items to take in a single paged request. The default is 50.
  • skipIncrementBy - hwo to calculate the skip parameter on each consecutive request. The default is skip += take