Back to all docs
API Reference / data / DataSource / schema
New to Kendo UI for jQuery? Start a free 30-day trial

Schema

configuration

The configuration used to parse the remote service response.

schema

Object
<script>
  var dataSource = new kendo.data.DataSource({
    transport: {
      read: {
        url: "https://demos.telerik.com/service/v2/core/products",
        contentType: "application/json",
        type: "POST"
      },
      parameterMap: function (data, type) {
        if (type == "read") {
          return JSON.stringify(data);
        }
      }
    },
    schema: {
      data: function(response) {
        console.log(response)            
        return response;
      }
    }
  });
  dataSource.fetch(function(){
    var data = this.data();
    /* The result can be observed in the DevTools(F12) console of the browser. */
    console.log(data.length);
  });
</script>

schema.aggregates

Function|String

The field from the response which contains the aggregate results. Can be set to a function which is called to return the aggregate results from the response.

The aggregates option is used only when the serverAggregates option is set to true.

The result of the function should be a JavaScript object which contains the aggregate results for every field in the following format:

pseudo
    {
      Field1Name: {
        Function1Name: Function1Value,
        Function2Name: Function2Value
      },
      Field2Name: {
        Function1Name: Function1Value
      }
    }

For example, if the data source is configured like this:

pseudo
    var dataSource = new kendo.data.DataSource({
      transport: {
        /* transport configuration */
      },
      serverAggregates: true,
      aggregate: [
        { field: "unitPrice", aggregate: "max" },
        { field: "unitPrice", aggregate: "min" },
        { field: "ProductName", aggregate: "count" }
      ]
    });

The aggregate results should have the following format:

pseudo
    {
      unitPrice: {
          max: 100,
          min: 1
      },
      productName: {
          count: 42
      }
    }
<script>
var dataSource = new kendo.data.DataSource({
  transport: {
    /* transport configuration */
  },
  serverAggregates: true,
  schema: {
    aggregates: "aggregates" // aggregate results are returned in the "aggregates" field of the response
  }
});
</script>
<script>
var dataSource = new kendo.data.DataSource({
  transport: {
    /* transport configuration */
  },
  serverAggregates: true,
  schema: {
    aggregates: function(response) {
      return response.aggregates;
    }
  }
});
</script>

schema.data

Function|String

The field from the server response which contains the data items. Can be set to a function which is called to return the data items for the response.

The data option will not be used if the data source is grouped and set for serverGrouping.

Returns:Array

—The data items from the response.

pseudo
    <script>
      var dataSource = new kendo.data.DataSource({
        transport: {
          read: {
            url: "https://demos.telerik.com/service/v2/core/products",
            contentType: "application/json",
            type: "POST"
          },
          parameterMap: function (data, type) {
            if (type == "read") {
              return JSON.stringify(data);
            }
          }
        },
        schema: {
          data: "Data"
        }
      });
      dataSource.fetch(function(){
        var data = this.data();
        /* The result can be observed in the DevTools(F12) console of the browser. */
        console.log(data.length);
      });
    </script>
<script>
  var dataSource = new kendo.data.DataSource({
    transport: {
      read: {
        url: "https://demos.telerik.com/service/v2/core/products",
        contentType: "application/json",
        type: "POST"
      },
      parameterMap: function (data, type) {
        if (type == "read") {
          return JSON.stringify(data);
        }
      }
    },
    schema: {
      data: function(response) {
        console.log(response)            
        return response; 
      }
    }
  });
  dataSource.fetch(function(){
    var data = this.data();
    /* The result can be observed in the DevTools(F12) console of the browser. */
    console.log(data.length);
  });
</script>

schema.errors

Function|String

The field from the server response which contains server-side errors. Can be set to a function which is called to return the errors for response. If there are any errors, the error event will be fired.

pseudo
    <div id="grid"></div>
    <script>
    var dataSource = new kendo.data.DataSource({
      transport: {
        read: {
          url: "https://demos.telerik.com/service/error-response",
          dataType: "json"
        }
      },
      schema: {
        data: "data",
        errors: "errors"
      },
      error: function(e) {
        console.log("Error occurred: " + e.errors);
      }
    });
    
    $("#grid").kendoGrid({
      dataSource: dataSource
    });
    </script>

If this option is set and the server response contains that field, then the error event will be fired. The errors field of the event argument will contain the errors returned by the server.

Specify the error field as a string

pseudo
    <script>
    var dataSource = new kendo.data.DataSource({
      transport: {
        read: {
          url: "https://run.mocky.io/v3/ef00571f-cd9c-4bb3-a8fc-c98afa9e8de4",
        }
      },
      schema: {
        data: "items",
        errors: function(response) {
	/* The result can be observed in the DevTools(F12) console of the browser. */
          console.log("errors as function", response.errors[0])
          return response.errors;
        }
      },
      error: function(e) {
	/* The result can be observed in the DevTools(F12) console of the browser. */
        console.log("error event handler", e.errorThrown);
      }
    });
    dataSource.fetch();
    </script>

Specify the error field as a function

pseudo
    <script>
      var dataSource = new kendo.data.DataSource({
        transport: {
          read: {
            url: "https://demos.telerik.com/service/v2/core/products",
          }
        },
        schema: {
          errors: function(response) { 
            return response.error;
          }
        },
        error: function(e) {
          /* The result can be observed in the DevTools(F12) console of the browser. */
          console.log(e.errors);
        }
      });
      dataSource.fetch();
    </script>

Default: "errors"

schema.groups

Function|String

The field from the server response which contains the groups. Can be set to a function which is called to return the groups from the response.

The groups option is used only when the serverGrouping option is set to true.

The result should have the following format:

