The Manage Schemas page consists of a table composed of 12 columns; each row in the table represents an attribute in the specified entity type, and each column represents a property of that attribute. For example, the following graphic shows some of the attributes found in the user schema (uuid; id; created; etc.), along with attribute properties such as Name, Type, Description, and Length:
So what exactly are all those properties, and what do they mean? Here’s a brief summary:
Name of the attribute. As we’ve learnedelsewhere, attribute names are case-sensitive, at least when doing Console searches: you can search on the displayName attribute (with an uppercase N), but you can’t search on displayname or DisplayName. Attribute names must be typed exactly as shown in the schema.
Which is one reason why it’s handy to have access to the schema from within the Console.
You should also take note of attributes (such as clients or primaryAddress) that are displayed in green and are accompanied by an expand/collapse arrow:
These are either objects or plural attributes, attributes that can contain more than one value; for example, a single user can have multiple clients. (To be a little more precise, some plurals can contain multiple attribute sets: as noted, a single user can have multiple clients. In other cases, a plural might be an object that contains a single, fixed set of attributes.) To view the “sub-attributes” that make up a plural or an object, click the expand/collapse arrow:
As shown above, the clients plural is composed of attributes such as id, clientId, and firstLogin. When referencing one of these sub-attributes in a search query, you must use dot notation to specify the full path to the attribute. In other words, the official attribute name (path) must include:
- The plural or object name (clients)
- A dot (.)
- The attribute name (clientId)
That means that an individual plural or object attribute will have a name similar to one of these:
If you only search on the attribute name (e.g. clientId or city), your search will fail.
Type (and format) of the data that can be stored in the attribute. For example, datetime attributes such as lastUpdated can only contain datetime values formatted according to the ISO 8061 standard. Likewise, Boolean attributes (such as optin.status) can only contain the values True or False.
For more information, see Managing Your Schema.
A brief description of the attribute. To help save screen space, only the first few words of a description are displayed when you view the Manage Schemas page. For example, the description for the displayName attribute looks like this:
The ellipsis (…) at the end of the description indicates that there’s more to the description than initially meets the eye. To see the full description for the attribute, click anywhere on the displayed description:
When you are finished, click Close. If you download a copy of the schema, the complete description appears in the download; downloaded descriptions aren’t truncated in any way.
Maximum number of characters that can be stored in the attribute. For example, the email attribute can contain a maximum of 256 characters. If you enter an email address that contains, say, 257 characters, that update will be rejected.
If this column contains a checkmark, that indicates that the attribute must contain a non-null value. If the Required column does not contain a checkmark then the attribute is optional: for example, you can have a user profile without specifying the user’s birthday or phone number.
Note that some attributes are automatically created when a profile is created:
Even though these attributes are required, you won’t see a checkmark in the Required column. That’s because, in addition to being auto-created, these attributes are read-only, at least for human beings: no one, not even an administrator, can change the value of the created or the lastUpdated attribute.
Janrain schemas support two levels of uniqueness. A globally unique attribute means that the value of the attribute must be unique among all the entities in the entity type. For example, email is a globally unique attribute: that means only one user in your user database (i.e., one entity in the user entity type) can have the email address firstname.lastname@example.org. You cannot create a second user profile that uses that same email address.
However, you can have two user profiles that use the same email address as long as those profiles use different entity types. For example, you can have an email@example.com in the user entity type as well as an firstname.lastname@example.org in a custom entity type.
Other attributes are locally unique. Locally unique attributes must be unique across all the plural attributes in a single entity. For example, August Springer’s user profile can only have one client with the client ID xyv3q7xhces2yy7cumgrte24epx4m2st; you cannot add a second client to his profile that uses that same client ID.
However, other user profiles can reference that same client ID: Maria Fuentes and Toni Loc and Barry Alvarez can all have a client that uses the ID xyv3q7xhces2yy7cumgrte24epx4m2st. Locally unique attribute values must be unique within an individual profile, but those values can be shared with other profiles.
A checkmark in the Case Sensitive column indicates that letter casing matters when searching for an attribute value. For example, the clients.clientId attribute is case-sensitive. To search for a client ID, you must specify the ID exactly as it appears in the user profile. This search returns the expected user profiles:
However, this search – which substitutes uppercase letters for the lowercase letters used in the client ID – won’t return anything at all:
That’s because, for case-sensitive attributes, an uppercase X is considered a different character than a lowercase x. You won’t find many case-sensitive attributes, but there are a few of them, and it’s crucial that you know about them.
Indicates that the attribute can be used in a Console search. (Searchable attributes are typically referred to as indexed attributes.) Out of the box, only a handful of attributes are searchable in the Console; these include most of the auto-generated attributes (such as uuid and created); globally unique attributes (e.g., email); and locally-unique attributes (for example, clients.clientId), and a few others. If you’d like to mark other attributes as searchable, contact your Janrain representative.
Used to uniquely identify records either within an entity type (globally unique) or within a single entity (locally unique). For more information on primary keys, see the Data Management section of this website.
A value automatically populated for a user record unless a different value is explicitly specified when the record is created.
Attributes that can be written to one time, then are never changed. For example, when you create a new user profile, the date and time are automatically entered in the created attribute. Once entered, however, that value cannot be changed.
Legacy validations are data rules and constraints that are still valid, but are being phased out. If you have already placed one of these rules or constraints on an attribute the Console will respect that constraint; however, you will not be able to add a similar constraint to a different attribute. For example, you might have an attribute marked as unicode-only; that means that you can only enter data that meets the Unicode character standard. The existing validation for that attribute will be respected.
Legacy validations are indicated by an icon in the Legacy Validations column; the number on the icon tells you the number of rules or constraints in the validation:
To view the actual constraints, click the icon: