Dataset Management

(introduced: version 2022.3)

⚠️ In this API and in the related ODK XForms specification, collections of Entities are referred to as Datasets. The term "Entity List" is used for this concept in the Central frontend UI, user documentation, and all other text intended for end users who are not developers.

A Dataset is a named collection of Entities that have the same properties.

A Dataset can be linked to Forms as Attachments. This will make it available to clients as an automatically-updating CSV.

Related APIs:

• Implicit creation of Datasets via Forms

• Link a Dataset to a Form Attachment

• Get a Form's Related Datasets

Listing Datasets

GET /projects/{projectId}/datasets

The Dataset listing endpoint returns all published Datasets in a Project. If a Draft Form defines a new Dataset, that Dataset will not be included in this list until the Form is published.

Request

Parameters

projectId

number The numeric ID of the Project Example: 16

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "name": "people",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "projectId": 1,
    "approvalRequired": true
  }
]

Schema

array name string The name of the Dataset Example: people createdAt string ISO date format. Example: 2018-01-19 23:58:03.395000+00:00 projectId number The numerical ID of the Project that the Dataset belongs to. Example: 1 approvalRequired boolean Control whether a Submission should be approved before an Entity is created from it. Example: true

HTTP Status: 200

Content Type: application/json; extended

Example

[
  {
    "name": "people",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "projectId": 1,
    "approvalRequired": true,
    "lastEntity": "2018-04-18T03:04:51.695Z",
    "entities": 10,
    "conflicts": 2
  }
]

Schema

array name string The name of the Dataset Example: people createdAt string ISO date format. Example: 2018-01-19 23:58:03.395000+00:00 projectId number The numerical ID of the Project that the Dataset belongs to. Example: 1 approvalRequired boolean Control whether a Submission should be approved before an Entity is created from it. Example: true lastEntity string ISO date format. The timestamp of the most recent entity, if any. Example: 2018-04-18 03:04:51.695000+00:00 entities number The number of Entities in the Dataset. Example: 10 conflicts number The number of Entities that have conflicts. Example: 10.0

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Creating Datasets

POST /projects/{projectId}/datasets

You can create a Dataset with a specific name within a Project. This Dataset can then be populated with Entities via the API or via Forms and Submissions, and then used by other Forms. This endpoint allows a Dataset to be created programatically without an input form.

The name of a Dataset is case-sensitive in that it will keep the capitalization provided (e.g. "Trees"). But Central will not allow a second Dataset with the same name but different capitalization to be created (e.g. "trees" when "Trees" already exists).

By default, the Dataset will have no properties, but each Entity will have a label and a unique ID (uuid). You can add additional properties with this related endpoint.

The Dataset name must follow the the same rules as XML identifiers and not start with . or __. See the Entities XForms Specification for more information.

Request

Parameters

projectId

number The numeric ID of the Project Example: 16

Request body

Example

{
  "name": "Trees",
  "approvalRequired": false
}

Schema

object name string The desired name of the Dataset. Must be a valid approvalRequired boolean Control whether a Submission should be approved before an Entity is created from it.

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "name": "people",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "projectId": 1,
  "approvalRequired": false,
  "sourceForms": [],
  "linkedForms": [],
  "properties": []
}

Schema

array linkedForms array Forms that consume data from the Dataset expand xmlFormId string The id of this form as given in its XForms XML definition Example: simple name string The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition. Example: Simple sourceForms array Forms that create Entities in the Dataset expand xmlFormId string The id of this form as given in its XForms XML definition Example: simple name string The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition. Example: Simple properties array All properties of the Dataset expand name string The name of the Property. Example: the.age odataName string The name of the property as it will appear in OData. OData property names can only contain alphanumeric characters and underscores. Example: the_age publishedAt string Publishing timestamp of the form that defined this property for the first time. Example: 2018-01-21T00:04:11.153Z forms array List of forms that create the property expand xmlFormId string The id of this form as given in its XForms XML definition Example: simple name string The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition. Example: Simple

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

HTTP Status: 409

Content Type: application/json

Example

{
  "code": 409.3,
  "message": "A resource already exists with name,projectId value(s) of trees,1."
}

Schema

object code number message string

Dataset Metadata

GET /projects/{projectId}/datasets/{name}

Returns the metadata of a published Dataset including properties and forms that create and consume the Dataset.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
name	string Name of the Dataset Example: people

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "name": "people",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "projectId": 1,
  "approvalRequired": true,
  "sourceForms": [
    {
      "xmlFormId": "treeRegistration",
      "name": "Tree Registration"
    }
  ],
  "linkedForms": [
    {
      "xmlFormId": "simple",
      "name": "Simple"
    }
  ],
  "properties": [
    {
      "name": "the.age",
      "odataName": "the_age",
      "publishedAt": "2018-01-21T00:04:11.153Z",
      "forms": [
        {
          "xmlFormId": "simple",
          "name": "Simple"
        }
      ]
    }
  ]
}

Schema