js
[{
  aggregates: {
    FIEL1DNAME: {
      FUNCTON1NAME: FUNCTION1VALUE,
      FUNCTON2NAME: FUNCTION2VALUE
    },
    FIELD2NAME: {
      FUNCTON1NAME: FUNCTION1VALUE
    }
  },
  field: FIELDNAME, // the field by which the data items are grouped
  hasSubgroups: true, // true if there are subgroups
  items: [
    // either the subgroups or the data items
    {
      aggregates: {
        //nested group aggregates
      },
      field: NESTEDGROUPFIELDNAME,
      hasSubgroups: false,
      items: [
      // data records
      ],
      value: NESTEDGROUPVALUE
    },
    //nestedgroup2, nestedgroup3, etc.
  ],
  value: VALUE // the group key
} /* other groups */
]
<script>
var dataSource = new kendo.data.DataSource({
  transport: {
    /* transport configuration */
  },
  group:[{field: "field"}],
  serverGrouping: true,
  schema: {
    groups: "groups" // groups are returned in the "groups" field of the response
  }
});
</script>
<script>
var dataSource = new kendo.data.DataSource({
  transport: {
    /* transport configuration */
  },
  group:[{field: "field"}],
  serverGrouping: true,
  schema: {
    groups: function(response) {
      return response.groups; // groups are returned in the "groups" field of the response
    }
  }
});
</script>

schema.model

Object|kendo.data.Model

The data item (model) configuration.

If set to an object, the Model.define method will be used to initialize the data source model.

If set to an existing kendo.data.Model instance, the data source will use that instance and will not initialize a new one.

<script>
var dataSource = new kendo.data.DataSource({
  schema: {
    model: {
      id: "ProductID",
      fields: {
        ProductID: {
          //this field will not be editable (default value is true)
          editable: false,
          // a defaultValue will not be assigned (default value is false)
          nullable: true
        },
        ProductName: {
          //set validation rules
          validation: { required: true }
        },
        UnitPrice: {
          //data type of the field {number|string|boolean|date} default is string
          type: "number",
          // used when new model is created
          defaultValue: 42,
          validation: { required: true, min: 1 }
        }
      }
    }
  }
});
</script>
<script>
var Product = kendo.data.Model.define({
  id: "ProductID",
  fields: {
    ProductID: {
      //this field will not be editable (default value is true)
      editable: false,
      // a defaultValue will not be assigned (default value is false)
      nullable: true
    },
    ProductName: {
      //set validation rules
      validation: { required: true }
    },
    UnitPrice: {
      //data type of the field {number|string|boolean|date} default is string
      type: "number",
      // used when new model is created
      defaultValue: 42,
      validation: { required: true, min: 1 }
    }
  }
});
var dataSource = new kendo.data.DataSource({
  schema: {
    model: Product
  }
});
</script>

schema.parse

Function

Executed before the server response is used. Use it to preprocess or parse the server response.

Parameters:responseObject|Array

The initially parsed server response that may need additional modifications.

Returns:Array

—The data items from the response.

<script>
var dataSource = new kendo.data.DataSource({
  transport: {
    read: {
      url: "https://demos.telerik.com/service/v2/core/products"
    }
  },
  schema: {
    parse: function(response) {
      var products = [];
      for (var i = 0; i < response.length; i++) {
        var product = {
          id: response[i].ProductID,
          name: response[i].ProductName
        };
        products.push(product);
      }
      return products;
    }
  }
});
dataSource.fetch(function(){
  var data = dataSource.data();
  var product = data[0];
/* The result can be observed in the DevTools(F12) console of the browser. */
  console.log(product.name); // displays "Chai"
});
</script>

schema.total

Function|String

The field from the server response which contains the total number of data items. Can be set to a function which is called to return the total number of data items for the response.

  • The schema.total setting may be omitted when the Grid is bound to a plain Array (that is, the data items' collection is not a value of a field in the server response). In this case, the length of the response Array will be used.
  • The schema.total must be set if the serverPaging option is set to true or the schema.data option is used.
Returns:Number

—The total number of data items.

<script>
var dataSource = new kendo.data.DataSource({
  transport: {
    /* transport configuration */
  },
  serverGrouping: true,
  schema: {
    total: "total" // total is returned in the "total" field of the response
  }
});
</script>
<script>
var dataSource = new kendo.data.DataSource({
  transport: {
    /* transport configuration */
  },
  serverGrouping: true,
  schema: {
    total: function(response) {
      return response.total; // total is returned in the "total" field of the response
    }
  }
});
</script>

schema.type

String

The type of the response.

The supported values are:

  • "xml"
  • "json"

By default, the schema interprets the server response as JSON.

Default: "json"

<script>
var dataSource = new kendo.data.DataSource({
  data: '<books><book id="1"><title>Secrets of the JavaScript Ninja</title></book></books>',
  schema: {
    // specify the schema is XML
    type: "xml",
    // the XML element which represents a single data record
    data: "/books/book",
    // define the model - the object which will represent a single data record
    model: {
      // configure the fields of the object
      fields: {
        // the "title" field is mapped to the text of the "title" XML element
        title: "title/text()",
        // the "id" field is mapped to the "id" attribute of the "book" XML element
        id: "@cover"
      }
    }
  }
});
dataSource.fetch(function() {
  var books = dataSource.data();
/* The result can be observed in the DevTools(F12) console of the browser. */
  console.log(books[0].title); // displays "Secrets of the JavaScript Ninja"
});
</script>
In this article
schemaschema.aggregatesschema.dataschema.errorsschema.groupsschema.modelschema.parseschema.totalschema.type
Not finding the help you need?
Contact Support