Rate this page

Schemas

Data Governance Broker users are represented using the data model defined by the SCIM 2 standard in RFC 7643. This is a straightforwardly simple data model, built around the constraints of the JSON format, but with extensibility built in to the model. Whether or not you intend to make SCIM API requests using the Data Governance Broker’s resource server, a little familiarity with the concepts described in this article will be helpful.

Data types

A SCIM schema describes a set of attributes. Each attribute has a type. SCIM data types roughly correspond to JSON types, as shown in the following table.

Data type Description
string A JSON string.
boolean A JSON boolean value. May have either of the literal values true or false.
decimal A JSON floating-point number.
integer A JSON integer number.
dateTime A JSON string representing a timestamp. SCIM DateTime values are always encoded as an xsd:dateTime value, as specified by XML Schema, section 3.3.7.
binary A JSON string representing a binary value. SCIM binary values are always base64-encoded.
reference A JSON string representing a reference to another resource. A SCIM reference is always a URI: This may be a URN, the URL of another SCIM resource, or simply another URL. URLs may be absolute or relative.
complex A JSON object. A SCIM complex attribute is a composition of sub-attributes; these sub-attributes may have any data type except for “complex”.

These data types are also described in section 2.3 of RFC 7643.

Single-valued vs. multi-valued attributes

A SCIM attribute may be single-valued or multi-valued. A multi-valued attribute is just an unordered collection of attributes. The members of a multi-valued attribute must all share the same data type.

Other attribute characteristics

Attributes have other properties that may be defined by the schema. These include:

Attribute characteristic Description
caseExact The case sensitivity of attribute values.
mutability Whether or not the attribute is read-only, write-only, and so on.
returned Whether the attribute is returned by default.
uniqueness Whether an attribute value is unique. Note that the Data Governance Broker does not enforce attribute uniqueness; this must be enforced by the user store.

Typed attributes

When a multi-valued attribute is composed of complex attributes, members conventionally have a sub-attribute called “type”, which indicates the member’s function relative to other members of the multi-valued attribute. For example, an emails multi-valued attribute might have a member with a type value of “work” and another with a type value of “home”.

As the “work” and “home” example values indicate, values of “type” will often have well-defined semantics. Clients may be encouraged or required to use “type” values drawn from an enumeration of well-defined values. These well-defined values are called canonical types.

Core schemas and extension schemas

Users and other resources served by the Data Governance Broker are modeled as SCIM resource types in the server configuration. A resource type should be defined for any collection of data that is treated as a distinct entity; examples of resource types might be users, devices, contacts, products, and so on. A resource type is somewhat analogous to a class in object-oriented programming. By this analogy, any specific resource (e.g., user, device, etc.) is an instance of the class.

A resource type is essentially defined as a set of one or more schemas. Together, these schemas constitute the attributes that may be used for the resource type. A resource type always has one core schema, which is understood to define the base set of attributes for the resource type. A resource type may also have one or more extension schemas, which define logically distinct sets of attributes. Any particular extension schema may be required or optional.

The ability to compose a resource type from various schemas allows the Data Governance Broker administrator to define schemas independently of resource types, mixing and matching them at will. This is a powerful capability that promotes reusability of schemas.

Referring to attributes

SCIM schemas are always identified by a URN, such as urn:pingidentity:schemas:User:1.0. These URNs act as a namespacing mechanism: An attribute can be identified by prefixing its name with its schema URN. For example, the emails attribute of the urn:pingidentity:schemas:User:1.0 schema can be fully qualified as urn:pingidentity:schemas:User:1.0:emails.

urn:pingidentity:schemas:User:1.0:emails

