Form with omissible field member

[niklase]

Hi @lhazlewood.

I miss the possibility to declare a Form Field Member as possible to omit when submitting a Form. This can be useful in for example a CRUD update scenario where semantics of setting a Member value to null would overwrite (3) persisted Member value with the null value while omitting the field when submitting the form would not affect the persisted Member value at all (2). (Or if complying with RFC 7396 - delete the persisted Field Member when Field Member in request is null)

In other words I want to be able to specify one Form where both 2 and 3 below are valid Form Submission Objects.

Scenario:

1:
PUT /person/1
{"name": "Peter", "age": 10} -> persisted Resource={"name": "Peter", "age": 10}

2:
PATCH /person/1
{"age": 11} -> persisted Resource={"name": "Peter", "age": 11}

3:
PATCH /person/1
{"name": null, "age": 12} -> persisted Resource={"name": null, "age": 12}

There are ways around this to accomplish almost the same thing. As I understand it I can for example use the 'mutable' Form Field Member and resend the Field Member value as it was persisted (with extra data on the wire as a consequence).

Please correct me if I have missed something but from my point of view this is something that should be possible to express in the form.

What are your thoughts on this?

[lhazlewood]

Ah, good catch! The required attribute was originally intended to support both nullable and omissible fields, but the current wording doesn't cover that. I think we need to update the wording in that section or even think of a new technique to allow null vs omitted vs neither. Any ideas?

So for a resulting Form Submission Object (FSO), it seems like a field can be:

• omissible,nullable - not required to be present in the FSO at all, but if it is, null is allowed
• omissible,nonnullable - not required to be present in the FSO, but if it is, null is not allowed
• required,nullable - must be in the FSO, but null is allowed
• required,nonnullable - must be in the FSO, and null is not allowed.

Given 4 possible states, it seems that two booleans would work:

• required stays and is a boolean, but it no longer represents null semantics. It means simply whether or not the field must be in the resulting FSO. Default value is false.
• a new form field, e.g. nullable as a boolean. Default value is true.

Thoughts?

[lhazlewood]

Actually on second thought, I thinknullable should be false by default since null is evil and should be consciously enabled. Modern programming languages (like Kotlin) take a similar stance.

[niklase]

Hi.
required (semantically meaning omissible field) and nullable (semantically meaning field value can be null), defaulting required to true and nullable to false would be the most intuitive naming and behaviour from my point of view.

If I get a list of fields that I am supposed to provide to perform some action (REST service) I would expect them to be required if nothing else is said. Do not know If the analogy is good enough but if I read a recipe when cooking something I expect the ingredients to be required if nothing else is written... :)

[lhazlewood]

Hrm - I think required defaulting to true is strange and shouldn't be the default. If you look at HTML forms and SQL (for example), all of them are optional unless specified as required.

For example, consider a user creation endpoint, e.g. POST /users with an HTML form, where a user could have:

• username
• email
• password
• surname
• givenName
• middleNames
• dateOfBirth
• favoriteColor
• photoUrl
• postalAddress
  etc, etc

it doesn't make sense in this case that all of these would be required by default. Indeed, most could be optional during creation (except maybe password and email or username), and in update, practically all are optional.

I think that's why HTML and SQL take the optional-by-default/required-is-explicit stance.

I believe most data in heterogeneous systems is optional (or very nearly close to 50/50, with a slight edge to optional), which is why I think required should be false by default. Conversely, if data is specified, most systems don't want that data to be null/empty, which is why I think nullable should be false by default as well.

Does this make sense? Was I able to convince you? ;) Thoughts?

[lhazlewood]

P.S. I'm slightly in favor of a required default of false based on my description above. I'm definitely not 100% convinced either way and I'm definitely open to persuasion :)

@dogeared @nbarbettini @fosrias @smizell any thoughts about this?

[niklase]

In XSD the minOccurs for an element is 1 by default meaning you have to set minOccurs=0 to make the element optional.

RAML defaults to required = true for parameters.

OpenAPI/Swagger defaults to required = false.

One thing to consider is the context of the client developers/API users. If they are used to work with SOAP or RAML it is maybe more intuitive with required = true as default but as such developers may be just as familiar with OpenAPI/Swagger this does not help me sorting out what should be the best default value...

So from my point of view the important thing is the default value is specified - true or false may just be a matter of taste :)

[nbarbettini]

I think that required: false and nullable: false both feel like the most natural, JSONy defaults. I could imagine a lot of extra noise if required was true by default.