Form Template Element - Section Optional¶

Functional Behavior¶

Sections have no functional behavior beyond providing structure to the underlying data collected by the form.

The ONLY Element that can appear in the root of a Form is a section or optionalSection.

An optionalSection may be set to null which means everything contained by the section is not set. This has two primary use cases:

Completely optional sections the user may or may not choose to complete.
Sections which may not be present in a draft of a document, but must be present in a final form of the document.

As JsonSchema allows null or object to be valid for optionalSchema, checking if its valid to be null in a finalized document must be done as an extra step, after json schema validation.

Visual Representation¶

Sections represent logical breaks in the form structure. Optional Sections allow for the entire section to be toggled off (incomplete).

A Optional Section may have whatever visual representation that is required. Nominally however, a Optional Section that is in the root of the document is known as a ***Optional Document Segment**. Whereas a section that is embedded within another section is a Optional Document Section or Optional Sub-Section.

There is no limit to how many levels sub-sections are nested, however the application is not required to show them any differently from one another.

The visual display of sections has no impact on how it is represented in the data captured.

For Optional Sections, the UI should allow the partial capture and local storage of data within the section, but NOT submit it if it would be invalid according to the document template schema. The UI may also employ a specific toggle which determines if an Optional Section is included or not.

Before submitting any document as Final, that contains Optional Sections, the UI must validate that those sections have been properly completed if they are not allowed to be null in a finalized document.

Parent Elements¶

The Section Optional form element, can appear as a child of:

The Root Object of the JSON Schema
Section
Section Optional

Definition¶

Definition: Section Optional

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "sectionOptional": {
      "additionalProperties": false,
      "type": [
        "object",
        "null"
      ]
    }
  }
}

Parameters¶

The Section Optional form element takes the following parameters:

`description` The displayable description attached to the section. Markdown formatted contents.
Section Optional
Parameters
Required	optional
Type	`string`
Content Media Type	text/markdown; template=handlebars
`properties` The sub fields of the section when it is not `null`.
Required	yes
Type	`string`
`required` Which fields MUST appear in the segment.
Required	optional
Type	`string`
`title` The title of the section.
Required	yes
Type	`string`
Content Media Type	text/plain
`x-final-optional` If present, and true, then this section may be `null` in a Finalized Form. The default behavior is that Optional Sections MUST NOT be `null` in Finalized Forms. This parameter allows that to be over-ridden, on a section by section basis. This parameter is only present in Optional Sections. This parameter informs post json schema validation to allow `null` sections based on the status of the Form, whereas typically they are always rejected.
Required	optional
Type	`boolean`
Example	`x-final-optional: true`
`x-flatten` If present, and true, then form element is to be flattened into its parent. Typically this parameter is only present in sections. The UI is free to decide how it presents flattened sections.
Required	optional
Type	`boolean`
Example	`x-flatten: false`
`x-icon` The name of the Icon to display with the field.
Required	optional
Type	`string`
Choices	Icons
Example	`x-icon: "bookmark"`
`x-order` The ordering of the properties to be enforced when displayed. Any field not listed here will get displayed in an alphabetical order following the listed fields.
Required	yes
Type	`string`

Example Usage¶

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

Example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "sectionOptional Example",
  "description": "An example of the sectionOptional Element, and it's parents.",
  "$defs": {
    "section": {
      "additionalProperties": false,
      "type": "object"
    },
    "sectionOptional": {
      "additionalProperties": false,
      "type": [
        "object",
        "null"
      ]
    }
  },
  "type": "object",
  "properties": {
    "exampleSection": {
      "$ref": "#/$defs/section",
      "properties": {
        "exampleSection": {
          "$ref": "#/$defs/section",
          "properties": {
            "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
}