Updating the schema

Attention

Updating the schema, if not done properly, can result in being unable to access data. Read this section thoroughly to avoid this situation.

When the z/OS® LDAP server is first started, the server supplies an initial schema. This initial schema is sufficient for usage of the SDBM (without RACF® custom fields), CDBM (with configuration related entries), and GDBM backends, but must be updated for usage of LDBM, TDBM, SDBM with RACF custom fields, and CDBM with user-defined entries. The schema files shipped with the LDAP server, schema.user.ldif and schema.IBM.ldif, might be sufficient for your usage of LDBM, CDBM, or TDBM. See Setting up the schema for LDBM, TDBM, and CDBM for more information about adding these files to the schema. If they are not sufficient, you can change the schema as needed. The schema entry is required and cannot be deleted. When in a sysplex, changes to the schema made at one LDAP server are broadcast to all the LDAP servers in the group. When deleting an attribute type or object class definition, you must provide just the object identifier enclosed in parentheses. Any additional fields that are specified are checked for appropriate syntax but are not used.

The operations supported include adding, modifying, or deleting any object class, attribute type, or IBM® attribute type that is not part of the initial schema definition required by the LDAP server. Changes to the initial schema are restricted. See Changing the initial schema for more information. The modifications (additions, changes, and deletions) specified by the LDAP modify function are applied to the schema entry. The resulting schema entry becomes the active schema and is used by all backends to verify that directory changes adhere to it.

Updates to the schema must be performed such that the schema fully resolves. This includes:

All attribute types referred to in object classes must exist in the schema.
All superior attribute types or object classes must exist.
Only the syntaxes and matching rules supported by the schema might be specified in attribute type definitions.
All attribute types referred to in IBM attribute type definitions must also be defined as attribute types.
All structural object classes must include the top object class in their object class hierarchy.

Modifications to the schema are rejected if they would possibly make existing entries no longer valid. If there is an entry in a TDBM, CDBM, or LDBM backend that is using an attribute or object class:

The attribute or object class cannot be deleted. Instead, "delete" the schema element by modifying it to mark it as OBSOLETE rather than deleting its definition from the schema entry. Therefore, no new entries can be created using the schema element and the existing entries which do use the schema element are still accessible. An existing entry that uses the OBSOLETE schema element must be modified to use only non-OBSOLETE schema elements during the next modification of the entry in order for the modification to succeed.
The attribute or object class cannot be modified in a way that could affect the data in the entry. For example, the syntax of an attribute cannot be changed when that attribute is in use. You must modify the entries first so they do not use the object class or attribute, then change the schema.
The following fields in an attribute type definition are the only fields that can be modified if the attribute type is in use by an entry:

DESC
OBSOLETE
SINGLE-VALUE (can be removed but not added)
NO-USER-MODIFICATION
USAGE
The following fields in an IBM attribute type definition can be modified:
ACCESS-CLASS
RACFFIELD
The following fields in an object class definition can be modified when the object class is in use by an entry:
DESC
OBSOLETE
MUST (can only move an attribute to MAY)
MAY (can only add an attribute)

Changing the initial schema

The initial schema contains the ldapSyntaxes, matchingRules, attributeTypes, IBMAttributeTypes, and objectClasses needed by the LDAP server. See Initial LDAP server schema for the contents of the initial schema.

The syntaxes, matching rules, attribute types, and IBM attribute types in the initial schema cannot be deleted or modified. The object classes in the initial schema cannot be deleted or modified, with the following exceptions:

groupOfNames
groupOfUniqueNames

These object classes allow the following fields to be modified:

DESC
MUST
MAY

The MUST and MAY lists can be modified in any way if no directory entries are using this object class. If there is a directory entry using this object class, the only MUST and MAY changes allowed are to move an attribute from the MUST list to the MAY list and to add an attribute to the MAY list.

Any part of a schema modification that attempts to add LDAP syntaxes or matching rules to the schema or to modify the initial schema except as described above is ignored, with no message issued to indicate this. The rest of the schema modification is performed and the result of those changes is returned to the client.

Replacing individual schema values

It is often necessary to apply an updated schema file to an existing schema. Optimally, this would replace changed values in the existing schema with their updated values from the file and add new values from the file to the existing schema, leaving all other values in the existing schema unchanged. However, this is not the way the RFC 2251: Lightweight Directory Access Protocol (v3) definition for such a modify with replace operation works: the RFC requires that ALL the existing values in the schema be replaced by the values specified in the schema file. Therefore, the schema file must contain all the unchanged values from the schema in addition to the updated and new values so that no unchanged existing values are lost.

To address this problem, the LDAP server supports two different behaviors when using a modify with replace operation on the schema entry:

Standard RFC behavior, in which all the existing values for an attribute are replaced by the ones specified in the modify operation. In order for the modification to succeed, the replacement values must include definitions for all schema definitions that are in use by existing directory entries and the replacement values must conform to the rules described above about what fields can be modified in an active schema entry.
Schema-replace-by-value behavior, in which each replace value in the modify operation either replaces the existing value (if one exists) in the schema or is added to the schema (if an existing value does not exist). All other values in the schema remain as they are. A replace value replaces a schema value if the schema value and replace value have the same numeric object identifier (NOID). Otherwise, the replace value is considered a new value and is added to the existing values in the schema.

In all cases, the values of the attribute that are in the initial LDAP server schema cannot be deleted and can only be modified in limited ways as described in Changing the initial schema.

The behavior used by the LDAP server is selected in one of two ways:

