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
version	string	No	The form version
description	string	No	The form’s description
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

Formats

A JSON example of this model.

{
  "id": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "name": "Sample string value",
  "createdAt": "2025-10-09T23:16:01.212Z",
  "lastModifiedAt": "2025-10-09T23:16:01.212Z",
  "description": "Sample string value",
  "version": "Sample string value",
  "instructions": "Sample string value",
  "jsonSchema": {},
  "uiSchema": {},
  "mappingToCommonGrants": {},
  "mappingFromCommonGrants": {},
  "customFields": {
    "property": {
      "name": "Sample string value",
      "fieldType": "string",
      "value": "Sample value",
      "schema": "https://example.com",
      "description": "Sample string value"
    }
  }
}

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: {}
        lastName: {}
      emails:
        primary: {}
      phones:
        primary: {}
    mappingFromCommonGrants:
      name:
        first: {}
        last: {}
      email: {}
      phone: {}
    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;

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.

  ...Fields.SystemMetadata;
}

// #########################################################
// FormJsonSchema
// #########################################################

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.

  ...Record<unknown>;
}

// #########################################################
// FormUISchema
// #########################################################