array linkedForms array Forms that consume data from the Dataset expand xmlFormId string The id of this form as given in its XForms XML definition Example: simple name string The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition. Example: Simple sourceForms array Forms that create Entities in the Dataset expand xmlFormId string The id of this form as given in its XForms XML definition Example: simple name string The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition. Example: Simple properties array All properties of the Dataset expand name string The name of the Property. Example: the.age odataName string The name of the property as it will appear in OData. OData property names can only contain alphanumeric characters and underscores. Example: the_age publishedAt string Publishing timestamp of the form that defined this property for the first time. Example: 2018-01-21T00:04:11.153Z forms array List of forms that create the property expand xmlFormId string The id of this form as given in its XForms XML definition Example: simple name string The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition. Example: Simple

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Update Dataset Metadata

PATCH /projects/{projectId}/datasets/{name}

You can only update approvalRequired using this endpoint. approvalRequired flag controls the Entity creation flow; if it is true then the Submission must be approved before an Entity can be created from it and if it is false then an Entity is created as soon as the Submission is received by the ODK Central.

By default approvalRequired is false for the Datasets created after v2023.3. Datasets created prior to that will have approvalRequired set to true.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
name	string Name of the Dataset Example: people

Request body

Example

{
  "approvalRequired": true
}

Schema

object approvalRequired boolean Control whether a Submission should be approved before an Entity is created from it. Example: true

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "name": "people",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "projectId": 1,
  "approvalRequired": true,
  "sourceForms": [
    {
      "xmlFormId": "treeRegistration",
      "name": "Tree Registration"
    }
  ],
  "linkedForms": [
    {
      "xmlFormId": "simple",
      "name": "Simple"
    }
  ],
  "properties": [
    {
      "name": "the.age",
      "odataName": "the_age",
      "publishedAt": "2018-01-21T00:04:11.153Z",
      "forms": [
        {
          "xmlFormId": "simple",
          "name": "Simple"
        }
      ]
    }
  ]
}

Schema

array linkedForms array Forms that consume data from the Dataset expand xmlFormId string The id of this form as given in its XForms XML definition Example: simple name string The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition. Example: Simple sourceForms array Forms that create Entities in the Dataset expand xmlFormId string The id of this form as given in its XForms XML definition Example: simple name string The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition. Example: Simple properties array All properties of the Dataset expand name string The name of the Property. Example: the.age odataName string The name of the property as it will appear in OData. OData property names can only contain alphanumeric characters and underscores. Example: the_age publishedAt string Publishing timestamp of the form that defined this property for the first time. Example: 2018-01-21T00:04:11.153Z forms array List of forms that create the property expand xmlFormId string The id of this form as given in its XForms XML definition Example: simple name string The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition. Example: Simple

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Adding Properties

POST /projects/{projectId}/datasets/{name}/properties

Creates a new Property with a specified name in the Dataset.

The name of a Property is case-sensitive in that it will keep the capitalization provided (e.g. "Firstname"). But Central will not allow another Property with the same name but different capitalization to be created (e.g. "FIRSTNAME" when "Firstname" already exists).

Property names follow the same rules as form field names (valid XML identifiers) and cannot use the reserved names of name or label, or begin with the reserved prefix __.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
name	string Name of the Dataset Example: people

Request body

Example

{
  "name": "circumference"
}

Schema

object name string The desired name of the Property.

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "success": true
}

Schema

object success boolean

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Download Dataset

GET /projects/{projectId}/datasets/{name}/entities.csv

Datasets (collections of Entities) can be used as Attachments in other Forms, but they can also be downloaded directly as a CSV file.

The CSV format closely matches the OData Dataset Service format, with columns for system properties such as __id (the Entity UUID), __createdAt, __creatorName, etc., the Entity Label label, and the Dataset/Entity Properties themselves. If any Property for an given Entity is blank (e.g. it was not captured by that Form or was left blank), that field of the CSV is blank.

The $filter querystring parameter can be used to filter on system-level properties, similar to how filtering in the OData Dataset Service works.

This endpoint supports ETag header, which can be used to avoid downloading the same content more than once. When an API consumer calls this endpoint, the endpoint returns a value in the ETag header. If you pass that value in the If-None-Match header of a subsequent request, then if the Dataset has not been changed since the previous request, you will receive 304 Not Modified response; otherwise you'll get the new data.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
name	string Name of the Dataset Example: people
$filter (query)	string If provided, will filter responses to those matching the query. Only system-level Entity fields are available to reference. The operators lt, le, eq, neq, ge, gt, not, and, and or are supported, and the built-in functions now, year, month, day, hour, minute, second. Example: __system/conflict eq \'hard\'

Response

HTTP Status: 200

Content Type: text/csv

Example

__id,label,geometry,species,circumference_cm,__createdAt,__creatorId,__creatorName,__updates,__updatedAt,__version
2c1ee90b-dde8-434b-9985-2eefd8465339,666cm purpleheart,-29.281608 -67.624883 0 0,purpleheart,667,2023-05-31T19:49:28.902Z,22,Alice,1,2023-05-31T19:52:34.467Z,1
84ac3a03-9980-4098-93a5-b81fdc6ea749,555cm wallaba,18.921876 77.309451 0 0,wallaba,555,2023-05-31T19:49:20.152Z,22,Alice,0,,1

Schema

string

HTTP Status: 403

Content Type: text/csv

Example

No Example

Schema

string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No