Next.js Discord

Discord Forum

How Should We Handle Optional Properties in Our API Schema?

Unanswered
Stabyhoun posted this in #help-forum
Open in Discord
StabyhounOP
Hello everyone! đź‘‹

I’m looking for some feedback from frontend and full-stack engineers on handling optional properties in our API schema. We’re developing a headless API designed to serve as a “Backend for Frontends” (BFF), enabling you to build custom frontend applications on top of it. Your insights are incredibly valuable to us!

The Question:
In our API, “optional” properties refer to fields that users can designate as non-mandatory when designing their data models. This flexibility allows users to define the structure of records that our API returns. For example, a blog post might have tags, but it doesn’t have to, or a product might have scaled pricing, but this isn’t mandatory.

We’re considering several approaches to represent these optional properties in our API responses, and we’d love your feedback on which approach you think works best.

I’ll share the different approaches in the comments. We would be super grateful if you would share which version you would prefer and why.

We’d love to hear your thoughts:

• Which approach do you find more intuitive or easier to work with in your frontend applications?
• Which approach do you think would minimize errors or edge cases?
• Are there any best practices or patterns you’ve seen that we should consider?

4 Replies

StabyhounOP
V1: Standard Approach (Empty Values for No Data)

Schema Definition:

{
  "name": "string",
  "email": "string",
  "tags": "string[]"
}


Sample Response When No Value is Present:

{
  "name": "foo",
  "email": "",
  "tags": []
}


In this approach, an empty string or an empty array is used to indicate "no value" for email and tags, respectively. This makes it clear that the property exists but currently has no data.
V2: Omitting Optional Properties from the Response

Schema Definition:

{
  "name": "string",
  "email?": "string",
  "tags?": "string[]"
}


Sample Response When No Value is Present:

{
  "name": "foo"
}


Here, the email and tags properties are marked as optional. If no data is present, these fields are omitted entirely from the response. This keeps the response lightweight but may require additional checks in the frontend to handle undefined properties.

Schema Definition:

{
  "name": "string",
  "email?": "string",
  "tags?": "string[]"
}


Sample Response When No Value is Present:

{
  "name": "foo"
}


Here, the email and tags properties are marked as optional. If no data is present, these fields are omitted entirely from the response. This keeps the response lightweight but may require additional checks in the frontend to handle undefined properties.
V3: Using null to Represent Missing Data

Schema Definition:

{
  "name": "string",
  "email": "string | null",
  "tags": "string[] | null"
}


Sample Response When No Value is Present:

{
  "name": "foo",
  "email": null,
  "tags": null
}


This approach ensures a consistent response structure by always including all fields, using null to indicate the absence of a value. This can make it easier for the frontend to handle responses but may introduce null checks in your application logic.
V4: Differentiating Between Single Values and Lists

Schema Definition:

{
  "name": "string",
  "email": "string | null",
  "tags": "string[]"
}


Sample Response When No Value is Present:

{
  "name": "foo",
  "email": null,
  "tags": []
}


In this approach, optional single-value fields are represented as null and optional list fields as empty arrays. This distinction helps differentiate between the absence of a value and an empty collection.