Form Template Element - Multi Select¶

Functional Behavior¶

A List of items, where multiple values can be selected.

Each entry in the list is a singleSelect type Form element. However, the contents are not entered free-form, they are chosen from the provided options.

Visual Representation¶

A List of items to be selected. The selector is not valid if less than minItems are selected. And no more than maxItems can be selected.

The value encoded in the document is the text value for each item selected, in the order presented.

The Items should appear and be parameterizable in the same way the base singleSelect type Form element can be.

It should appear similar to singleSelect except that multiple items can be selected, instead of just one.

Parent Elements¶

The Multi Select form element, can appear as a child of:

Section

Definition¶

Definition: Multi Select

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "multiSelect": {
      "items": {
        "$ref": "#/$defs/singleSelect"
      },
      "type": "array",
      "uniqueItems": true
    },
    "singleSelect": {
      "contentMediaType": "text/plain",
      "pattern": "^[^\\n]*$",
      "type": "string"
    }
  }
}

Parameters¶

The Multi Select form element takes the following parameters:

`default` Default selections can be supplied.
Multi Select
Parameters
Required	optional
Type	`string`
Example	`default: ["option1", "option3"]`
`description` The description of the field presented to the user during data entry.
Required	optional
Type	`string`
Content Media Type	text/markdown; template=handlebars
Example	`description: "Select a few items you prefer."`
`maxItems` The maximum number of items that may be selected. Default to the size of the selectable items if not specified. If it is less than `minItems` it is taken to == `minItems`.
Required	yes
Type	`integer`
Example	`maxItems: 2`
`minItems` The minimum number of items that may be selected. Default to 0 if not specified.
Required	optional
Type	`integer`
Example	`minItems: 2`
`title` The label attached to the field.
Required	yes
Type	`string`
Content Media Type	text/plain
Example	`title: "Select Items"`
`x-guidance` Long form Markdown formatted description to give guidance about how the field is to be completed.
Required	optional
Type	`string`
Content Media Type	text/markdown; template=handlebars
Example	`x-guidance: "Select two items only, no more, no less."`
`x-icon` The name of the Icon to display with the field.
Required	optional
Type	`string`
Choices	Icons
Example	`x-icon: "cursor-click"`

Example Usage¶

This is an Example Form Template showing just the Multi Select form element, and its parents.

Example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "multiSelect Example",
  "description": "An example of the multiSelect Element, and it's parents.",
  "$defs": {
    "multiSelect": {
      "items": {
        "$ref": "#/$defs/singleSelect"
      },
      "type": "array",
      "uniqueItems": true
    },
    "section": {
      "additionalProperties": false,
      "type": "object"
    },
    "sectionOptional": {
      "additionalProperties": false,
      "type": [
        "object",
        "null"
      ]
    },
    "singleSelect": {
      "contentMediaType": "text/plain",
      "pattern": "^[^\\n]*$",
      "type": "string"
    }
  },
  "type": "object",
  "properties": {
    "exampleSection": {
      "$ref": "#/$defs/section",
      "properties": {
        "exampleMultiSelect": {
          "$ref": "#/$defs/multiSelect",
          "default": [
            "option1",
            "option3"
          ],
          "description": "Select a few items you prefer.",
          "items": {
            "default": "option 1",
            "description": "Single Selector.\nChoose a value from the options presented.",
            "enum": [
              "option 1",
              "option 2",
              "option 3"
            ],
            "title": "Single Selector",
            "x-guidance": "It is recommended that a good choice be made.\nA bad choice could effect prospects of success.\nA good choice could improve them.\nSo make a good choice.",
            "x-icon": "emoji-happy"
          },
          "maxItems": 2,
          "minItems": 2,
          "title": "Select Items",
          "x-guidance": "Select two items only, no more, no less.",
          "x-icon": "cursor-click"
        },
        "exampleSection": {
          "$ref": "#/$defs/section",
          "properties": {
            "exampleMultiSelect": {
              "$ref": "#/$defs/multiSelect",
              "default": [
                "option1",
                "option3"
              ],
              "description": "Select a few items you prefer.",
              "items": {
                "default": "option 1",
                "description": "Single Selector.\nChoose a value from the options presented.",
                "enum": [
                  "option 1",
                  "option 2",
                  "option 3"
                ],
                "title": "Single Selector",
                "x-guidance": "It is recommended that a good choice be made.\nA bad choice could effect prospects of success.\nA good choice could improve them.\nSo make a good choice.",
                "x-icon": "emoji-happy"
              },
              "maxItems": 2,
              "minItems": 2,
              "title": "Select Items",
              "x-guidance": "Select two items only, no more, no less.",
              "x-icon": "cursor-click"
            },
            "exampleSectionOptional": {
              "$ref": "#/$defs/sectionOptional",
              "x-final-optional": true,
              "x-flatten": false,
              "x-icon": "bookmark"
            }
          },
          "x-flatten": false,
          "x-icon": "bookmark"
        },
        "exampleSectionOptional": {
          "$ref": "#/$defs/sectionOptional",
          "x-final-optional": true,
          "x-flatten": false,
          "x-icon": "bookmark"
        }
      },
      "x-flatten": false,
      "x-icon": "bookmark"
    },
    "exampleSectionOptional": {
      "$ref": "#/$defs/sectionOptional",
      "x-final-optional": true,
      "x-flatten": false,
      "x-icon": "bookmark"
    }
  },
  "additionalProperties": false
}