Valid Null JSON Field Format?

[esparano]

Forgive me if this was specified somewhere, but what is the correct way to represent null fields or empty arrays in JSON? I've seen it represented a few different ways.

For example, say an operation has no contingency plans (because it is not a required field). Would the operation look like this:

{
   ...
}

like this:

{
    ...
    contingency_plans: null,
    ...
}

or like this?:

{
   ...
   contingency_plans: [],
   ...
}

I'm handling all three on my end just in case, but which way should we produce JSON so that the NASA systems (or other USSs) accept it?

Same goes for missing metadata, priority_elements, etc.

[nasajoey]

These are all valid per JSON spec. However, the may be interpreted differently by systems. We can note best practices for UTM. My initial gut feeling is that we shouldn't send nulls. Those are interpreted (I think) as if the key was not even sent. Assuming that is true, you just shouldn't send it. If you send an empty array, that is understood as the array being sent and not having any values.
This will satisfy the "required" aspect of any array, according to JSON and UTM spec. If we want to be clearer, for those required arrays we should probably make minItems = 1. Thoughts?

[nasajoey]

This isn't documented anywhere at the moment and really has never been discussed.

[esparano]

I agree that sending less is better where possible, so your suggestions make sense to me. I'd like input from others if they have an opinion about it, though!

[nasajoey]

No input from others for almost 2 months. I'm going to call it official:

1. Don't send null values for optional fields. Rather, leave the key out of your JSON.
2. If an array is required, the spec should clarify if minItems is 1 or 0.
3. Null for required fields should be disallowed at the swagger level by adding minLength for strings and other indicators to eliminate nulls.

@esparano does this sound about right?

[ktian94]

@nasajoey: We can ensure we don't send null values for optional fields, but it may be difficult for us to enforce this on requests we receive as doing something below is considered valid JSON. If we receive a key with the value null and the field is nullable, can we still accept the request?

{
    ...
    contingency_plans: null,
    ...
}

[nasajoey]

I think items 2 and 3 above address this. In the spec, if an array field is required, we'll move to making the minItems = 1. If the array field is not required, then we'll have an agreement on the protocol (above JSON spec) to not allow null... optional fields that are null should just not be sent.

[ktian94]

What’s the reason for deviating from valid JSON spec? I saw you mentioned that it “may be interpreted differently by systems”, but the JSON spec is an open standard that should be consistent across systems, no?

Sorry, I probably should’ve brought this question up earlier.

[nasajoey]

i was told some frameworks may do odd things with a null field, potentially against spec. If a null is properly sent, some systems may treat that field as unsent and some count it as sent. Not sure if this is a problem, but inconsistency sounds bad.

I'm not super invested in this decision at this point. would be happy to hear from others. as with other decisions, leaning on existing spec sounds better to me.

[esparano]

I guess this is similar to my question about accepting valid ISO-8601 datetimes. We are using subsets of accepted standards, and there is a difference between sending in the required format and being required to reject valid data that isn't part of our subset.

I agree with the three bullet points you wrote, @nasajoey!