Unknown fields

When the API receives JSON containing fields that are not recognized or used by the endpoint, it will — on a best-effort basis — return an X-TD-Unknown-Fields header. This header contains a comma-separated list of the unrecognized fields.

While receiving unknown fields is not considered an error, it may indicate a potential issue, such as incorrect or misspelled field names. Monitoring this header can help identify and correct such mistakes.

For example, if the header returns valid_fro,name, it suggests that the valid_fro field was misspelled (it should be valid_from), and the field name is not used by this endpoint.

Implicit fields

When the API does not receive a field which is documented to be optional, it will use the default value for that field. If the default value of a field is undocumented, then the default value of that field is null.

Some fields that are optional in the API should not have been optional to begin with as not specifying these fields can have unintended results. The most significant examples of this are fields on the “Replace or Create” endpoints. See Replace-Update endpoints for more details.

Fields can not be made required without breaking users that rely on the fields being optional. That is why we have added the X-TD-Implicit-Fields header. This header is added to the response when a field was not provided even though the field should be required (much like the X-TD-Unknown-Fields header). Importantly, this allows users to detect potential issues without breaking anyones implementation.

In the future, we intend to make these fields required from the start. Existing fields can be made required gradually when there is enough evidence that no user relies on the field being optional.