Forms

Forms define the structure of edit and filter forms. When reading a Profile Schema, the forms field tells you how to build input forms for users to edit their profile data or filter profiles.

Understanding Forms Structure

The forms object contains two form schemas:

• edit (required): Defines the structure of the profile edit form
• filter (optional): Defines the structure of the profile filter form

Reading Form Schema Structure

A form schema can have either:

• groups (Group array, optional): Array of component groups for organized layout
• components (ComponentRef array, optional): Flat array of component references for simple layout

At least one of groups or components must be provided. Groups are used for better organization, while a flat component list is used for simpler layouts.

Reading Form Component References

A form component reference tells you how to display a component in a form:

Field	Type	Required	Description
id	ComponentId	Yes	Component identifier (must exist in components)
order	number	Yes	Display order
icon	string	No	Icon identifier to display with the component
label	LocalizedString	No	Component label to display
description	LocalizedString	No	Component description to display
placeholder	LocalizedString	No	Input placeholder text
metadata	object	No	Additional metadata

Note: Form component references include placeholder and description fields, which are not present in presentation component references. These provide additional guidance for users filling out forms.

Reading Edit Form

The edit form is used for creating and updating profile data. It includes all editable fields organized in a user-friendly layout.

Example:

{
  "forms": {
    "edit": {
      "groups": [
        {
          "title": { "en": "About" },
          "order": 1,
          "components": [
            {
              "id": "name",
              "order": 1,
              "label": { "en": "Username" },
              "placeholder": { "en": "Add your name" },
              "description": {
                "en": "This is how you'll appear to others. Pick a name that feels authentic and easy to recognize."
              }
            },
            {
              "id": "bio",
              "order": 2,
              "label": { "en": "Bio" },
              "placeholder": { "en": "Say something about yourself" },
              "description": {
                "en": "Say something about yourself. Keep it short, fun, or a little flirty, totally up to you."
              }
            },
            {
              "id": "gender",
              "order": 3,
              "label": { "en": "Gender" },
              "placeholder": { "en": "Select your gender" },
              "description": {
                "en": "We use broad gender groups to find your kind of people. For the best matches, we recommend choosing the one that fits you best."
              }
            }
          ]
        }
      ]
    }
  }
}

What this tells you:

• Edit form has one group titled "About"
• Display components in this order: name, bio, gender
• Use the provided labels, placeholders, and descriptions for each field
• Look up each component's configuration in the components array using the id

Reading Filter Form

The filter form is optional and used for filtering profile data. It typically includes only the fields that are useful for filtering.

Example:

{
  "forms": {
    "filter": {
      "components": [
        {
          "id": "gender",
          "order": 1,
          "label": { "en": "Gender" }
        },
        {
          "id": "birthDate",
          "order": 2,
          "label": { "en": "Birth Date Range" }
        }
      ]
    }
  }
}

What this tells you:

• Filter form uses a flat component list (no groups)
• Display two filter fields: gender and birthDate
• Use the provided labels
• Look up each component's configuration in the components array

How to Use Forms

Forms define the structure of input forms, but the actual values for each field come from the user's profile data (for edit forms) or are empty initially (for filter forms).

Data Flow

1. Fetch the Profile Schema - Get the schema configuration (including forms)
2. For Edit Form: Fetch the User's Profile Data - Get the current values from the Profile Detail service to pre-fill the form
3. For Filter Form: Start with empty values - Users will fill in filter criteria
4. Combine Schema and Values - Merge the form structure with the user's data (or empty values) to render the form

Form Values

Each component in the form references a field by its id. For edit forms, the corresponding value comes from the user's profile data where the field name matches the component id. For filter forms, values start empty and are filled by the user.

Rendering Process

For Edit Form:

1. Iterate through groups in order (sorted by order field)
2. For each group:
   • Display the group title if present
   • Iterate through components in order (sorted by order field)
3. For each component:
   • Look up the component definition in the components array using the id
   • Fetch the current value from the user's profile data using the same id as the key
   • Render the input field:
     • Use the component definition to determine the field type (text, choice, date, address)
     • Pre-fill the input with the value from profile data
     • Use the label, placeholder, and description from the form reference
     • Apply validation rules from the component definition
     • Display the component icon if present

For Filter Form:

1. Iterate through components in order (sorted by order field)
2. For each component:
   • Look up the component definition in the components array using the id
   • Render appropriate filter controls (empty initially)
   • Use the label from the form reference
   • Apply filter-specific validation if needed

