User component schema

The user component lets responders select Microsoft Entra or Team users. It stores the selected user object rather than only a name or email address.

User sources

`usersSource`	Behaviour
`teamMembers`	Uses users known to the Team’s SharePoint site. This is the builder default.
`organization`	Searches users across the signed-in user’s organisation. Guest and directory policies can affect availability.
`specificUsers`	Restricts the options to the exact objects in `specificUsers`.

An organisation user picker can use:

{
  "type": "user",
  "key": "requester",
  "label": "Requester",
  "usersSource": "organization",
  "multiple": false
}

Specific users

When usersSource is specificUsers, provide exact directory objects already selected in the builder or explicitly supplied by the user:

{
  "type": "user",
  "key": "reviewer",
  "label": "Reviewer",
  "usersSource": "specificUsers",
  "specificUsers": [
    {
      "id": "existing-directory-object-id",
      "displayName": "Alex Manager",
      "mail": "alex.manager@example.com",
      "userPrincipalName": "alex.manager@example.com"
    }
  ]
}

Never invent user IDs, email addresses, or directory objects. The AI assistant does not have a directory-search tool, so it may only preserve existing objects or use exact values supplied by the user.

Stored values

Organisation users commonly contain:

{
  "id": "directory-object-id",
  "businessPhones": ["+61 8 5555 0100"],
  "displayName": "Jane Smith",
  "givenName": "Jane",
  "surname": "Smith",
  "jobTitle": "Solutions Architect",
  "mail": "jane@example.com",
  "mobilePhone": null,
  "officeLocation": "Perth",
  "preferredLanguage": "en-AU",
  "userPrincipalName": "jane@example.com"
}

Team-member values use the SharePoint user record and can include userLookupId. With multiple: true, the component stores an array of these objects.

Use paths such as data.requester.displayName and data.requester.mail. See Component response values for usage across calculations and templates.

Field projection and sample metadata

Use selectFields to retain only required properties in the stored response:

{
  "selectFields": ["id", "displayName", "mail"],
  "sampleItem": {
    "id": "directory-object-id",
    "displayName": "Jane Smith",
    "mail": "jane@example.com"
  }
}

sampleItem should represent the projected single-user object, even when multiple: true. Team Forms uses this metadata for email suggestions, connector schemas, and executable-code types. It is not a default or submitted value.

If no projection is needed, omit selectFields and preserve the full provider-returned object. Do not add fields to sampleItem that the selected source does not provide.

Refreshing and copying

Property	Type	Behaviour
`multiple`	boolean	Stores an array and allows more than one selected user.
`refreshOn`	string array	Refreshes available users when the listed component paths change. The special value `data` means any response-data change.
`clearOnCopy`	boolean	Excludes the selected user when copying an existing response.
`defaultValue`	user object or array	Initial selection. Preserve builder-managed current-user placeholders rather than inventing their internal shape.