[ADP-706] null and absent semantic

Guidance

• MUST have same semantic for null and absent property

If a property is nullable and not required, a property with null value and an absent property must be considered semantically equivalent.

For example, these two JSON objects should be considered semantically equivalent:

{
  "name": "John",
  "age": null
}

{
  "name": "John"
}

TIP

💡 PATCH endpoints are an exception to this rule (see MUST use HTTP methods correctly). Referring to the example above, a PATCH request with the first object would set the name to John and the age to null, whereas a request with the second object would only modify the name.

• Boolean fields MUST NOT be of null value

• Fields with null value SHOULD be omitted

• Empty arrays and objects SHOULD NOT be null (use [] or {} instead)

null-indicating-unset

• When designing a value to represent unset, and 0/'' has a different meaning than the unset value, you MAY use null and specify the field as nullable (OAI3.0) or potentially null (OAI3.1). It is recommended to document this (null indicating unset) in your API documentation.
  • The behavior regarding unset SHOULD be consistent throughout the project.

INFO

For cases where a field must be designed to accept null and another type, refer to the following.

Implementation Detail

This involves the OpenAPI spec's nullable attribute (in version 3.0, this is indicated by the nullable field, whereas in version 3.1, this is achieved by including null in the array of possible types) and the required property for a field in the schema.

Example in OpenAPI 3.0

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /example:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  age:
                    type: integer
                    nullable: true
                required:
                  - name

Example in OpenAPI 3.1

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
paths:
  /example:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  age:
                    type: [integer, null]
                required:
                  - name

Reference

Design References

• https://api.otto.de/portal/guidelines/r004020
• https://opensource.zalando.com/restful-api-guidelines/#123
• https://schweizerischebundesbahnen.github.io/api-principles/restful/best-practices/#use-same-semantics-for-null-and-absent-properties
• ADIDAS API - JSON

Changelog

• 2024.11.04: Add more null semantic
• 2024.11.15: Add unset semantic