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:
Example : Get id and name from dataElements, and id and name from the dataSets on dataElements:
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.
|<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.|
|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:
Example : Include only id, name and the collection of organisation units from a data set, but exclude the id from organisation units:
Example : Include nameable properties from all indicators:
In DHIS2.17 we introduced field transformers, the idea is to allow further customization of the properties on the server side.
This will rename the id property to i and name property to n .
Multiple transformers can be used by repeating the transformer syntax:
|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.|
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)