1.8 Metadata field filter

In certain situations the default views of the metadata can be too verbose. A client might only need a few fields from each object and want to remove unnecessary fields from the response. To discover which fields are available for each object please see the schema section.

The format for include/exclude is very simple and allows for infinite recursion. To filter at the “root” level you can just use the name of the field, i.e. ?fields=id,name which would only display the id and name for every object. For objects that are either collections or complex objects with properties on their own you can use the format ?fields=id,name,dataSets[id,name] which would return id , name of the root, and the id and name of every data set on that object. Negation can be done with the exclamation operator, and we have a set of presets of field select (see below). Both XML and JSON are supported.

Example : Get id and name on the indicators resource:

/api/26/indicators?fields=id,name

Example : Get id and name from dataElements, and id and name from the dataSets on dataElements:

/api/26/dataElements?fields=id,name,dataSets[id,name]

To exclude a field from the output you can use the exclamation (!) operator. This is allowed anywhere in the query and will simply not include that property (as it might have been inserted in some of the presets).

A few presets (selected fields groups) are available and can be applied using the ‘:’ operator.

Property operators
Operator Description
<field-name> Include property with name, if it exists.
<object>[<field-name>, …] Includes a field within either a collection (will be applied to every object in that collection), or just on a single object.
!<field-name>, <object>[!<field-name> Do not include this field name, also works inside objects/collections. Useful when you use a preset to include fields.
*, <object>[*] Include all fields on a certain object, if applied to a collection, it will include all fields on all objects on that collection.
:<preset> Alias to select multiple fields. Three presets are currently available, see table below for descriptions.
Field presets
Preset Description
all All fields of the object
* Alias for all
identifiable Includes id, name, code, created and lastUpdated fields
nameable Includes id, name, shortName, code, description, created and lastUpdated fields
persisted Returns all persisted property on a object, does not take into consideration if the object is the owner of the relation.
owner Returns all persisted property on a object where the object is the owner of all properties, this payload can be used to update through the web-api.

Example : Include all fields from dataSets except organisationUnits:

/api/26/dataSets?fields=:all,!organisationUnits

Example : Include only id, name and the collection of organisation units from a data set, but exclude the id from organisation units:

/api/26/dataSets/BfMAe6Itzgt?fields=id,name,organisationUnits[:all,!id]

Example : Include nameable properties from all indicators:

/api/26/indicators.json?fields=:nameable

1.8.1 Field transformers

In DHIS2.17 we introduced field transformers, the idea is to allow further customization of the properties on the server side.

/api/26/dataElements/ID?fields=id~rename(i),name~rename(n)

This will rename the id property to i and name property to n .

Multiple transformers can be used by repeating the transformer syntax:

/api/26/dataElementGroups.json?fields=id,displayName,dataElements~isNotEmpty~rename(haveDataElements)
Available Transformers
Name Arguments Description
size Gives sizes of strings (length) and collections
isEmpty Is string or collection empty
isNotEmpty Is string or collection not empty
rename Arg1: name Renames the property name
paging Arg1: page,Arg2: pageSize Pages a collection, default pageSize is 50.

1.8.1.1 Examples

Examples of transformer usage.

/api/26/dataElements?fields=dataSets~size

/api/26/dataElements?fields=dataSets~isEmpty

/api/26/dataElements?fields=dataSets~isNotEmpty

/api/26/dataElements/ID?fields=id~rename(i),name~rename(n)

/api/26/dataElementGroups?fields=id,displayName,dataElements~paging(1;20)