Better document which fields in API can be null

[jacobwhall]

I didn't document well which fields could be returned null vs. those which are guaranteed to always have a specific type.