Question

I am building a web service API, using JSON as the data language. Designing the structure of the data returned from the service, I am having some trouble deciding how to deal with missing values.

Consider this example: I have a product in my web store for which the price is yet unknown, maybe because the product has not yet been released. Do I include price: null (as shown below) or do I simply omit the price property on this item?

{
    name: 'OSX 10.6.10',
    brand: 'Apple',
    price: null
}

My main concern is making the API as easy to consume as possible. The explicit null value makes it clear that a price can be expected on a product, but at the other hand it seems like wasted bytes. There could be a whole bunch of properties that are completely irrelevant to this particular product, while relevant for other products – should I show these as explicitly null as well?

{
    name: 'OSX 10.6.10',
    price: 29.95,
    color: null,
    size: null
}

Are there any “best practices” on web service design, favoring explicit or implicit null values? Any de-facto standard? Or does it depend entirely on the use case?

Answer 1

FWIW, my personal opinion:

Do I include price: null (as shown below) or do I simply omit the price property on this item?

I would set the values of “standard” fields to null. Although JSON is often used with JavaScript and there, missing properties can be handled similarly as the ones set to null, this must not be the case for other languages (e.g. Java). Having to test first whether a field is present seems inconvenient. Setting the values to null but having the fields present would be more consistent.

There could be a whole bunch of properties that are completely irrelevant to this particular product, while relevant for other products – should I show these as explicitly null as well?

I would only include those fields that are relevant for a product (e.g. not pages for a CD). It’s the client’s task to deal with these “optional” fields properly. If you have no value for a certain field which is relavant to a product, set it to null too.

---

As already said, the most important thing is to be consistent and to clearly specify which fields can be expected. You can reduce the data size using gzip compression.