Encode the relation between some action fields and CollectionJSON entities

[velveteer]

In order to derive HTML forms in the client Siren provides action field types that map directly to HTML5 input types. Right now for character creation the client knows about two fields: race and discpline, both with a type of url. If we derived the form with this information then we would be presenting two text inputs with URL pattern validation. It should be obvious that this is unacceptable for users, they don't know our URIs.

It turns out that race and discipline are represented by CollectionJSON entities, which are provided as links on the Characters entity with identifiers races and disciplines. So for a better user experience we can have users select a race and discipline from the items in these collections. The client needs to turn the relative hrefs on these items into absolute URIs in order to satisfy the url type on the field, but this can likely be derived without the schema from the value of the hrefs themselves.

My problem is that the client doesn't know that a race field can be represented as a HTML <select> tag with <option> tags populated from the items in the races collection, where the <option> values are the item hrefs. Knowing this information would enable the client to derive the special case where a field has an enumerable value in the presentation layer.

It may be possible to use the class of the field to inform the client of this implementation-specific behavior. I don't know if enough information can be conveyed with the class alone. Something like [ 'collection' ] would allow the client to assume that this field has an associated collection...but what is it called? In our case I can simply pluralize race to races and resolve this collection if it exists on the entity. Admittedly this is not ideal. And this doesn't help me know that I am supposed to use the item hrefs as the option values, I only know that a collection might exist for this field.

Would a POD be out of scope for this problem? It could instruct the client of specific fields that would need extra logic at the presentation layer. I understand this is also an issue of relations, so if we can solve it in Siren then we should. But the amount of information that needs to be encoded here may be difficult or impossible to represent as Siren relations. To reiterate, this information is:

1. A field can be represented as a dropdown/select with options
2. These options should be populated from a specific CollectionJSON entity
3. The value of each option is the href of each collection item

[alunduil]

I like the idea of race and discipline being select on the client, but I don't believe it's accurate for the representation to force only those choices at an API level. I think the representation does need to say I expect a URI that will parse as a race or discipline accordingly.

I agree this leads to a problem of the client needing to know what is available to handle these properties but I wonder if this is a situation where a profile would make things better.

Also, note that there is only a subset of HTML5 form types specified in the siren specification which begs the question and forces us to answer it. I'd have to review the profile discussion and see if we can add a profile to the type of the action (thereby getting more semantic meaning behind the fields). Unfortunately, the actions themselves don't have classes, but using the representation's class may be an option as well.

You'll have to remind what a POD is, but if I'm not mistaken it's similar to what I'm proposing above.

To summarize answers to your enumerated points:

1. siren does not have support for this mechanism and we either add it or find another semantic that makes it moot
2. see 1
3. this would obviate the need for the previous caching discussion we had

If I'm understanding this issue correctly, we should investigate profiles to capture information about the actions, and possibly the resources. This would allow us to link to the appropriate information and present it without issue. You'd be able to grab that this field has these default choices, etc. Regardless, I think I need to think about this a bit more and would love a sanity check on what I've proposed so far.

[velveteer]

From my understanding a POD exists to augment the client with additional information for presentation logic. The spec is here: http://rwcbook.github.io/pod-spec/

It is mainly used for metadata on display items, but our use case is around displaying Siren action fields. The spec allows for extensions to the POD, which I believe should allow us to specify render information for action fields. Amundsen calls his implementation for the Siren client a SOP, Siren Object Profile, and there's an example of how it's used to conditionally render entity properties: https://github.com/RWCBook/siren-client-pod/blob/master/files/siren-client.js#L158.

In his example he also adds a new link to the entity that looks like:

{  
  "rel": ["profile"],  
  "href": "/files/user.pod",  
  "class": ["user"],  
  "type": "application/prs.profile-object-desc+json"
}

I am trying to figure out if it's worth the extra effort for two form fields, and if this is a pattern we want to solve for before it becomes ubiquitous. For now I can use a client-side POD (or some form of metadata) in order to get this moving, and once that is structured we can look into adding it to the API, moving the "internal" knowledge to "external" knowledge, to quote Amundsen in his section on the POD. Even in this same section he admits the POD is ad-hoc and was designed only for his use case, which means Siren appears to require some form of client metadata one way or another, at least as long as we are not rendering a plain HTML form with primitive values.

[alunduil]

Can you show me an example of that approach with our characters representation? I'm having a hard time mapping it mentally. It almost looks like we'd get rid of the races and disciplines links and use those profiles instead if I'm reading it correctly. I like that idea a lot but want to make sure I understand this as well.

[alunduil]

I'd say we want to solve this well, because eventually it will be the same pattern that we use for talents and spells. Probably even equipment and other secondary elements.

[github-actions[bot]]

-| This issue has not been updated in 90 days. It will be closed in 90 days if no further activity occurs. Please respond if you would like to keep it open.