For the most part, people think of user profiles as being, well, user profiles: a collection of information that a user enters themselves or that is automatically supplied when a user logs by using social login.
However, user profiles are more than just a collection of information. For example, why can users provide their first and last names in their profiles, but not their maiden names? Why can users specify the city and country they live in, but not the county that they live in? Why can users indicate the organization that they work for, but not the department that they work in? What is it that determines the information that users can and cannot supply in their user profiles?
As it turns out, there’s one answer to all of those questions: the schema.
Each Janrain entity type (including the user entity type, the underlying database for user profiles) has a schema, a blueprint that specifies what can and cannot be stored in that entity type. For example, the schema dictates such things as the:
- Attributes used to store customer information (email; displayName; primaryAddress.city).
- Type of data that can be stored in those attributes (for example, the lastUpdated attribute can only store datetime information).
- Attributes that can be referenced in a Console search.
To make the best use of the information stored in your user profiles, you need to understand the user schema and how it works. And to help you gain that understanding, this section of the Console documentation includes the following topics:
Note. If you have other entity types (for example, a custom entity type named employees), then those entity types will have a schema as well; in fact, to create a new entity type you start by building the schema for that type. (Because, needless to say, you need a blueprint before you start building.) Because the user schema is the most widely-used Janrain schema, this documentation will typically refer only to the user schema and the user entity type. However, the concepts that apply to the user schema and the user entity type also apply to any other schema and entity type used in your organization.
Accessing the Manage Schemas Page
Providing access to schemas is nothing new; for example, this information has long been exposed in the Capture Dashboard:
As you can see, the Capture Dashbord includes some extremely useful information. That said, however, the Capture Dashboard only displays a handful of schema properties (the attribute name, the attribute datatype, and any data constraints associated with the attribute). And that’s it. You cannot look at the Schema page in the Capture Dashboard and determine whether or not attribute values are case-sensitive, or whether you can use a specific attribute in a Console search. If you want that kind of information (and you probably do), you need to turn to the Console’s Manage Schemas page.
Note. At this point in time, the Manage Schemas page is read-only: you can view schema information (and download a copy of the schema), but you can’t really manage the schema: you can’t add or delete attributes, mark an attribute as searchable or case-sensitive, etc. In the future, that will likely change. For now, however, managing your schemas means using the entity type APIs or contacting your Janrain representative.
The Manage Schemas page is accessed like any other page in the Janrain Console; you simply click the appropriate link in the navigation pane:
That’s all there is to it, although there are couple of things to keep in mind here. First, the Manage Schemas link is only visible to Administrators: if you hold any other Console role you won’t even see the link, let alone be able to access the page. In addition, clicking Manage Schemas only toggles the display of the individual entity types used in your organization. To navigate to a schema page, click the name of the entity type itself (e.g., user).
Viewing Schema Information
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. Name of the attribute. As we’ve learned elsewhere, 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. 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.
Description. 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.
Length. 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.
Required. 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.
Unique. 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 email@example.com. 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 firstname.lastname@example.org in the user entity type as well as an email@example.com 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.
Case Sensitive. 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:
clients.clientId = "xyv3q7xhces2yy7cumgrte24epx4m2st"
However, this search – which substitutes uppercase letters for the lowercase letters used in the client ID – won’t return anything at all:
clients.clientId = "XYV3Q7XHCES2YY7CUMGRTE24EPX4M2ST"
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.
Searchable. 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.
Primary Key. 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 https://docs.janrain.com/registration/data-management#features.
Default Value. A value automatically populated for a user record unless a different value is explicitly specified when the record is created.
Write Once. 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. 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:
Exporting a Schema
To export a schema, go to the Manage Schemas page, click the Download File button, and then click the desired export format:
Your exported schema file will be downloaded and saved using a file name composed of the schema name and the appropriate file extension (for example, user.csv or user.json).