Managing Schema

From clause 13.1.8 of ITU-T Rec. X.501 and Section 4.1.7.2 of RFC 4512

In simplest terms, a name form is a particular schema definition which requires specific RDN syntaxes for use upon entries bearing a specific STRUCTURAL class.

To offer an example of this, consider the following UDDIv3 name form, per the 03-uddiv3.ldif file included with OpenDJ:

This name form states that any entry bearing the STRUCTURAL class uddiBusinessEntity MUST ONLY be designated using the uddiBusinessKey as the principal RDN attribute type, for example, " uddiBusinessKey=ABC123 ".

Alternatively, when devising custom name forms, it is possible to enforce the use of specific attribute types within multi-valued RDNs. Consider the following hypothetical name form:

This name form states that any entry bearing the STRUCTURAL object class groupOfUniqueNames MUST be designated using attribute types cn and o for a qualifying entry bearing a multi-valued RDN, such as " cn=Auditors+o=Acme Audit Co ".

Name forms also allow use of MAY clauses. Consider the following hypothetical name form, similar to the above:

This rule enforces use of the cn RDN attribute type the same as before, but while it no longer requires use of o, it will not reject it when present. As such, either of the following RDNs are acceptable:

But, regardless of the permutations, a name form does little good in practice — unless it is referenced by a DIT structure rule.

From clause 13.1.6 of ITU-T Rec. X.501 and Section 4.1.7.1 of RFC 4512

In short, a DIT structure rule enforces the terms of its prescribed name form. To offer a simple analogy, if a name form presents a law, the DIT structure rule is the public official upholding that law.

Consider this structure rule, per the included 03-uddiv3.ldif file:

This rule employs the uddiBusinessEntityNameForm definition, and constrains entries bearing the STRUCTURAL object class of the name form — also known as the namedObjectClass — to the RDN attribute type (in this case, uddiBusinessKey).

When a DIT structure rule is introduced to the directory schema, it will not be evaluated until an entry is added to the DIT it enforces.

DIT structure rules shall not influence preexisting entries, even if based upon now-illegal STRUCTURAL class and RDN combinations.

Once structure rules have been established, when a new entry is added to, or renamed within the DIT in violation of a structure rule, OpenDJ will return "Object class violation (65)" along with additional contextual information for debugging purposes.

But when a new entry is successfully added to or renamed within the DIT, a new operational attribute type appears on the entry: governingStructureRule.

From clause 13.1.7 of ITU-T Rec. X.501:

See also Section 3.4.6 of RFC 4512.

In simplest terms, the governingStructureRule contains the integer identifier of the DIT structure rule which governs the entry. In the case of the above DIT structure rule, it would appear in LDAP search results as follows:

Instances of this attribute type may be used for diagnostic reasons, or by client applications designed to determine the appropriate RDN syntax to be applied for a new entry, or for an entry being renamed and/or moved, in advance of the request.

DIT structure rules can be configured in such a way that a particular rule extends from, or is subordinate to, another DIT structure rule using the SUP clause.

The purpose of the SUP clause is to allow an entry with a particular RDN syntax to reside beneath one of multiple possible choices. For example:

In this example, the integer identifiers 20 and 21 indicate that the bearer of this clause will allow entries to reside as subordinates to either of the entries governed by those rules.

Also note that rules can be recursive or "self-referencing". This manifests as an instance where a DIT structure rule possesses a SUP clause member that matches its own integer identifier. This is a particularly useful feature because it allows nesting of compliant entries — for example, those bearing the organizationalUnit STRUCTURAL class — to exist within superior entries of like-design.

For an example of recursive rules in action, see the ouStructure rule (21) in the next section.

This section will cover the highlights of creating initial DIT content while under the control of easily-understood DIT structure rules enforcing the use of common attribute types within entry RDNs.

The following basic assumptions apply:

To begin, let’s take a look at the following nameForms definitions:

These name forms declare the following mandates:

Next, we’ll take a look at the new dITStructureRules instances, which will bring the above name forms to life:

From these rules, one can begin to perceive an abstract DIT structure, defined by the incrementing — and hierarchically-significant — integer identifiers, each of which reflect the following respective conditions:

Next, we’ll be creating the initial portions of the governed DIT using ldapmodify, and periodically checking the results with ldapsearch along the way.

So far, so good. What we’ve just done is create the initial structure of our DIT, and in doing so we’ve confirmed the DIT structure rules do not seem to be interfering.

But, let’s stop for now and check our work. We want to see the DIT structure rules that are actively governing our entries. To do this, we need only perform a simple anonymous LDAP search:

This proves the following:

Let’s see what happens when we attempt to add an entry bearing an unauthorized RDN syntax.

Good, the DIT structure rule in question seems to work in preventing bogus RDNs. Now let’s continue with entries that are expected to work.

Again, let’s check our work (omitting the contents of the previous LDAP search):

So, what did we learn?

DIT structure rules are extremely powerful. When properly planned and implemented, they can greatly aid in the formation of clean and orderly directory structures without the need for additional ACIs.

Because DIT structure rules do not influence preexisting entries, even those in violation of those rules, this presents a potential pain-point regarding the restoration of content that (in some way) predates the incorporation of those DIT structure rules. This situation may apply following a disaster-triggered reload of data, or when using this data to "seed" a new DSA being built in the topology.

If DIT structure rules are already applied to the DSA in question, but data has NOT yet been loaded, the DIT structure rules in question will consider ANY data to be "new" regardless of its true chronological age.

If violations are perceived, this will result in errors during the incorporation of that data. This can be confusing to administrators if that same data exists as expected on other DSAs — even those with effectively identical configurations.

When introducing DIT structure rules to an established (preexisting) DIT, it is strongly recommended that separate load-tests be conducted on a disposable system or virtual image that is under the governance of all planned DIT structure rules. This will allow accurate simulation of new in-topology server builds, or rebuilds of preexisting servers that have suffered a malfunction of some kind, or have been rebuilt due to upgrade or other reasons.

Directories which utilize both DIT structure rules as well as collective attribute subentries, per RFC 3672, will require specific adjustments to allow these two features to cooperate.

Clause 14.2.2 of ITU-T Rec. X.501 defines the subentryNameForm ASN.1 definition, which is intended solely to enforce a singular naming convention for subentries:

The same subsection also states that "No other name form shall be used for subentries". In other words, according to this standard, this is the ONLY permitted name form for subentries.

As such, the OpenDJ package conveniently includes the equivalent LDAP name form definition within the subschema subentry for users to leverage:

As a result, users are only expected to implement the DIT structure rule meant to reference this name form.

Consider the following fictional structure rule definition, which contains two distinct "placeholders" the user needs to populate:

As with any new structure rule, the user will need to first assign a unique integer identifier to replace the <structure rule ID> placeholder. For the purposes of this example, let’s assume "88" is chosen.

Next, all superior structure rule integer identifiers under which a subentry COULD be created MUST be referenced. For the purposes of this example, let’s assume the superior structure rule identifiers chosen are "15" and "16", meaning that subentry instances are permitted as subordinate entries to those parent entries which currently bear a matching governingStructureRule integer identifier.

As such, the final structure rule would appear as:

Because subentries themselves do not allow for subordinate entries, we need not worry about rule recursion in this instance.

Again, this procedure is only necessary in directories which utilize DIT structure rules and collective attribute subentries.

Some LDAP implementations on the market today offer no support for DIT structure rules. A common workaround for this is the use of ACIs to enforce specific naming conventions for entries. While OpenDJ supports this technique just the same, there are potential caveats.

Use of ACIs to enforce such rules can be bypassed by users with sufficient access privileges. DIT structure rules, on the other hand, are defined in the schema, which conceptually exists at a lower and more fundamental level than ACIs. As such, no user can bypass a DIT structure rule using conventional means — not even the root DN.

There is also the classic argument that use of ACIs to effect "behavioral changes" in this manner is contrary to the very intent of ACIs. Because DIT structure rules are essentially immutable and do not discriminate the origin of any request, they resemble configuration directives in practice more so than an expression of privilege.

The argument against ACIs in this context gains additional momentum when one considers the innate risk of altering ACIs for any reason, as even the slightest misstep can deny critical functionality or, worse, expose data.