Proposal: Add validations to the data array

[glanotte]

Reference: https://groups.google.com/forum/?fromgroups=#!topic/collectionjson/Q2dnK82ok9A

Use Case: We would like to add the ability to pass validation information along to our front end clients to compliment our server-side validations. This is to help reduce potentially expensive operations on the server. Our particular scenario is to try to catch invalid file uploads before they are uploaded, but we see opportunities to use this to enrich our UX by having more responsive validations and reduce the risk of a divergence of logic between the two.

The proposed format for the validators is:

{
  "collection": {
    "version": "1.0",
    "href": "http://www.example.com/file_upload",
    "template":{
      "data": [{
        "name": "file",
        "value": null,
        "validations": [{
          "name": "file_size",
          "value": [0, 2097152],
          "prompt": "The maximum size for a file"
        }, {
          "name": "file_type",
          "value": ["png", "bmp", "jpg", "gif"],
          "prompt": "allowed file types"
        }]
      },{
        "name": "label",
        "value": null,
        "validations": [{
          "name": "length",
          "value": [0, 50],
          "prompt": "The allowed length of the label"
        }]
      },{
        "name": "background_color",
        "value": null,
        "validations": [{
          "name": "inclusion",
          "value": ["red", "green", "blue"],
          "prompt": "The list of allowed background colors"
        }]
      },{
        "name": "email_address",
        "value": null,
        "validations": [{
          "name": "format",
          "value": "\\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,4}\\b",
          "prompt": "regex pattern for an email address"
        }]
      }]
    }
  }
}

When proposing on the google group, the suggestion was raised that we would need a common set of validators. I reviewed a few validation libraries and below seemed to be a fairly common set, though the naming will look familiar to many a ruby and rails developer.

• inclusion - validates value to ensure it is within an Array of allowed values.
  • name: inclusion
  • value: ARRAY
• exclusion - validates value to ensure it is not within an Array of allowed values.
  • name: exclusion
  • value: ARRAY
• format - validates String to ensure it matches regex
  • name: format
  • value: Regex as String
• length - validates a String against and Array containing an upper and lower bound length
  • name: length
  • value: ARRAY - [Lower bound Integer, Upper bound Integer]
• file_type - validates a File against an Array of allowed file types
  • name: file_type
  • value: ARRAY
• file_size - validates a File against an Array containing an upper and lower bound file size
  • name: length
  • value: ARRAY - [Lower bound Integer, Upper bound Integer]
• presence - validates a value to ensure that it present (not null and not empty)
  • name: presence
  • value: null

If there are validators that are missing or the implementation is lacking for some specific needs please let me know. I will be working on a PR to link to this so we can have more of a work in progress.

[glanotte]

In speaking with some coworkers, they feel there might not be a need for file_type and inclusion but instead the inclusion validator would behave one way for a file and another way for a list of arrays.

Similarly, he suggested using size instead of length and the validator working for Strings as described above, for a file it would validate the size of the file (as opposed to the file_size validator) and for integers it would validate the number is in the specified range.

I would prefer that a validator be tied to a specific type, but I thought I would mention the other side here.

[carlesjove]

I see a problem with it, but it'd be @mamund 's decision to accept it or not. In CJ values are supposed to be strings, only. So this wouldn't be spec compliant:

"value": ["red", "green", "blue"]

However, it's somehow also a problem to write it as a string, because it could lead to some weird scenarios where comma separated values are not really to be treated as arrays.

Maybe a values property could be introduced? Just thinking loud.

"values": ["red", "green", "blue"]

[mamund]

yep -- one of the challenges for this design will be dealing with the
varying types of "value" (scalar, array, object) needed for each validator.

as Carles points out, the "value" keyword is already defined as a string
and i'd prefer to not overload that for the validator extension.

mamund
+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

On Thu, Feb 19, 2015 at 2:16 AM, Carles Jove i Buxeda <
notifications@github.com> wrote:

I see a problem with it, but it'd be @mamund https://github.com/mamund
's decision to accept it or not. In CJ values are supposed to be strings
https://github.com/collection-json/spec#66-value, only. So this
wouldn't be spec compliant:

"value": ["red", "green", "blue"]

However, it's somehow also a problem to write it as a string, because it
could lead to some weird scenarios where comma separated values are not
really to be treated as arrays.

Maybe a values property could be introduced? Just thinking loud.

"values": ["red", "green", "blue"]

—
Reply to this email directly or view it on GitHub
#12 (comment)
.

[glanotte]

That makes sense, thanks for bringing that up. (also thinking out loud) I think that arguments might be a more accurate name? And this might be carrying things a bit too far, but we could do something like this instead of having arguments be any of a number of data types:

{
  "collection": {
    "version": "1.0",
    "href": "http://www.example.com/file_upload",
    "template":{
      "data": [{
        "name": "file",
        "value": null,
        "validations": [{
          "name": "file_size",
          "prompt": "The maximum size for a file",
          "arguments": [{
            "name": "lower_bound",
            "value": "0"
          },{
            "name": "upper_bound",
            "value": "2097152"
          }]
        }, {
          "name": "file_type",
          "prompt": "allowed file types",
          "arguments": [{
            "name": "option",
            "value": "png"
          },{
            "name": "option",
            "value": "bmp"
          },{
            "name": "option",
            "value": "jpg"
          },{
            "name": "option",
            "value": "gif"
          }]
        }]
      },{
        "name": "label",
        "value": null,
        "validations": [{
          "name": "length",
          "prompt": "The allowed length of the label",
          "arguments": [{
            "name": "lower_bound",
            "value": "0"
          },{
            "name": "upper_bound",
            "value": "50"
          }]
        }]
      },{
        "name": "background_color",
        "value": null,
        "validations": [{
          "name": "inclusion",
          "prompt": "The list of allowed background colors",
          "arguments": [{
            "name": "option",
            "value": "red"
          },{
            "name": "option",
            "value": "green"
          },{
            "name": "option",
            "value": "blue"
          }]
        }]
      },{
        "name": "email_address",
        "value": null,
        "validations": [{
          "name": "format",
          "prompt": "regex pattern for an email address",
          "arguments": [{
            "name": "regex",
            "value": "\\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,4}\\b"
          }]
        }]
      }]
    }
  }
}

[carlesjove]

Following on this (the problem with value being an array), I just checked current extensions and we have this:

• Array Values: introduces an array object
• URI Templates: seems to accept value as an array… This is strange.
• Errors: introduces an array object. See the password example. This would be a +1 to @glanotte proposal of an arguments object.