Empty HAL-Forms options inline attribute should be serialized

[reda-alaoui]

Currently, when HalFormsOptions.Inline#getInline is empty, the JSON inline attribute is excluded from the representation. This is because of:

spring-hateoas/src/main/java/org/springframework/hateoas/mediatype/hal/forms/HalFormsOptions.java

Line 39 in d6265fb

@JsonInclude(Include.NON_EMPTY)

If we take a look at HAL-FORMS specification, we can read what follows:

If the inline attribute is missing or unparseable and the link (see link) attribute is missing or unparseable, then the options element SHOULD be ignored.

Therefore, IMO, from the spec POV, inline has 3 states:

• missing
• empty
• non empty

Spring HATEOAS current behavior reduces this to 2 states:

• missing
• non empty

I think Spring HATEOAS should fix this to correctly represent the 3 states of the specification.

[odrotbohm]

I don't think the spec states what you're suggesting. From the inline section of the spec:

The inline attribute is a JSON array that contains the list of possible values. The inline attribute is OPTIONAL.

So the inline attribute is either a list of values or it's missing. This makes total sense to me, especially as it's in an XOR relationship with the link attribute. I don't see of what value it would be to render an empty collection, especially in light of the final clause in the link section:

If both inline and link elements appear in the same options object, the inline element SHOULD be used and the link element SHOULD NOT be used.

If we rendered an empty collection of inline elements, the link element would never be considered in the first place, which breaks the entire idea of supporting both flavors. I can see that the spec could be more explicit about this, but the way it's written today, an empty inline array doesn't make much sense to me. The exact wording aside, the processing model seems to be "Is the link attribute present, use that. If not, try to find an inline attribute. If present use that. Else invalid.".

Taking a step back: what would be a reasonable use case for rendering an empty inline array?

[reda-alaoui]

Taking a step back: what would be a reasonable use case for rendering an empty inline array?

I am one of the maintainer of https://github.com/badgateway/ketting . I am trying to build an Angular library allowing to generate Angular forms from HAL-Forms via Ketting.

If inline is missing and I follow the specification - the options element SHOULD be ignored - the generated html input will have to be a free text field. But if the inline is present and empty, the generated html input will be a select field with zero option. If the input is not required, a select field with zero option is valid.

In this case (empty inline array), the generated input should be a select field, not a free field.

[reda-alaoui]

If we rendered an empty collection of inline elements, the link element would never be considered in the first place, which breaks the entire idea of supporting both flavors.

You are correct. My pull request didn't account for that. But isn't that an implementation issue? I guess we could make it nullable and exclude it from serialization if null ?

[reda-alaoui]

If we rendered an empty collection of inline elements, the link element would never be considered in the first place, which breaks the entire idea of supporting both flavors.

You are correct. My pull request didn't account for that. But isn't that an implementation issue? I guess we could make it nullable and exclude it from serialization if null ?

In fact, I think it's already handled. HalFormsOptions doesn't allow to mix inline with remote by design (3 distinct public static factory methods) and totally separate types (Inline vs Remote). Am I missing something?

[odrotbohm]

If inline is missing and I follow the specification - the options element SHOULD be ignored - the generated html input will have to be a free text field.

I'm afraid you don't. Again, from the spec (emphasis mine):

The inline attribute is OPTIONAL. If the inline attribute is missing or unparseable and the link (see link) attribute is missing or unparseable, then the options element SHOULD be ignored.

1. inline is optional, i.e., it's okay for it to be missing.
2. The options element is only to be ignored if both inline and link are missing. This is clearly a hint at an either/or relationship between the two attributes that's been the foundation of the design of HalFormsOptions. This is even made explicit in the general definition of the options element.

The options element contains a set of possible values accessible either by value (e.g. options.inline) or by reference (e.g. via options.link.href) and can be used to provide a constrained list of possble values for a property field.

So it's still not clear to me what problem we're trying to solve.

[reda-alaoui]

Let's try to reach a common understanding with an example.

Suppose I receive this (which is the case that made me create this issue). This is what Spring HATEOAS currently outputs if I provide an empty inline array without remote:

{
  "_templates" : {
    "default" : {
      "properties" : [
        {
          "name" : "foo",
          "options" : {
            "minItems" : 0,
            "maxItems" : 1
          }
        }
      ]
    }
  }
}

1. Do we agree that, according to the spec the options field is invalid and should be ignored? (If the inline attribute is missing or unparseable and the link (see link) attribute is missing or unparseable, then the options element SHOULD be ignored.)
2. What kind of html input would you generate? An input of type text or a select box?

IMO, the options is invalid, should be ignored and therefore the client cannot generate a select box because options seems to be the only way to provide the notion of select box to the client:

The options element contains an enumerated list of possible values for a property. This can be used to provide a UI similar to HTML controls such as:

SELECT & OPTIONS

INPUT.type="radio"

INPUT.type="checkbox"

INPUT.type="search" (w/ type-ahead suggestions)

[odrotbohm]

1. The example is invalid, as it contains neither an inline attribute nor a link one.
2. None. The spec clearly states that the invalid options attribute is to be ignored.

IMO, the options is invalid, should be ignored and therefore the client cannot generate a select box…

The sentence should have ended right there. Let me try again: why are you trying to process an invalid element of a HAL Forms document if the spec says it should be ignored under exactly the circumstances you describe?

Wait. Are you saying we shouldn't accept empty collections for the inline(…) factory methods in HalFormsOptions?

[reda-alaoui]

The example is invalid, as it contains neither an inline attribute nor a link one.

This example can be generated via Spring HATEOAS using the following construct:

HalFormsOptions.inline(List.of())
          .withMinItems(0L)
          .withMaxItems(1L);

This is what this issue is about.

why are you trying to process an invalid element of a HAL Forms document if the spec says it should be ignored under exactly the circumstances you describe?

I am trying to change the Spring HATEOAS behavior to avoid having my http client receiving this invalid element.

Wait. Are you saying we shouldn't accept empty collections for the inline(…) factory methods in HalFormsOptions?

No, I am saying an empty collection passed to inline(...) should be serialized as [] instead of being skipped by Jackson serialization.

[odrotbohm]

Which brings us back to the question I raised above:

Taking a step back: what would be a reasonable use case for rendering an empty inline array?

[reda-alaoui]

If the collection of options is built dynamically (e.g. by fetching a database table) you can end up with an inline taking an empty array (e.g. the table is empty).