A resource type’s core schema attributes never need to be fully qualified, while a resource type’s extension schema attributes always need to be fully qualified. Say, for example, that we have a Users resource type with the core schema urn:pingidentity:schemas:User:1.0 and the extension schema urn:pingidentity:schemas:sample:profile:1.0. The emails attribute from the urn:pingidentity:schemas:User:1.0 schema can always be called simply emails, because it belongs to the core schema. But the birthDate attribute of the urn:pingidentity:schemas:sample:profile:1.0 extension schema must always be fully qualified as urn:pingidentity:schemas:sample:profile:1.0:birthDate.

User store schemas

You’ll recall that the Data Governance Broker’s user store is comprised of one or more data stores that actually hold users’ data. One of these data stores will always be a Ping Identity Directory Server, which is an LDAP directory server. Another could be an RDBMS such as PostgreSQL or a NoSQL database, such as MongoDB. Most data stores require that their own schemas also be defined, which you may or may not be responsible for designing.

Regardless of whether or not the data stores that make up the user store have explicit schemas, the attributes in the Data Governance Broker’s SCIM schemas must be mapped to data store attributes so that operations against Data Governance Broker users can be translated to requests that can be understood by the data stores. This is either done explicitly, by defining attribute mappings in the configuration, or implicitly, using a Pass Through SCIM Resource Type. For more information about how this mapping process works, see the Ping Identity Data Governance Broker Administration Guide.

The starter schema

The Data Governance Broker comes with an example set of resource types and schemas called the starter schema. This configuration is used by most of the examples in this guide and is also used by the various sample applications. You are strongly encouraged to install this configuration when starting out with the Data Governance Broker. After you’ve become comfortable with using the Data Governance Broker, you can then move on to customizing your schema and configuration.

The starter schema set defines a resource type called “Users” and two schemas:

Schema ID Schema type Description
urn:pingidentity:schemas:User:1.0 core Common user attributes with broad applicability, such as name, email addresses, and phone numbers.
urn:pingidentity:schemas:sample:profile:1.0 extension Marketing preferences. Used by the sample applications.

The above scheme is a good pattern to follow: Place broadly useful attributes in a core schema and place domain-specific attributes in extension schemas.

You are encouraged to study the starter schema files in your Data Governance Broker’s resource/starter-schemas directory to learn more about how they work. Here’s a partial look at what the core schema looks like when retrieved from the Data Governance Broker’s SCIM schemas endpoint:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Schema"
  ],
  "id": "urn:pingidentity:schemas:User:1.0",
  "name": "User",
  "meta": {
    "resourceType": "Schema",
    "location": "https://example.com/scim/v2/Schemas/urn:pingidentity:schemas:User:1.0"
  },
  "attributes": [
    {
      "name": "userName",
      "type": "string",
      "multiValued": false,
      "required": true,
      "caseExact": false,
      "mutability": "readWrite",
      "returned": "default",
      "uniqueness": "none"
    },
    {
      "name": "emails",
      "type": "complex",
      "subAttributes": [
        {
          "name": "display",
          "type": "string",
          "multiValued": false,
          "required": false,
          "caseExact": false,
          "mutability": "readWrite",
          "returned": "default",
          "uniqueness": "none"
        },
        {
          "name": "primary",
          "type": "boolean",
          "multiValued": false,
          "required": false,
          "caseExact": false,
          "mutability": "readWrite",
          "returned": "default",
          "uniqueness": "none"
        },
        {
          "name": "type",
          "type": "string",
          "multiValued": false,
          "required": false,
          "canonicalValues": [
            "other",
            "work",
            "home"
          ],
          "caseExact": false,
          "mutability": "readWrite",
          "returned": "default",
          "uniqueness": "none"
        },
        {
          "name": "value",
          "type": "string",
          "multiValued": false,
          "required": false,
          "caseExact": false,
          "mutability": "readWrite",
          "returned": "default",
          "uniqueness": "none"
        }
      ],
      "multiValued": true,
      "required": false,
      "caseExact": false,
      "mutability": "readWrite",
      "returned": "default",
      "uniqueness": "none"
    },
    ...
  ]
}