Example: Rendering Edit Form

Schema (Edit Form):

{
  "forms": {
    "edit": {
      "groups": [
        {
          "title": { "en": "About" },
          "order": 1,
          "components": [
            {
              "id": "name",
              "order": 1,
              "label": { "en": "Username" },
              "placeholder": { "en": "Add your name" },
              "description": {
                "en": "This is how you'll appear to others. Pick a name that feels authentic and easy to recognize."
              }
            },
            {
              "id": "gender",
              "order": 2,
              "label": { "en": "Gender" },
              "placeholder": { "en": "Select your gender" },
              "description": {
                "en": "We use broad gender groups to find your kind of people. For the best matches, we recommend choosing the one that fits you best."
              }
            },
            {
              "id": "birthDate",
              "order": 3,
              "label": { "en": "Age" },
              "placeholder": { "en": "Add your age" },
              "description": {
                "en": "Your age helps us show you better matches. We'll only display your age, not your exact birth date."
              }
            }
          ]
        }
      ]
    }
  }
}

Component Definitions (from components array):

[
  {
    "id": "name",
    "kind": "text",
    "rules": {
      "required": true,
      "minLength": 2,
      "maxLength": 50
    }
  },
  {
    "id": "gender",
    "kind": "choice",
    "metadata": {
      "variant": "radio",
      "dataSource": {
        "type": "static",
        "choices": [
          { "value": "male", "label": { "en": "Man" } },
          { "value": "female", "label": { "en": "Woman" } },
          { "value": "non-binary", "label": { "en": "Non-Binary" } }
        ]
      }
    },
    "rules": {
      "required": true
    }
  },
  {
    "id": "birthDate",
    "kind": "date",
    "metadata": {
      "displayAs": "age"
    },
    "rules": {
      "required": true,
      "minAge": 18,
      "maxAge": 80
    }
  }
]

Profile Data (from Profile Detail service - current values):

{
  "name": "John Doe",
  "gender": "male",
  "birthDate": "1990-05-15"
}

Rendered Edit Form:

• Username field:

  • Label: "Username"
  • Placeholder: "Add your name"
  • Description: "This is how you'll appear to others..."
  • Pre-filled value: "John Doe"
  • Validation: Required, 2-50 characters

• Gender field:

  • Label: "Gender"
  • Placeholder: "Select your gender"
  • Description: "We use broad gender groups..."
  • Pre-selected value: "male" (radio button "Man" selected)
  • Options: Man, Woman, Non-Binary (radio buttons)
  • Validation: Required

• Age field:

  • Label: "Age"
  • Placeholder: "Add your age"
  • Description: "Your age helps us show you better matches..."
  • Pre-filled value: "1990-05-15" (displayed as date picker, shows age: 34)
  • Validation: Required, age between 18-80

Example: Rendering Filter Form

Schema (Filter Form):

{
  "forms": {
    "filter": {
      "components": [
        {
          "id": "gender",
          "order": 1,
          "label": { "en": "Gender" }
        },
        {
          "id": "birthDate",
          "order": 2,
          "label": { "en": "Birth Date Range" }
        }
      ]
    }
  }
}

Component Definitions (from components array):

[
  {
    "id": "gender",
    "kind": "choice",
    "metadata": {
      "variant": "checkbox",
      "multiple": true,
      "dataSource": {
        "type": "static",
        "choices": [
          { "value": "male", "label": { "en": "Man" } },
          { "value": "female", "label": { "en": "Woman" } }
        ]
      }
    }
  },
  {
    "id": "birthDate",
    "kind": "date",
    "metadata": {
      "displayAs": "date"
    },
    "rules": {
      "minDate": "1950-01-01",
      "maxDate": "2010-12-31"
    }
  }
]

Rendered Filter Form:

• Gender filter:

  • Label: "Gender"
  • Empty checkboxes (no pre-selection)
  • Options: Man, Woman (checkboxes, multiple selection allowed)
  • User can select one or both

• Birth Date Range filter:

  • Label: "Birth Date Range"
  • Empty date range picker (no pre-filled values)
  • Date range: 1950-01-01 to 2010-12-31
  • User can select a date range for filtering

Notes

• Component id values in forms must reference components defined in the components array
• The edit form is required, while the filter form is optional
• Forms can use either groups or a flat component list
• Form component references include placeholder and description for better user guidance
• The same component can appear in both edit and filter forms with different configurations (different labels, etc.)