Lately I was working on some contributions for the Office 365 CLI, specifically on adding files and meta data. When you look at the different documentation available on uploading files and setting meta data on a list item, you come across the usual REST API methods (Files/Add and File/ListItemAllFields). Using both method will let you upload files and set metadata on the corresponding list item. One of the drawbacks on using these methods is that setting some types of meta data is cumbersome, like taxonomy, user and lookup fields. For instance, to update a taxonomy field you should construct an object in the following manner:

  MetaData: {
    __metadata: { "type": "SP.Taxonomy.TaxonomyFieldValue" },
    Label: "1",
    TermGuid: "499FF84B-82F6-4098-BAAB-9466248EBD2F",
    WssId: -1

Updating metadata using such constructs and especially when using multi value columns, is a tricky way of updating such fields.

Another drawback could be that if you use versioning on your document library, the above methods will create 2 versions when uploading a file and adding meta data. While working on the Office 365 CLI, I came across the ValidateUpdateListItem method. This is a method on a list item and can be used to update list items. The nice thing on this endpoint is it has a property called ‘bNewDocumentUpdate’. Microsoft documentation specifies:

bNewDocumentUpdate Set to false to create a list item

It wasn’t really clear to me what this property was actually doing, but after some more digging it is actually very similar to the UpdateOverwriteVersion method available on the server API. So when you use the ValidateUpdateListItem method and set the bNewDocumentUpdate property to true, it will call the UpdateOverwriteVersion method, which will update the item without incrementing the version. This will result in only 1 new version. Nice!

Specify field values

The ValidateUpdateListItem method lets you update meta data on a list item by adding a formValues array to the body of the REST API post request.

"formValues": [ 
  { "FieldName": "Title", 
    "FieldValue": "Item" } 
"bNewDocumentUpdate": false

There isn’t very much documentation available around the ValidateUpdateListItem method and setting its field values for the different kind of field types the list items could have. Below I will sum-up the different kind of fields and its fieldValue format:

Taxonomy Field (single value):


Taxonomy Field (multiple values):


Person Field (single value):


Person Field (multiple values):


Hyperlink Field:


The last advantage the ValidateUpdateListItem() method has, is that the method will give you a response in the following format:
{ "value": [ 
  { "ErrorMessage": null, 
    "FieldName": "Title", 
    "FieldValue": "Item", 
    "HasException": false, 
    "ItemId": 0 }, 
  { "ErrorMessage": null, 
    "FieldName": "Id", 
    "FieldValue": "1", 
    "HasException": false, 
    "ItemId": 0 
] }
The value property in the response holds an array for each updated Field. When an exception occurs on updating a Field, the HasException will be true and an error message will be supplied in the ErrorMessage property. Very useful to provide feedback to your user when something goes wrong on updating the fields! When the update is successful, the ItemId property will also hold the ID of the ListItem.


Using the regular ListItemAllFields Update REST API endpoint is sometimes cumbersome in providing the correct constructs of objects for the values of the meta data. Next to this the endpoint will create 2 versions of the item when using Versioning on the library. The ValidateUpdateListItem() method on the List Item object is much easier in providing the field values for the fields to update. Next to this it has an option to specify, if to only create 1 version for the update on the list item, after uploading a file. Last but not least it will give you a response in order to let you check if the updates on the fields where successful or not and give validation errors back to your user.