Skip to content

UI Schema Hints

UI Schema Hints are metadata extensions to JSON Schema that modify how a field is rendered and behaves in the UI. These hints are consumed by the ui-components library and are designed to help developers declaratively control layout, visibility, grouping, and form interactions.

They are prefixed with underscores (e.g. _ui_group) to distinguish them from standard JSON Schema keywords.

📘 Reference: The logic that consumes and applies these hints is implemented in the SfoFormHelperService. You can review this service to understand how hints like _nullable and _multiple are handled during form cleanup, default value stripping, and validation.

Supported UI Hints

Hint Description
_ui_group Groups fields under a shared heading, section, or tab.
_ui_hide Prevents a field from being rendered in the UI (but not removed from the data model).
_ui_class Applies layout utility classes to the form field container (e.g. for grid or spacing).
_ui_icon Adds an icon to be displayed alongside the label (if supported by the layout engine).
_ui_table_width Sets column width for tabular data layouts using Basscss class conventions.
_ui_tag Used to tag or categorize a field, useful for filtering or conditional rendering.
_readme Injects markdown-formatted documentation blocks into the form UI.
_nullable Allows null as a valid value for the field. Preserves nulls during form processing and affects validation.
_multiple Enables multi-select behavior for supported widgets and enum arrays. Affects validation as well as UI behavior.

Hint Usage Summary

Below are concrete examples for key UI hints, demonstrating how schema inputs affect rendering and model outputs.

_nullable

Allows a field to explicitly accept null as a value.

Schema

{
  "type": "string",
  "_nullable": true
}

Possible Output Values

"Hello"
null

_multiple

Indicates that a field should be rendered as a multi-select UI, and expects array output. This is a UI hint; validation still depends on type: "array" and items.

Schema

{
  "type": "array",
  "_multiple": true,
  "items": {
    "type": "string",
    "enum": ["a", "b", "c"]
  }
}

Possible Output Values

["a"]
["a", "b"]
[]

Combined Example: _nullable + _multiple

This enables inputs like null, [], and [null] to be valid outputs.

Schema

{
  "type": "array",
  "_nullable": true,
  "_multiple": true,
  "items": {
    "anyOf": [{ "type": "string", "enum": ["before", "after"] }, { "type": "null" }]
  }
}

Possible Output Values

null
[]
["before"]
[null]
["before", null]

Implementation Notes

These UI hints are parsed and applied within the SfoFormHelperService, particularly in the following methods:

  • removeNullValues – ensures _nullable, minLength, and structural cleanup rules are respected.
  • removeDefaults – removes keys from objects when their values match schema defaults.
  • isPatchValid – validates form patches against the schema, supporting Ajv extensions via SchemaKeywords.

To extend UI behavior, add your own keywords to the SchemaKeywords enum and define their usage in your form renderer or helper service.

Best Practices

  • Use UI hints only to modify presentation and schema behavior that affects user interaction—not core validation logic unless explicitly intended.
  • Group related fields using _ui_group to improve form UX.
  • Document complex forms inline using _readme with Markdown content.
  • Use _ui_hide to exclude advanced or internal fields from the editor UI while keeping them part of the schema payload.