Form

Form

A form for collecting data from a user.

Table

Property	Type	Required	Description
id	uuid	Yes	The form’s unique identifier
name	string	Yes	The form’s name
description	string	No	The form’s description
instructions	string | File	No	The form’s instructions
jsonSchema	FormJsonSchema	No	The form’s JSON schema used to render the form and validate responses
uiSchema	FormUISchema	No	The form’s UI schema used to render the form in the browser
mappingToCommonGrants	MappingSchema	No	A mapping from form schema to CommonGrants schema
mappingFromCommonGrants	MappingSchema	No	A mapping from CommonGrants schema to form schema
customFields	Record<CustomField>	No	Custom attributes about the form itself, not custom fields within the form

Formats

Example

A JSON example of this model.

{
  "id": "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a",
  "name": "Form A",
  "description": "Form A description",
  "instructions": "Form A instructions",
  "jsonSchema": {
    "$id": "formA.json",
    "type": "object",
    "properties": {
      "name": {
        "first": { "type": "string" },
        "last": { "type": "string" }
      },
      "email": { "type": "string" },
      "phone": { "type": "string" }
    }
  },
  "uiSchema": {
    "type": "VerticalLayout",
    "elements": [
      {
        "type": "Group",
        "label": "Name",
        "elements": [
          { "type": "Control", "scope": "#/properties/name/first" },
          { "type": "Control", "scope": "#/properties/name/last" }
        ]
      },
      { "type": "Control", "scope": "#/properties/email" },
      { "type": "Control", "scope": "#/properties/phone" }
    ]
  },
  "mappingToCommonGrants": {
    "name": {
      "firstName": { "field": "name.first" },
      "lastName": { "field": "name.last" }
    },
    "emails": { "primary": { "field": "email" } },
    "phones": { "primary": { "field": "phone" } }
  },
  "mappingFromCommonGrants": {
    "name": {
      "first": { "field": "name.firstName" },
      "last": { "field": "name.lastName" }
    },
    "email": { "field": "emails.primary" },
    "phone": { "field": "phones.primary" }
  },
  "customFields": {
    "formType": {
      "name": "Form Type",
      "fieldType": "string",
      "value": "application",
      "description": "The type of form"
    }
  }
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: Form.yaml
type: object
properties:
  id:
    $ref: uuid.yaml
    description: The form's unique identifier.
  name:
    type: string
    description: The form's name.
  description:
    type: string
    description: The form's description.
  instructions:
    anyOf:
      - type: string
      - $ref: File.yaml
    description: The form's instructions.
  jsonSchema:
    $ref: FormJsonSchema.yaml
    description: The form's JSON schema used to render the form and validate responses.
  uiSchema:
    $ref: FormUISchema.yaml
    description: The form's UI schema used to render the form in the browser.
  mappingToCommonGrants:
    $ref: MappingSchema.yaml
    description: A mapping from form schema to CommonGrants schema.
  mappingFromCommonGrants:
    $ref: MappingSchema.yaml
    description: A mapping from CommonGrants schema to form schema.
  customFields:
    $ref: "#/$defs/RecordCustomField"
    description: Custom attributes about the form itself, not custom fields within the form.
required:
  - id
  - name
examples:
  - id: b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a
    name: Form A
    description: Form A description
    instructions: Form A instructions
    jsonSchema:
      $id: formA.json
      type: object
      properties:
        name:
          first:
            type: string
          last:
            type: string
        email:
          type: string
        phone:
          type: string
    uiSchema:
      type: VerticalLayout
      elements:
        - type: Group
          label: Name
          elements:
            - type: Control
              scope: "#/properties/name/first"
            - type: Control
              scope: "#/properties/name/last"
        - type: Control
          scope: "#/properties/email"
        - type: Control
          scope: "#/properties/phone"
    mappingToCommonGrants:
      name:
        firstName:
          field: name.first
        lastName:
          field: name.last
      emails:
        primary:
          field: email
      phones:
        primary:
          field: phone
    mappingFromCommonGrants:
      name:
        first:
          field: name.firstName
        last:
          field: name.lastName
      email: {}
      phone: {}
description: A form for collecting data from a user.
$defs:
  RecordCustomField:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: CustomField.yaml

TypeSpec

The TypeSpec code for this model.

/** A form for collecting data from a user. */
@example(Examples.Form.form)
model Form {
  /** The form's unique identifier. */
  id: Types.uuid;

  /** The form's name. */
  name: string;

  /** The form's description. */
  description?: string;

  /** The form's instructions. */
  instructions?: string | Fields.File;

  /** The form's JSON schema used to render the form and validate responses. */
  jsonSchema?: FormJsonSchema;

  /** The form's UI schema used to render the form in the browser. */
  uiSchema?: FormUISchema;

  /** A mapping from form schema to CommonGrants schema. */
  mappingToCommonGrants?: Models.MappingSchema;

  /** A mapping from CommonGrants schema to form schema. */
  mappingFromCommonGrants?: Models.MappingSchema;

  /** Custom attributes about the form itself, not custom fields within the form. */
  customFields?: Record<Fields.CustomField>;
}

FormJsonSchema

A JSON schema used to validate form responses.

Example

A JSON example of this model.

{
  "$id": "formA.json",
  "type": "object",
  "properties": {
    "name": {
      "first": { "type": "string" },
      "last": { "type": "string" }
    },
    "email": { "type": "string" },
    "phone": { "type": "string" }
  }
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: FormJsonSchema.yaml
type: object
properties: {}
unevaluatedProperties: {}
examples:
  - $id: formA.json
    type: object
    properties:
      name:
        first:
          type: string
        last:
          type: string
      email:
        type: string
      phone:
        type: string
description: A JSON schema used to validate form responses.

TypeSpec

The TypeSpec code for this model.

/** A JSON schema used to validate form responses. */
@example(Examples.Form.formSchema)
model FormJsonSchema {
  ...Record<unknown>;
}

FormUISchema

A UI schema used to render the form in the browser.

Example

A JSON example of this model.

{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "Group",
      "label": "Name",
      "elements": [
        { "type": "Control", "scope": "#/properties/name/first" },
        { "type": "Control", "scope": "#/properties/name/last" }
      ]
    },
    { "type": "Control", "scope": "#/properties/email" },
    { "type": "Control", "scope": "#/properties/phone" }
  ]
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: FormUISchema.yaml
type: object
properties: {}
unevaluatedProperties: {}
examples:
  - type: VerticalLayout
    elements:
      - type: Group
        label: Name
        elements:
          - type: Control
            scope: "#/properties/name/first"
          - type: Control
            scope: "#/properties/name/last"
      - type: Control
        scope: "#/properties/email"
      - type: Control
        scope: "#/properties/phone"
description: A UI schema used to render the form in the browser.

TypeSpec

The TypeSpec code for this model.

/** A UI schema used to render the form in the browser. */
@example(Examples.Form.uiSchema)
model FormUISchema {
  ...Record<unknown>;
}