Specify the schemaReplaceByValue option in the global section of the LDAP server configuration file to set the behavior for all modify with replace operations of the schema. Specifying on activates the schema-replace-by-value behavior; off activates the standard RFC behavior. See Customizing the LDAP server configuration for more information.
Specify the IBMschemaReplaceByValueControl control on the modify with replace operation to set the behavior for just that specific modify operation, overriding the schemaReplaceByValue configuration option. Specifying TRUE in the control activates the schema-replace-by-value behavior; FALSE activates the standard RFC behavior. See Supported server controls for more information.

If neither the schemaReplaceByValue configuration option or the IBMschemaReplaceByValueControl control is specified, the default behavior is schema-replace-by-value.

Example: assume that the objectclasses attribute for cn=schema contains the following values:

objectclasses: ( 1.130.255 NAME 'oldObjectclass1' DESC 'old description 1' ... )
objectclasses: ( 1.130.256 NAME 'oldObjectclass2' DESC 'old description 2' ... )
objectclasses: ( 1.130.257 NAME 'oldObjectclass3' DESC 'old description 3' ... )

This is to replace 'oldObjectclass1' and add a value for 'newObjectclass4'.

This is the update file for the modify operation:

dn: cn=schema
changetype: modify
replace: objectclasses
objectclasses: ( 1.130.255 NAME 'newObjectClass1' DESC 'new description 1' ... )
objectclasses: ( 1.3.5.9 NAME 'newObjectClass4' DESC 'description 4' ... )

After the modify operation with schema-replace-by-value behavior, the objectclasses attribute in the schema would have the following values:

objectclasses: ( 1.130.255 NAME 'newObjectClass1' DESC 'new description 1' ... )
objectclasses: ( 1.130.256 NAME 'oldObjectclass2' DESC 'old description 2' ... )
objectclasses: ( 1.130.257 NAME 'oldObjectclass3' DESC 'old description 3' ... )
objectclasses: ( 1.3.5.9 NAME 'newObjectClass4' DESC 'description 4' ... )

If the modify operation with traditional RFC behavior is performed instead, the objectclasses attribute in the schema would end up with the following values:

objectclasses: ( 1.130.255 NAME 'newObjectClass1' DESC 'new description 1' ... )
objectclasses: ( 1.3.5.9 NAME 'newObjectClass4' DESC 'description 4' ... )

IBM attribute types are extensions to the attribute type definition. The IBM attribute type is deleted when the corresponding attribute type is deleted. IBM attribute types are always replaced by value even when schemaReplaceByValue off is specified in the LDAP server configuration file. This ensures that access class protection is not inadvertently removed from an existing attribute type.

Updating a numeric object identifier (NOID)

It might become necessary to update the numeric object identifier (NOID) of an attribute type or object class in the schema. This NOID change can be accomplished by a special modify operation. The modify operation must consist only of a value to delete followed by a value to add. The value to delete must specify the current NOID of the attribute type or object class whose NOID is to be changed; the value to add must specify the new NOID for the attribute type or object class, along with all the other parts of the attribute type or object class definition. For an attribute type, the NAME, SUP, EQUALITY, ORDERING, SUBSTR, and SYNTAX must be identical in the existing definition and the value to add. SINGLE-VALUE can be removed but not added. For an object class, NAME, SUP, MUST, MAY, and type (ABSTRACT, STRUCTURAL, or AUXILIARY) must be identical in the existing definition and the value to add. The entire attribute type or object class definition is replaced by the contents of the add. Note the object identifier assigned to an attribute type or object class cannot be changed if there are any directory entries using the attribute type or object class. Also, the object identifier of an attribute type or object class in the initial LDAP schema cannot be changed.

As an example for changing the NOID of the xyz attribute type from 1.3.5.7 to 2.4.6.8, the update file for the modify operation is as follows:

cn=schema
-attributetypes=( 1.3.5.7 NAME 'xyz' DESC 'xyz attribute added for application abc' \
SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 USAGE userApplications )
+attributetypes=( 2.4.6.8 NAME 'xyz' DESC 'xyz attribute added for application abc' \
SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 USAGE userApplications )

Changing a NOID should not need to be done as part of normal LDAP server operations. It is intended to be used as an error recovery device for when an incorrect NOID has been added to the schema.

Analyzing schema errors

Following is some information about the possible cause of some schema errors that might be encountered when updating schema:

For enhanced readability, type:value pairs in LDIF files might be split across multiple lines. The indicator to LDIF that the subsequent lines are continuations is that the first character on the subsequent line is a space. This character is ignored by parsers and it is assumed that the next character immediately follows the previous line. Therefore, if a space is needed between the last value on one line and the first value on the subsequent line, a second space must exist on the subsequent LDIF line. Various reason codes related to unrecognized values might be issued.
Only limited changes are allowed to the initial schema, as described in Changing the initial schema. All other changes to the initial schema are ignored by the LDAP server with no error returned.
The IBM attribute type schema attribute is an extension to the associated attribute type in the schema. If the schema update contains an IBM attribute type value for which an attribute type value is not defined, the schema update fails. For example,
```
IBMAttributeTypes: ( 1.2.3.4 ACCESS-CLASS normal )
```
cannot be specified unless
```
attributeTypes: ( 1.2.3.4 NAME ’sample’ ... )
```
is also defined.
While the UTC Time syntax is supported, usage of the Generalized Time syntax is preferred. For UTC Time syntax, year values between 70 and 99 assume 1970 to 1999 and values between 00 and 69 assume 2000 to 2069.
When searching attribute type values of Coordinated Universal Time syntax, use Coordinated Universal Time syntax in the search filter rather than local time. All time values are stored in the data store as Coordinated Universal Time times.