Allow port types to be specified using json-schema

[chadrik]

As a user of a UI that is compatible with fbp-protocol such as noflo-ui, I want UI widgets with finer grained controls to make my life easier.

I propose that we expand the definition of our port types to allow json schema documents so that developers can use this to provide a better UX for users.

We currently support enums and defaults.

For starters, I would like to add things like:

• minimum / maximum values for numeric types
• prefix and/or suffix around an input widget (e.g.: data size: [<input>] MB)
• display precision for float types
• "soft" max and min values for numerics, for setting initial slider bounds which can be expanded up to the "hard" min/max

As well as the ability to reinterpret a base datatype with a more specific widget. For example:

• file / folder browser for strings
• date picker for strings

Here is an example sub-document for an integer port:

{
  "id": "input_size",
  "required": true,
  "addressable": true,
  "type": 
  {
    "$schema": "http://json-schema.org/schema#",
    "title": "input size",
    "description": "input size in megabytes",
    "type": "integer",
    "default": 10,
    "minimum": 0,
    "maximum": 100000,
    "softMaximum": 1000,
    "labelSuffix": "MB"
  }
}

Notes:

• "title" is the display label. can be different from the "id"
• in the case that "type" is a json-schema doc, some keys that would normally be siblings of "type" will be contained within it: "values", "description", and "default"

Other advantages:

• gives us the ability to describe compound types. For example, it's very common to use object type, but unfortunately, since the UI knows nothing of an object's schema, it can't provide a proper UI or validation. With json-schema, runtimes can provide more information for these compound types and noflo-ui can build appropriate UIs.
• could also be used to validate IIPs on the UI side

Related issues:

• Nicer UI for port value input noflo/noflo-ui#309
• Ability to edit node metadata noflo/noflo-ui#482
• Allow to specify edge metadata noflo/noflo-ui#371

[jonnor]

Yes, we need richer type information and JSON schema seems a nice fit.

I think that we should split the schema definition and usage of the schema however. So instead of type having the (whole) schema inline, it would be a reference. Preferably an URL which is the canonical definition, like http://flowbased.org/schemas/bartype or http://myservice/API/schema/FooResource.json
This hopefully encourages usage of compatible definitions where possible, as well as making it possible to easily detect (simple cases) of compatible definitions.

Optionally one could allow adding to the schema like max/min constraints.

There is the $ref mechanism in JSON schema. Maybe that would be enough?

[jonnor]

For the suffix, isn't it better to be able to specify a 'unit' ?

[bergie]

I think better to provide the schema as a URL, like we did in noflo/noflo#551

The consumer can then fetch the schema as needed. This way there is no need to duplicate (potentially) large data structures across multiple components sharing the schema, and schema can also be carried as a metadata on packets/IIPs so it can be used not only for generating input widgets, but also for richer visualization