Metadata Best Practices

Metadata field names must not contain a dot or ellipsis. For example, using this field name returns a Bad Request (400) error:
{ "preference.color": "pink" }
Was this helpful?/
One way of handling this limitation is to nest attributes:
{ "preference": { "color": "pink" } }
Was this helpful?/
Alternately, you can use any delimiter that is not . or $ with the exception that you can use the . delimiter in data values like this:
{ "preference": "light.blue" }
Was this helpful?/

Do not use dynamic field names. Dynamic fields reduce indexing efficiency and cause degradation in search queries. A static schema is easier to search, manipulate, and work with. For example, instead of using this structure:

    "participants": {
        "Alice" : {
            "role": "sender"
        },
        "Bob" : {
            "role": "receiver"
        }
    }

Was this helpful?/

Use this:

    "participants": [
        {
            "name": "Alice",
            "role": "sender"
        },
        {
            "name" : "Bob",
            "role": "receiver"
        }
    ]

Was this helpful?/

Use a consistent data type each time you create or update a given metadata field. For example, if you use user.user_metadata.age = "23" for one user and user.user_metadata.age = 23 for another user, it will cause issues when retrieving the data.

Both app_metadata and user_metadata are together limited to a size of 16 MB total per user. Metadata storage is not designed to be a general purpose data store, and you should still use your own external storage facility when possible. When using Rules and/or the Dashboard, your metadata limits may be lower.
When setting the user_metadata field using the Authentication API Signup endpoint, you are limited to a maximum of 10 String fields and 500 characters. For an example of working with metadata during a custom signup process, see Custom Signup > Using the API.

Store any information that you want to use to customize Auth0 emails in metadata. Use user_metadata.lang if the user is allowed to change the field's value, such as information used to determine the language for an email. See Customize Email Templates for details.

User credentials such as access tokens, refresh tokens, and additional passwords should not be stored in app_metadata, as these will be visible to any Dashboard administrator.

The app_metadata field should not contain any of these properties:

__tenant
_id
blocked
clientID
created_at
email_verified
email
globalClientID
global_client_id
identities
lastIP
lastLogin
loginsCount
metadata
multifactor_last_modified
multifactor
updated_at
user_id

Docs