Form

FormBase

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.
version	string	No
instructions	string or array<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.
createdAt	utcDateTime	Yes	The timestamp (in UTC) at which the record was created.
lastModifiedAt	utcDateTime	Yes	The timestamp (in UTC) at which the record was last modified.

Formats

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"
    }
  },
  "createdAt": "2025-01-01T17:01:01",
  "lastModifiedAt": "2025-01-02T17:30:00"
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: FormBase.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.
  version:
    type: string
  instructions:
    anyOf:
      - type: string
      - type: array
        items:
          $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.
  createdAt:
    type: string
    format: date-time
    description: The timestamp (in UTC) at which the record was created.
  lastModifiedAt:
    type: string
    format: date-time
    description: The timestamp (in UTC) at which the record was last modified.
required:
  - id
  - name
  - createdAt
  - lastModifiedAt
unevaluatedProperties:
  not: {}
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:
        field: emails.primary
      phone:
        field: phones.primary
    createdAt: 2025-01-01T17:01:01
    lastModifiedAt: 2025-01-02T17:30:00
description: A form for collecting data from a user.
$defs:
  RecordCustomField:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: CustomField.yaml

The TypeSpec code for this model.

/** A form for collecting data from a user. */
@example(Examples.Form.form)
@Versioning.added(CommonGrants.Versions.v0_2)
@Versioning.renamedFrom(CommonGrants.Versions.v0_3, "Form")
model FormBase {
  /** The form's unique identifier. */
  id: Types.uuid;

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

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

  @Versioning.added(CommonGrants.Versions.v0_3)
  version?: 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>;

  /** The system metadata for the form. */
  ...Fields.SystemMetadata;
}

Changelog

Version	Changes	Schema
0.3.0	Renamed model from `Form` to `FormBase` Added `version` field	FormBase.yaml
0.2.0	Added `Form` model	Form.yaml

FormJsonSchema

A JSON schema used to validate form responses.

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" }
  }
}

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.

The TypeSpec code for this model.

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

Changelog

Version	Changes	Schema
0.2.0	Added `FormJsonSchema` model	FormJsonSchema.yaml

FormUISchema

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

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" }
  ]
}

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.

The TypeSpec code for this model.

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

Changelog

Version	Changes	Schema
0.2.0	Added `FormUISchema` model	FormUISchema.yaml