Resource Schema

Resource Schema defines representation of the information from the resources. Resource schema describes "live" objects such as accounts, groups or entitlements.

Specific resource schema depends on the actual resource instance: what type it is, how the adapter/connector is configured, what kind of native schema it is using (e.g. LDAP inetOrgPerson) and how the schema is customized. The information that the resource schema describes is dynamic and cannot be expressed as static XML structure. Resource schema can only be determined in run-time. Dynamic resource schema can vary for each instance of resource, e.g. two LDAP servers using exactly the same product, version, connector and even very similar connector configuration may show a very different resource schema. Resource schema is defined using the XSD language as most other schemas in midPoint.

We will refer to parts of the dynamic resource schema using a slightly different terminology than we use for static schemas. While the static XSD types in midPoint use Type suffix in their XSD names, dynamic resource schema is using a ObjectClass suffix for the XSD types. This naming distinction avoid confusion between the static parts of midPoint and the dynamic resource schema.

Resource schema works together with another dynamic schema: Connector Schema. The Resource and Connector Schema Explanation describes how these two fits together.

It may look like the resource schema definition is duplicating many objects from the identity schema. E.g. the Object Class concept may look like Object Shadow, Account Object Class may look like Account Shadow. But this is not really the case. It is not a duplication, but rather an alignment of concepts. The resource schema is only available at run-time, therefore we need a static equivalent for these concepts in compile-type, e.g. to be able to store them in repository. Identity schema is static and takes that role. Secondly, the generic objects defined in the resource schema are defined in a very loose manner regarding their identification and therefore also referencing. They have no universal concept of unique identifier. To be able to store them efficiently and manage them, we need OID which is provided by the objects in identity schema. The identity schema acts as a mapping between native identifier and the OID. Thirdly, the resource schema is a shearing layer on top of identity schema as we want great deal of flexibility in the resource schema. That provides the capability of midPoint to adapt to almost any resource schema that we may encounter in the field.

Resource schema defines capabilities of the Resource and the connector. Resource schema is a dynamic thing. It is in fact usually generated by the connector on demand and is not written by system administrator at all. It has (almost) nothing to do with midPoint configuration. For example, if there is an optional attribute givenName in the LDAP schema and the connector can expose that attribute to midPoint the Resource Schema will also contain such attribute. It will be most likely marked as read-write and optional. It does not matter if midPoint is using that attribute or not, it will be in the resource schema.

The details of how the Resource Schema is used by the midPoint is not part of the Resource Schema itself. It is defined by the Resource Schema Handling - except for one detail. Resource schema can suggest how the object classes and attributes should be used which provides reasonable default settings for midPoint. This is expressed in the resource schema by appropriate annotations.

The basic principle is:

Object Class refers to a type of object on the Resource. Unix account, Active Directory group, inetOrgPerson LDAP objectclass or a schema of USERS database table are all Object Classes from the midPoint point of view. Object class defines a set of attribute names, types for each attribute and few additional properties.

Object classes are presented in the form of simple XSD schema objects in midPoint. Each object class is a XSD complex type. Each first-level element in such complex type is considered to be an attribute of the object class. XSD datatypes are used to describe the attribute types. Usually primitive and simple types are used (such as xsd:string), but even a complex types may be used (with some limitations, see below). Usual XSD constructs such as minOccurs and maxOccurs are used to describe whether the attribute is mandatory and whether it is single-valued or multi-valued, as described in the following table.

The XSD form of object class depends on the connector. It is generated by the connector (directly or indirectly) as it is in fact a definition of the objects that the connector understands.

MidPoint has a slightly unusual approach when it comes to the object class and attribute names. midPoint does not try to map object class names and attribute names to some kind of common "global" structure. midPoint is exposing the native resource terminology all the way to business logic and GUI. It means that if account object class is known as inetOrgPerson on the resource and it contains attribute cn, the accounts from that resource will have attribute cn and will be presented as being of type InetOrgPersonObjectClass. We do not consider the lack of the mapping as a drawback. The mapping is usually too simplistic to be of any use for real IDM deployments and it only leads to a confusion. Therefore we have decided to show the real names through the whole system. Note that the attributes can still be transformed and synchronized to other attributes and properties using several midPoint mechanisms, such as inbound and outbound expressions. See (Resource Schema Handling for more details).

The general rule of thumb is that XSD Object Classes should be as close to the "culture" of the target system (resource) as possible. It should use the same or similar names for XSD elements as are the resource attributes. Similarly, the names of object classes should reflect the types of object on the Resource. For example the LDAP inetOrgPerson object class should be mapped to InetOrgPersonObjectClass XSD type, containing the cn, sn, givenName and similar elements (see the example below). In addition to this, the connector should put nativeObjectClass and nativeAttributeName XSD annotations in the schema. This may be used by the tools and business logic.

The complete process how native resource schema is used by the connector and mapped to Resource Schema is illustrated at Resource Schema Mapping page.

Resource object attribute is a property of object class. All that applies to property applies also to attribute, e.g. only a whole attributes can be changed, they may be simple or complex types, they should be representable in XML, etc. In addition, attribute definition may have some annotations that suggest its purpose and use on the Resource.

There are some aspects of the Resource Schema that cannot be expressed by using just the standard XSD mechanisms. Such aspects include designation of identifiers for the Object Class, native object class and attribute names, readable names, etc. The midPoint resource schema defines a set of XSD annotations that can be used for this purpose. The annotations extend the XSD language to match our needs. Some annotations are authoritative information, some are just suggestions (default setting) that can be overridden in the Resource Schema Handling. Following sections define the annotations that can be used in the Resource Schema.

But, as such definition is not available at run-time, it cannot be mapped to Java using JAXB or similar compile-time technology. The resource schema needs to be dynamically interpreted at run-time, which makes the code quite complex.

The attributes of object class are properties, therefore they theoretically may have a deeper structure. However, midPoint does not care about that structure, it considers the attribute to be opaque. If there is a structured attribute, midPoint will pass it unchanged all the way from the connector to the business logic and GUI.

TODO