Skip to content

Walls Dynamic Forms

Jump to bottom
Antero Duarte edited this page Oct 23, 2020 · 13 revisions

Specification

Field Types

Through a study of the existing field types in both of these use cases, the following list of field types was created:

Field Type Type ID Allowed Values Example
Text String string Unspecified length simple string type { single: "a string", multiple: ["one string", "two strings"] }
Number number Positive or negative integer or floating point number { single: 1, multiple: [1,2,3] }
Boolean boolean Boolean value: true or false { single: true, multiple: [true, false, false] }
SPARQL Query sparql-query Field containing a SPARQL Query { single: "CONSTRUCT {?s ?p ?o}WHERE{?s ?p ?o}", multiple: ["CONSTRUCT {?s ?p ?o}WHERE{?s ?p ?o}", "CONSTRUCT {?s ?p ?o}WHERE{?s ?p ?o}"] }
RDF Triple Pattern triple-pattern Represents a triple's constituents (s,p,o). Because of the ambiguity of the Object part in triples, Object Resources must be wrapped in angled brackets (<>), otherwise they are assumed to be literals. The parts of the triple can be omitted when they are variables in the pattern { single: {s: "http://wallscope.co.uk/Murdoc", p: "http://wallscope.co.uk/name", o: "Murdoc Niccals" }, multiple: [{s: "http://wallscope.co.uk/Murdoc", p: "http://wallscope.co.uk/name", o: "Murdoc Niccals" }, {p: "http://wallscope.co.uk/isPartOf", o: "<http://wallscope.co.uk/Gorillaz>" }] }
URI/URL Field uri Special string field that represents a URI/URL format. Does not have to be dereferenceable, but has to follow URI format { single: "http://wallscope.co.uk/", multiple: ["http://wallscope.co.uk/about", "http://dev.verinote.net:5080/"] }
Password Field password Special string field that displays a password input that can be shown/hidden { single: "pa$$w0rd!", multiple: ["12345678", "correcthorsebatterystaple"] }
String : String Mapping mapping Mapping of string to string, represented as a JSON object where both keys and values are strings. { single: {"key":"value"}, multiple: { "key1":"value1", "key2":"value2" }
File path filepath Filesystem filepath represented in Unix format (/ as separator). Format accommodates absolute and relative paths and allows for dot ('.', '..') modifiers { single: "/home/a/folder", multiple: ["/folder/one", "/folder/two"] }
Nested Form form A collection of fields to be nested in the current level form. The result will be a nested object with the name of the field as a key and the resulting form object as a value {single: {nested: {field1: "some string", field2: 42}}}

This is not a definitive list and should be added on to as required (for example if we notice that we are having to handle types that are not listed on a regular basis)

Field metadata:

The field descriptions should be served as a JSON Array of objects with the following fields:

  • Type
    • One of types above
  • Name
    • Field identifier
    • Also the key to use in the result object, see result section
  • Required
    • Indicates if a field is required
    • The server should error if a field is marked as required and not present in the result object
  • Description
    • Text description of the field. Should help an end user understand how to fill it.
  • Default value
    • Useful when using with required fields. It is not mandatory that a field metadata includes this but it is recommended that it includes a sane default
    • For simplicity's sake, the default field should not be in the same format as the field value, but rather a string representation that can easily be parsed into the actual value by a JSON parser
    • Ex: "this is a normal string", "{this_is:"a stringified object"}", "12345"
  • Size
    • Size should identify how many values the backend expects for this field.
    • This field should not be used to express the optionality of a value, therefore "required" takes precedence
    • It follows the format: {Number}[Optional sign indicating minimum or maximum]
    • Ex: "1" - exactly 1 value, should be represented in the result object as a plain literal ({field:"value"})
    • Ex: "1+" - one value or more, should be represented in the result object as an array of values ({field: ["value","other value"]})
    • Ex: "3-" - at most 3 values, should be represented in the result object as an array of values ({field: ["value","other value"]})
    • Special cases:
      • "" - if left empty, or omitted, 1 is assumed
      • "1-" - As expressed before, this field is not meant to express optionality of a field, therefore the sign is dropped and "1-" == "1"
      • "0", "0+", "0-" - As expressed before, this field is not meant to express optionality of a field, therefore the 0 is turned into 1 in the backend when validating, meaning "0" == "1", "0+" == "1+", "0-" == "1-" == "1"

Nested form metadata

As a design choice, for nested forms most of the fields existent on regular fields are ignored as they would increase complexity. If use cases arise that need that complexity, a change will be considered. Therefore when type === 'form' in a field metadata object, the only required fields are:

  • Name
  • Description
  • Default value
    • This is provided as it may be useful to prefill a nested form, but it will be overridden by individual default values in the nested fields as those take precedence
  • Fields
    • This field should be the array of field metadata objects to render as a nested form. They follow the same structure as normal field metadata

As a final note, the nesting uses recursive components to render the nesting. Through this the number of levels of nesting allowed is infinite.

Field metadata example

[
  {
    "name": "trips",
    "type": "triple-pattern",
    "required": false,
    "size": "1+",
    "description": "Object that represents a mapping of string to string",
    "default": "{\"p\":\"http://www.w3.org/2000/01/rdf-schema#label\"}",
  },
  {
    "name": "mapping",
    "type": "mapping",
    "required": true,
    "size": "2-",
    "description": "Object that represents a mapping of string to string",
    "default": "{\"label\":\"http://www.w3.org/2000/01/rdf-schema#label\"}",
  },
  {
    "name": "string field",
    "type": "string",
    "required": true,
    "size": "2+",
    "description": "A plain text string field",
    "default": "",
  },
  {
    "name": "number field",
    "type": "number",
    "required": true,
    "size": "2+",
    "description": "A number field",
    "default": "2",
  },
  {
    "name": "boolean field",
    "type": "boolean",
    "required": true,
    "size": "2+",
    "description": "A number field",
    "default": "true",
  },
  {
    "name": "password field",
    "type": "password",
    "required": true,
    "size": "2+",
    "description": "A password field",
  },
  {
    "name": "SPARQL query field",
    "type": "sparql-query",
    "required": true,
    "size": "1+",
    "description": "A sparql query field",
    "default": "CONSTRUCT {?S ?P ?O}WHERE{?S ?P ?O}",
  },
  {
    "name": "Nested Form",
    "type": "form",
    "description": "A nested form",
    "fields": [
      {
        "name": "Nested SPARQL query field",
        "type": "sparql-query",
        "required": true,
        "size": "1",
        "description": "A nested sparql query field",
        "default": "CONSTRUCT {?nest ?P ?O}WHERE{?nest ?P ?O}",
      },
    ],
  },
]

To which a valid response object would be:

{
 "mapping": {
  "label": "http://www.w3.org/2000/01/rdf-schema#label"
 },
 "string field": [
  "",
  ""
 ],
 "number field": [
  2,
  2
 ],
 "boolean field": [
  "true",
  "true"
 ],
 "password field": [
  "",
  ""
 ],
 "SPARQL query field": [
  "CONSTRUCT {?S ?P ?O}WHERE{?S ?P ?O}"
 ],
 "trips": [
  {
   "s": "",
   "p": "http://www.w3.org/2000/01/rdf-schema#label",
   "o": ""
  },
  {
   "s": "",
   "p": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
   "o": "<http://xmlns.com/foaf/0.1/Person>"
  }
 ],
 "Nested Form": {
   "Nested SPARQL query field": "CONSTRUCT {?nest ?P ?O}WHERE{?nest ?P ?O}"
 }
}
Clone this wiki locally