Prologue

JSON Schema is a specification to define JSON data structure, it doesn't include detailed explanation about how to convert the specification to specific forms, @delon/form is a dynamic form library developed based on our own understanding of JSON Schema and current data input components of ng-zorro-antd.

JSON Schema must always have a type type="object" as root node，therefore a simplest Schema structure at least is:

schema = {
  type: 'object', // optional, set to `object` by default
  properties: {}
}

Ahead of dscribing Schema, it is necessary to make a systematic description about the relationship between form elements and Schema.

As we know, form is a set of HTML elements, every element maps to one Schema property, a property has it's own data type, format, visual information, etc., but this is not enough to describe the rich APIs provided by ng-zorro-antd. In order to better use these APIs, @delon/form not only implemented most standard JSON Schema, but also added an additional property ui, which is used to describe how to render the property.

Non Pollution

Of course, you can set <sf [ui]="ui"> to add additional UI rendering if you have strict requirement about standard, or JSON Schema data is generated from backend. For example:

schema = {
  properties: {
    url: {
      type: 'string',
      title: 'Web Site'
    }
  }
}

A URL property, the pure JSON Schema structure cann't describe about adding prefix https://, but nz-input supports very rich prefix and postfix texts, so we can customize it in ui to add prefix https://:

ui = {
  $url: {
    addOnBefore: 'https://'
  }
}

ui itself is a JSON structure, in order to distinguish with relationship of JSON Schema property, must add prefix $ to all properties; must replace array elements with $items. When KEY is *, it is valid for all properties.

Relationship between Form and Data Structure

We think a complete form should include some of following elements:

Description from left to right:

Some Specifications

• Following camelCase to name key

• You can ignore description marked as Not recommended if you are very familiar with JSON Schema.

JSON Schema（SFSchema）

JSON Schema has complete specification descrbes for each property, @delon/form is currently based on specification draft-07, following is the detailed explanation of specification:

Common Type

Value Type

About exclusiveMinimum and exclusiveMaximum

The implementation mechanism of sf causes that it couldn't handle error capturing for type perpectly, therefore sf ignores all type (see config.ts) errors by default, these two kinds of errors are considered as type error, which will trigger invalid check. (find more details from #676）

String Type

Array Type

Object Type

Condition Type

Validation of condition check is very strong and rich, but considering it breaks UI and adds complexity to component build, @delon/form only implements required, and uses it to determine if need validation, for example, a login page, it can show different login mode based on different login methods:

schema: SFSchema = {
  properties: {
    type: { type: 'string', enum: [ 'mobile', 'name' ], default: 'mobile' },
    name: { type: 'string' },
    pwd: { type: 'string' },
    mobile: { type: 'string' },
    code: { type: 'string' }
  },
  required: [ 'type' ],
  if: {
    properties: { type: { enum: [ 'mobile' ] } }
  },
  then: {
    required: [ 'mobile', 'code' ]
  },
  else: {
    required: [ 'name', 'pwd' ]
  }
};

For above configuraion, eventual behavior is showing mobile and code in UI when login method is mobile, otherwise, showing name and pwd.

Actually, condition type is eventually parsed to ui.visibleIf, Convert it to the following:

{
  properties: {
    login_type: {
      type: "string",
      title: "登录方式",
      enum: [
        { label: "手机", value: "mobile" },
        { label: "账密", value: "account" }
      ],
      default: "mobile",
      ui: {
        widget: "radio",
        styleType: "button"
      }
    },
    mobile: {
      type: "string",
      ui: {
        visibleIf: {
          login_type: val => val === "mobile"
        }
      }
    },
    code: {
      type: "number",
      ui: {
        visibleIf: {
          login_type: val => val === "mobile"
        }
      }
    },
    name: {
      type: "string",
      ui: {
        visibleIf: {
          login_type: val => val === "account"
        }
      }
    },
    pwd: {
      type: "string",
      ui: {
        type: "password",
        visibleIf: {
          login_type: val => val === "account"
        }
      }
    }
  },
  required: ["login_type"]
};

Logic Type

Not recommended, mainly because there is no UI handle for logic type, it's similar to condition type, will affect UI rendering.

Format and Visual Type

Other

Non Standard

UI（SFUISchemaItem）

UI Schema structure is composed by commonality and widgets, following is descriptioin of commonality part, please refer to widget API for widget part.

In order to keep integrity of API, Schema of widget may includes commonality information.

SFUISchema

Equals to <sf [ui]="ui">, a group of UI structure corresponds to JSON Schema structure, type is: [ key: string ]: SFUISchemaItem。

Basic Type

visibleIf

Is visible with conditions, for example:

• visibleIf: { shown: [ true ] }: show current property when shown: true

• visibleIf: { shown: [ '$ANY$' ] }: show current property when shown is any value

• visibleIf: { shown: (value: any, property: FormProperty) => value > 0 }: complex expression

Validation Type

Array Type

Form Element Type

Render Type

Responsive Property SFGridSchema

grid equals to complete Grid, can determine how to render the form by grid

Horizontal Layout Type

The sum of label and control must be 24