Validation: Extension of First-Class Citizen?

[Kevin Swiber]

Greetings!

I've been spending some time thinking about extensions to Siren, and I remembered a Pull Request submitted by Gabriel Castillo some time ago.  The PR was to add HTML 5 Validation support to Siren.

I re-opened a conversation on GitHub, but I wanted to hit up the list, too.  Any thoughts on this?  Should validation be first-class or provided by an extension?

See: https://github.com/kevinswiber/siren/pull/12

Cheers,

--
Kevin Swiber

Projects: https://github.com/kevinswiber
Twitter: @kevinswiber

[Manuel Gómez]

On Sat, Feb 1, 2014 at 7:46 PM, Kevin Swiber <ksw...@gmail.com> wrote:
> Any thoughts on this? Should validation be first-class or provided by an
> extension?
>
> See: https://github.com/kevinswiber/siren/pull/12

I believe this should address the broader issue of a rich
specification of the server’s expectations for how action fields are
to be procured. For simple types, like length-limited text or number
ranges, this is easy enough to specify with the proposed properties.
However, it would be very useful (to me, at least) to have some
established concept of how more complex type or format specifications
could be provided to clients.

My particular use cases are rather complex: some of the fields I need
in my API’s actions are actually complex (JSON) objects with a
particular structure (and yes, it makes sense for them to be simple
action fields and entity properties, not full separate entities — it’s
a long story, but such use cases do exist). Other action fields in my
use case would in fact be the URIs that correspond to other resources
in the API that belongs to some collection resource — again, while
conventionally that would mean some sort of action on that other
resource, it does make sense in my use case to put an URI in a field
(and it’s a long story). I can also imagine some would want
validation based on a regex or something of the sort.

I’m not suggesting Siren should directly address these relatively
complex and somewhat unusual use cases directly. It would make sense
for these concepts to be dealt with some sort of domain-specific
extension to the format. My point is that validation is a lot more
than number ranges and common types! It would perhaps be a worthy
effort to address the arguably common case of numeric ranges directly
in the core format, though, and if this is a common sentiment, do
disregard this message. :)

[Gabriel Castillo]

 

some of the fields I need
in my API’s actions are actually complex (JSON) objects with a
particular structure

While I haven't had to deal with validation that is extra-ordinarily complex, In times when we have had to create properties that are objects (instead of making them entities) we have made each property of the object a field.

fields = [

   {name: door.color, type: text}

   , {name: door.height, type: number}

   , {name: door.width, type: number}

 ]

In cases where this is not enough, we've also played around with the idea of having "custom" field types in addition to the ones provided by the HTML5 spec.  These custom field types would be specific to your domain and would probably need to be documented somewhere so that Siren clients know how to handle them.  (This is just a concept, over at Kiva, we haven't actually implemented this).  This may be frowned upon, and thus it would be great to have some feedback.

One thing we have implemented (in a rather half-ass way and I just haven't gotten around to soliciting feedback from the community) is enumeration types.  For this we've added an "options" attribute on the field.  An example direct from our API:

fields: [

{name:sendRepaymentNotifications, type:radio, options:[monthly, nightly, none]}

, {name:sendAutolendingNotifications, type:radio, options:[monthly, nightly, none]}

]

"options" is something that we just quickly whipped up and I'll post in a separate thread on wether that's a good way to address enumeration types.

 

[Alex Soto]

Just comments on other possibilities (none of which I have tried):

To pattern it after existing html radio buttons, you have a field for every possible value, with the value attribute set to one of the options.  The con to this is it is verbose, but the pro is that it's a familiar pattern.

--
You received this message because you are subscribed to the Google Groups "Siren Hypermedia" group.
To unsubscribe from this group and stop receiving emails from it, send an email to siren-hypermed...@googlegroups.com.
To post to this group, send email to siren-hy...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/siren-hypermedia/a9091552-e95f-4660-b2e5-59eb70e45aaf%40googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

[Manuel Gómez]

(repeating a slightly augmented reply to Gabriel that accidentally
went off-list)

On Mon, Feb 3, 2014 at 4:26 PM, Gabriel Castillo <gab...@uglymunky.com> wrote:
> While I haven't had to deal with validation that is extra-ordinarily
> complex, In times when we have had to create properties that are objects
> (instead of making them entities) we have made each property of the object a
> field.
>
> fields = [
> {name: door.color, type: text}
> , {name: door.height, type: number}
> , {name: door.width, type: number}
> ]

Indeed this is a good strategy for nested records when the structure
is static. However, consider something like a variant record where
the presence of a field should exclude the presence of (some) others.
Perhaps even something involving recursive variant record types: the
API I’m working on has a resource with a property that is actually a
JSON-encoded logic expression AST. (I do think it’s a bit of a stretch
to think Siren’s validation specification should handle something like
this, but it’s worth thinking about this sort of structural validation
even if it’s impractical to make it this expressive.)

Consider also fields whose values should be one of a fixed (or
server-provided) set of values, such as in an enumerated type, or a
select HTML control. This is very common in Web forms. This is
indeed addressed by your options proposal, at least if the set of
options can be described as simple text values — but it might be
desirable to provide a title for presentation along with the actual
field value.

Consider even fields whose values should be one of a set of values
known by the server, but with a large set of possible values that
could change depending on the state of resources in the server, such
that it would be bad to include the full enumeration of options in the
action field type: in my use case, field values sometimes are the
URIs of resources included in some collection. This could be
modeled somewhat easily by providing the URI for the collection
resource as the field type, and clients could then query the collection
resource for linked or embedded resources with, say, the `item`
relation type, to procure the valid potential values for such a field.
This is what I mean by the distinction between how to validate,
and how to procure valid values: instead of informing the client of
how to decide whether user input forms an acceptable value for a
field, perhaps the server ought to inform the client how to ask for
or search for values that are valid, perhaps in ways that make more
sense for a given application than “here’s a (possibly huge) list of
every valid thing you may provide for this field”.

I insist that these are just some random ideas inspired by the API I’m
currently working on, and I’m not convinced (or trying to convince
anyone) that it’s wise for Siren itself to support specifying field
types with this degree of detail. I suspect in many cases it could be
easier to solve this sort of issue with a more granular definition of
resources for the API. I do dream of a full algebraic type
specification format for the Web, though :)