Since JSON Schema is written in JSON itself and there are many loosely overlapping bits of terminology (objects, documents, data, values, schemas, definitions, specifications, fragments...), the following defines how and what terms are used relating to Form Builder.
JSON (JavaScript Object Notation) is a lightweight data interchange format.
JSON supports the following data types:
- string
- number
- boolean
- null
- object
- array
An occurrence of JSON data. It can be of any JSON data type.
A JSON document which is an object - ie. a collection of name/value pairs.
JSON Schema is a JSON-based declarative format for describing the structure of JSON data.
A schema is a JSON object that defines a JSON document conforming to the JSON Schema format.
eg. The Start page schema defines the data namespace of the service’s Start page instance
Schemas allow for the creation and validation of instances as well as for providing instructions for user interfaces with which to edit such instances and validating and transmission of data entered by the user.
Schemas can be thought of as the blueprints for the data that represent the service.
Other examples of Form Builder schemas
Schemas fall into 4 categories
- Block schemas define block instances used by the service.
- Behaviour schemas define configuration instances used by the service
- Configuration schemas define configuration instances used by the service
- Definition schemas provide the means to define other schemas.
An instance is a JSON document that has a structure defined by a particular schema.
eg. A Start page instance defines the block of the service’s Start page
All instances must have
_ida unique identifier for the instance_typethe name of the schema the instance is an instance of
A collection of instances make up the representation of a service.
Other examples of Form Builder instances
References to instances can be generic
Instances can be nested or discrete
-
Discrete instance
An instance that is stored as a separate individual file
All instances can be discrete.
-
Nested instance
An instance that exists as the value of a property of another instance
Only component instances can be nested.
A specification is a collection of files containing:
- a schema
- valid and invalid example instances for testing the schema
- any transformation rules
- documentation
A specification of a block also includes:
- a template
- template tests
Specifications are grouped together into a specifications module.
A block instance is any instance that defines the rendering of block
It covers the following types:
- Page
- Component
- Pattern
Block instances are any instances of these types.
Block schemas are any schemas of these types.
All block schemas must have a corresponding template.
The block definition schema is a definition schema used by all the block schemas.
A configuration instance is any instance that defines properties such as:
- the service name and phase
- service ownership and feedback details
- feature flags in use
- any additional specifications used
A definition schema is a base schema that is used to make other schemas.
Definitions are not used to create instances.
An environment is any computer system, physical or virtual, where a service can be run.
The service instance is a configuration instance that sets the basic details of the service.
- name
- phase
A page instance is the data representation of a document to be displayed to a user.
A component instance is the data representation of an item that can be added to a page
Components come in 3 forms:
- control
A control component blocks a form control for a user to enter information
- content
A content component blocks non-form content
- grouping
A grouping component blocks a group of components / blocks
A pattern is a best practice design solution for a specific user-focused task.
Patterns come in 2 forms: