Skip to main content

User Attributes Schema Guide (MCP)

This guide explains how to define, validate, and safely update the tenant user attributes JSON schema. It is used by MCP tools and the user attributes API to control which custom fields users can store.

When to use​

  • You need to create or update the schema that validates user.attributes.
  • You want to add, remove, or change custom attribute fields.

Key rules (enforced)​

  • JSON Schema Draft 2020-12 only.
  • Schema type must be object.
  • Reserved field names are blocked (e.g. email, username, is_active, attributes).
  • Attribute names must be lowercase snake_case and start with a letter.
  • required must be a list and each required field must exist in properties.
  • additionalProperties is enforced to false at validation time.
  1. Read the current schema using MCP:
    • user_attributes_schema(action="get")
  2. Merge changes locally (add/remove/rename properties, update required).
  3. Replace the schema using MCP:
    • user_attributes_schema(action="update", schema=...)

⚠️ The update action replaces the entire schema. It does not merge.

Common patterns​

  • Add a new field: add a property definition and optionally add to required.
  • Soft deprecate: keep property but remove from required.
  • Rename field: add the new property, migrate data, then remove the old property.

Example schema​

{
  "type": "object",
  "title": "UserAttributes",
  "properties": {
    "department": {
      "type": "string",
      "title": "Department",
      "enum": ["HR", "DEV", "SALES"]
    },
    "level": {
      "type": "integer",
      "title": "Level",
      "minimum": 1,
      "maximum": 10
    }
  },
  "required": ["department"]
}

Permissions​

Updating the schema requires manage_site permission for the tenant.

Troubleshooting​

  • "Reserved field" error: rename the attribute to a custom snake_case name.
  • "Required field not found": ensure each item in required exists in properties.