[ADP-320] Array Convention

Guidance

Empty Arrays

• MUST NOT use null for empty arrays.
• Arrays SHOULD be empty ([]) and not null if there is no data to provide.

Example:

{
  "entries": []
}

Do not use:

{
  "entries": null
}

Array Consistency

• MUST maintain consistent array structures across API responses.
• SHOULD use the same field names and data types for array elements across different endpoints.

Array Limits

• SHOULD define and document maximum array sizes to prevent performance issues.
• MAY implement pagination for large arrays (see ADP-312: Pagination).

Array Ordering

• SHOULD maintain a consistent default ordering for array elements.
• MAY provide sorting options for arrays (see ADP-313: Sorting).

Related ADPs

• ADP-312: Pagination
• ADP-313: Sorting
• ADP-701: Property Design
• ADP-754: OpenAPI JSON Schema

References

• JSON Specification (RFC 8259)
• Google JSON Style Guide