Page tree
Skip to end of metadata
Go to start of metadata

Introduction

Common Schema defines basic concepts of Object, Property, Extensible Object, etc. It is very generic. It has no special domain knowledge of identity management systems.

Common schema is used as a foundation for most other schemas in midPoint. It provides a set of XML supertypes common for most system components. It gives the objects their basic structure, identifier and typing mechanism. It also defines object references, contains types for describing object changes, operation results and lots of other "utility" types.

Inline documentation

Most XML types and elements are documented in-line in the schema definition files. Please see the current XSD definition from the source-code repository for the latest version.

Basic Prism Schema Concepts

Object

Abstract

Superclass for all objects. It contains the basic structure that the object must have to be passed between system components and stored in the repository. It defines two XML attributes and two properties:

XML Attribute

Type

Description

oid

string
immutable

System-wide immutable identifier for the object. It may be quite long and not human-readable. It should not be displayed to user. It has no meaning outside of IDM system and should not be directly passed to any third-party systems. This identifier must be unique in the entire system. OID is immutable. It cannot be changed.

version

string
read-only

Version for optimistic locking. Contains the version in which this object was read from the repository, fetched from the resource, etc.

Property

Type

Description

name

string

Human-readable, mutable name of the object. It may also be an identifier (login name, group name), but it is not required to. It should be unique in the respective context of interpretation. E.g. the name of the User subtype should be unique in the whole system. The name of the Account subtype should be unique in the provisioning resource (target system) that it belongs to. Name may not be human-readable in a sense that it is displayable to a common end-user. It is indented to be displayed to IDM system administrator. Therefore it may contain quite an "ugly" structures such as LDAP DN or URL.

description

string

Free-form textual description of the object.

Objects contain properties. In XML representation the properties are usually the first-level elements in Object XML body, but there may be exceptions to this rule defined in the schema. Usually every first-level XML element placed into the body of Object is considered to be Property. But properties may be also found in other sub-elements (extension, attributes) as specified below.

Property

Abstract, Concept

Property is a specific characteristic of an object. It may be considered object "attribute" or "field". For example User has fullName property that contains string value of user's full name.

  • Properties may be single-valued or multi-valued
  • Properties may contain primitive types or complex types (defined by XSD schema)
  • Property values are unordered, implementation may change the order of values
  • Duplicate values of properties should be silently removed by implementations, but clients must be able tolerate presence of duplicate values.

Operations that modify the objects work with the granularity of properties. They add/remove/replace the values of properties, but do not "see" inside the property.

Property is just a concept. It is not implemented by a specific XSD data type. We just define that each and every element placed in the body of Object must be a property or a property container.

Property Container

Abstract

Property container groups properties into logical blocks. The reason for grouping may be as simple as better understandability of data structure. But the group usually means different meaning, source or structure of the data. For example, the property container is frequently used to hold properties that are dynamic, not fixed by a static schema. Such grouping also naturally translates to XML and helps to "quarantine" such properties to avoid Unique Particle Attribute problems.

Property Container contains a set of (potentially multi-valued) properties. The order of properties is not significant, regardless of the fact that it may be fixed in the XML representation. In the XML representation, each element inside Property Container must be either Property or a Property Container.

Property Container is also a supertype of Object and Resource Object as these entities contain properties.

Extensible Object

Abstract

An Object with generic extensibility mechanism. It contains a special XML element extension where any property can be placed. The extension is treated exactly the same as other object properties by the code (storage, modifications, etc), except that the system may not be able to understand its meaning.

The extensible part is quarantined into the extension element to avoid problems with XSD unique particle attribution (UPA) rule.

XML Element

Type

Description

extension

Property[*]

Property container for any non-standard properties of the objects (from other namespaces)

Any non-standard properties may be placed in placed in the extension element and it will be handled almost like a standard property by the code. However the off-the-shelf midPoint code is only expected to understand standard properties defined in this model. The low-level components (including IDM model) that do not understand the non-standard properties must silently ignore them and pass them around the system with the object. The custom properties may therefore be used by expressions, custom business logic or most other customizations.

This is an abstract object type used for extending known object types. It is not supposed to be used to create new object types. For ability to store new object types please see the Generic Object below.

Generic Object

Generic object for storing unknown (unexpected) object types. The generic object should be used if there is a need to store a custom object (e.g Kangaroo) at deployment-time where the XML type replacement extensibility cannot be used. The properties of such custom objects are to be placed in the extension part of this object. The schema is not checked or enforced for this type of objects, unless it is explicitly constrained by the data store (e.g. if this object is stored in LDAP directory, property names may be limited to LDAP attribute names allowed by LDAP schema). Generic object defines one property:

Property

Type

Description

objectType

URI
limited mutability

Type of the stored object. This attribute contains URI defining the type (class) of stored object. The URI that maps to a QName of an object XML element should be used if possible (see URLs and QNames). However this is not mandatory and the implementation must be able to work with any URI. Object type may be changed, but the possible values may be constrained by the implementation. E.g. the implementation may allow to change the object type only to the subtype or supertype, or it may fail if the properties of the object does not conform to the schema constraints defined for the new type, etc.

It is expected that all other properties of the new object type will be placed in the extension XML element of this object.

Off-the-shelf midPoint code will not understand the meaning of generic objects. It will just store them and pass them around as an opaque payload. The generic objects are supposed to be used only by custom business logic, custom expressions and customized midPoint components.

Object Reference

Object Reference is a property that describes a reference to an object. It is used to represent an association between objects, for example, a reference from a User object to Account objects that belong to the user. The reference is a simple uni-directional link that uses an OID as an identifier.

This type should be used for all object references, so the implementations can detect them and automatically resolve them.

It contains two XML attributes:

XML Attribute

Type

Description

oid

string

OID of the object that this reference refers to.

type

QName

XSD type of the object that this reference refers to. It may be used in XPath expressions and similar filters.

Schema Annotations

container

object

There are some aspects of the Schema that cannot be expressed by using just the standard XSD mechanisms. Such aspects include specification of printable names, default element names, etc. The midPoint schema defines a set of XSD annotations that can be used for this purpose. The annotations extend the XSD language as we need.

displayName

Specifies the printable name of the object class or attribute. It must contain a printable string.

This is supposed to be an annotation of an Property Container (XSD complexType) or Property (XSD element) definitions. As it applies to Property Container it also applies to Objects.

defaultElement

Specifies the default name of the XML element that represents specific XSD type. It is meaningful only for XML representation of the schema. It can apply to any XSD type. It must contain QName of existing element defined in the schema.

help

Specifies the help text or a key to catalog file for a help text. The help text may be displayed in any suitable way by the GUI. It should explain the meaning of a definition. Usually applies to a property, but may also apply to other definitions.

targetType

The target type of an object reference. This annotation may appear in object reference type definitions and specify a valid XSD object types whose may be the targets of the reference.

  • No labels