API JSON Conventions

JSON does not specify representations of all data types; this is a guide to how the NOLS API interprets resources in JSON format. This does not reiterate the JSON specification, it highlights the grey areas.

booleans

Use true or false: the API will reject null values.

numbers (integers and floats)

Use well-formed numbers per JSON spec: null is used for non-values.

strings

For INPUT use strings per JSON spec: empty strings "" and null are interpreted as non-values.

For OUTPUT the API will always return empty strings for non-values.

numbers (full precision decimals)

A special case of strings.

For INPUT use string of digits with fixed point of ".". Empty strings "" and null are interpreted as non-values.

For OUTPUT the API will always return null for non-values.

dates

A special case of strings.

For INPUT use ISO-8601 date format "YYYY-MM-DD". Empty strings "" and null are interpreted as non-values.

OUTPUT will always be in "YYYY-MM-DD" format or null for non-values.

date-times

A special case of strings.

For INPUT use ECMA-262 date time format ("YYYY-MM-DDTHH:mm:ss.sssZ" or "YYYY-MM-DDTHH:mm:ss.sss+-HH:mm"). Empty strings "" and null are interpreted as non-values. Fractional seconds will always be accepted, but ignored in some cases depending on underlying data storage.

OUTPUT will always be in "YYYY-MM-DDTHH:mm:ss.sssZ" format (UTC, optional fractional seconds) or null for non-values.