[ADP-321] Omit Empty

Guidelines

• Although null and absent has the same semantic, SHOULD omit optional properties when they are empty or null.

• MUST document optional fields with OpenAPI description explaining when they are optional.

  application/json:
    schema:
      type: object
      required: [id, name]
      properties:
        id:
          type: string
        name:
          type: string
        nickname:
          type: string
          description: "When the user is a guest, this field is optional."
          nullable: true

• MUST NOT include null values for optional properties.

  • In rare cases, when handling uninitialized states, if 0/-1 cannot be used to indicate an uninitialized state (already has other meaning), MAY use null values, and explain in the description field. At this time, null does not represent an optional field.

  application/json:
    schema:
      type: object
      properties:
        id:
          type: string
        temperature:
          type:
            - number
            - 'null'
          description: |
            The latest temperature reading in Celsius.
            If `null`, it indicates the sensor has not yet been initialized.

• SHOULD consider the semantic difference between an absent property and an explicitly set null value.

Examples

DO

{
  "paymentMethod": "INVOICE_SINGLE"
}

DON'T

{
  "paymentMethod": "INVOICE_SINGLE",
  "installments": null
}

Changelog

• 2025.03.31: Add optional field description rule.