Marking Required Fields

by Robert Delwood, a Lead API Documentation Writer

Few things in API documentation are ever simple. Take the case of the required field. It seems obvious that fields are either required or optional, and how to mark them. However, when getting to the details, it becomes neither obvious nor clear. Let me explain.

I’ve identified several requirement cases. The terminology is mine and it’s not the best. I define a field as being required if the call fails if it’s not present. This means there isn’t even a smart default for it. For example, a client name field might be required because there isn’t any way to have a default for that.

Required

This object or field is required. This is the simplest case and one everyone thinks about for a required field. The request will fail if that field is not provided. Mark the field Required.

Example 1. The field name is required. The call fails if name is not provided.

Optional

This is a simple case and one everyone thinks about for an optional field. The request will succeed even if that field is not provided. However, many API documentation suite standards, such as OpenAPI, don’t have an explicit Optional marker. In those cases, items not marked as Required implies being optional. A workaround includes using the field description, such as “Specifies an optional field that…” This is valid, although I personally find it awkward in long documents. I do use it one case later.

Example 2. The fields id and name are required. The call fails if both are not provided. Field tag is optional and may be omitted safely.

Conditional

Some fields may be required by a condition.

I call one instance positive conditionally required. This is a case that additional fields may be required based on a condition. For example, the image below states that if the address field is included then the postal code field must also be included.

Example 3. Neither field streetAddress or postalcode is required; the call can be successful without either one. It’s only by notation that streetAddress can present. If it is present, then postalCode must also be present.

Some fields may be excluded by a condition I call this instance negative conditionally required. This is a case that fields may have to be excluded based on a condition. For example, if a street address is included, then geolocation coordinates must not be included.

These cases can be the most difficult to mark, or even understand. It’s because they’re arbitrary. There is no pattern or predictability. It’s up to the way the developers designed it. They are good candidates for writers pushing back. A lot of conditions or unclear conditions make for a bad developer experience. Until it’s changed, writers just have to handle it in documentation. You might even get into odd cases. A phone number may be optional, in that the minimum character count is zero, unless the user enters a phone number, and the minimum becomes ten.

For marking these, it’ll have to be up to the writers and developers on a per case basis. How ever it’s decided, each of the fields has to be marked, not just the first one or some of them. There’s no telling how clients got to the field, perhaps by the browser search or chance. There’s no guarantee, they’d get to the first mention first.

Object required

Objects present a special case. An object is required if any of its members (other objects or any field) are Required. In this instance, mark all fields as noted above. If any fields get marked, then the object itself become required. Add the Required notation to the object.

Example 4. The object category is required since one of its fields, id, is required.

Optional required

In this case, the object itself is optional. That is, there are no required fields for making the call successful and omitting the object is valid. However, if the object is included, then there may be required fields. For this, mark the individual fields Required. However, do not mark the object as required.

Example 5. The object category is optional. However, if it is included, then both fields, id and name, are required.

This marking practice is the riskiest because it depends on consistency. It has to be marked the same way every time. It’s a limitation of the OpenAPI standard. If your team has the ability to add a new notation, perhaps if you’re using Word, then add your own term. One workaround would be to describe it as optional in the description.

Response fields

Response fields do have the concept of being required or not. A required response field means it’ll always be present in the returned object. However, I don’t mark them as Required. In the application’s code, the developer has to check for the existence of the field before reading it anyhow. So, regardless, as a matter of a best practice, there is no need for marking them. Writers and developers can decide this for their document.