Openapi: we need an Array and fields contract.

[carlosthe19916]

The REST Endpoints are growing and we need a formal contract between server and client. Without it the client never knows what to expect from the backend.

Arrays

It has been mentioned in some discussions that fields whose type is an array should never been NULL but rather an empty array or an array with values.

What is our position on this? I personally suggest having an empty array rather than NULL

Fields

Let's use the Openapi definition to know which fields are mandatory and which ones are optional (nullable). When using Swagger the mandatory fields always have a red cross next to the field name.

I suggest appropriately using this as it would simplistic to mask every field as optional and avoid having a proper design.

[bobmcwhirter]

We can certainly emit empty arrays when there's no data, instead of skipping the field.

[ctron]

I don't think we ever have null. We might skip the field, or have an empty array.

[ctron]

Just to be clear.

Skipped:

{}

Null:

{
  "items": null,
}

Empty:

{
  "items": [],
}

[bobmcwhirter]

True, but Javascript, being a little special, makes obj.items undefined in both of the first two cases, afaik.

[chirino]

null and undefined are slightly different in JS and the difference is testable.

[carlosthe19916]

Perhaps I shouldn't have used the word "null" as it is a particular thing of a language. Sorry for that. My main point is:

• For fields whose type is an array then always return a value. An empty array or an array with values
  • I wonder is there is a global way of configuring Serde or whatever tool the backend is using to avoid this things even being discussed. Configuring these things field by field is error prone. I can see lines of code like:

trustify/modules/fundamental/src/vulnerability/model/mod.rs

Lines 21 to 22 in ea568e0

	#[serde(default, skip_serializing_if = "is_false")]
	pub normative: bool,

trustify/modules/importer/src/model/sbom.rs

Lines 11 to 12 in ea568e0

	#[serde(default, skip_serializing_if = "Vec::is_empty")]
	pub keys: Vec<Url>,

• For fields whose type is string|number then we should document them appropriately in the openapi spec as it represents the contract between clients-server

My original intention is to avoid issues like the one reported here trustification/trustify-ui#114 .

[ctron]

That's a tricky thing, and I actually tried coming up with Rust RFC, trying to capture exactly that problem. Which resulted in an PoC crate: https://github.com/ctron/isx

Right now, there is no global definition of "empty" in the Rust ecosystem. Therefore serde allows providing that with a custom attribute. For some types "empty" is simple (Option, Vec, *Map). For others, it isn't (String, integers, boolean). In such cases, people tend to go for "is default". Which hover is specific to the type. And might be specific to the language's ecosystem.

So I think your proposal of coming up with a set of rules for our project makes perfect sense. My proposal would be to omit everything that could be "empty", from the perspective of a "contains no elements" perspective. That should work well for Option and any kind of list, map. I might hope this should also work well in the TypeScript ecosystem.

All other values (strings, booleans, integers, …) should either be wrapped into Option explicitly, or never be skipped.