Novell is now a part of Micro Focus

Ten Guidelines for Designing Effective Schema Extensions

Articles and Tips: article

Jacob Hammons
Technical Writer
Novell Developer Kit
jhammons@novell.com

01 Sep 2001


Thanks to Alan Clark, Jane Shropshire, and Cameron Morris of Novell for providing content for this article.

This AppNote provides ten guidelines to help software designers, in-house developers, and network administrators create effective extensions to the Novell eDirectory schema. It also contains references to other resources to find additional information on the topics presented.


Topics

directory services, Novell Directory Services (eDirectory), schema extensions, programming guidelines

Products

Novell eDirectory (all versions)

Audience

network administrators, developers, integrators

Level

intermediate

Prerequisite Skills

familiarity with Novell eDirectory and database programming

Operating System

n/a

Tools

Novell Developer Kit

Sample Code

no

Introduction

Since its inception in 1994, Novell Directory Services (NDS) has always featured an extensible schema. (The schema is a set of definitions that define the types of objects and attributes that are supported in the NDS database.) Over the years, thousands of software designers, in-house developers, and administrators have taken advantage of this feature to extend and customize the schema to tailor NDS for their specific needs and environment.

NDS itself has continually evolved until it is now a multi-platform, highly scalable, distributed enterprise directory called Novell eDirectory. When combined with leading-edge technologies such as DirXML, Novell eDirectory can store, manage, and synchronize data from hundreds of different sources.

With these advancements, the need for customization has only increased. As extending the eDirectory schema has become more common, Novell has responded by creating a number of valuable resources for schema development. This AppNote highlights many of these resources and gives you pointers to help you create the most effective schema possible. Coming from some of the top schema designers at Novell and the Novell Schema Review Board, these guidelines are intended to help you avoid many of the pitfalls that occur when working with a highly scalable, distributed enterprise directory.

If you need to brush up on your schema basics, refer to the list of relevant resources at the end of this AppNote.

Schema Extension Guidelines

This section outlines ten guidelines and recommendations to help you become more proficient when extending the eDirectory schema. The guidelines are listed here, and then each one is explained in more detail under the headings that follow.

  1. Register a prefix and a unique ID.

  2. Conform to LDAP naming conventions.

  3. Consider using LDIF.

  4. Use auxiliary classes.

  5. Use the correct syntax.

  6. Define inclusive containment.

  7. Select appropriate class flags and attribute constraints.

  8. Comment each class and attribute.

  9. Add attributes as needed.

  10. Maintain compatibility.

1. Register a Prefix and a Unique ID

To avoid schema conflicts, Novell Worldwide Developer Support maintains an eDirectory schema registry with the Novell Base schema ("Red Box"), technology forum-defined schema, and developer-defined schema. By registering a unique prefix and an ASN.1 OID in this registry, you can ensure that your schema extensions will be unique and will not cause collisions with other schema.

Even developers creating in-house schema that may never be distributed should register. Why? Because the OID you use may unintentionally collide with another reserved number. Replacing an OID requires a revamp of your schema, which can dramatically affect the current entries in your directory trees.

To register, http://developer.novell.com/support/schreg2c.htm or call 1-800-REDWORD (1-800-733-9673). You will be asked to select a three- to eight-letter unique prefix, and you will receive an ASN.1 OID from Novell (or you can provide your own). Once you have registered a prefix and an ASN.1 OID, you can immediately design and implement schema extensions that are unique in NDS with the current schema definitions.

2. Conform to LDAP Naming Conventions

LDAP allows attribute and class names to contain only ASCII letters and hyphens. NDS has been less restrictive, allowing spaces, underscores, and colons. To solve this conflict, NDS internally maps incompatible names with compatible names (this mapping can be viewed using ConsoleOne).

To minimize mapping issues and for future compatibility, we strongly recommend that any new classes or attribute names that you create should follow LDAP rules.

It is also a recommended convention to prefix each schema definition with your extension in lowercase and capitalize the first letter of each descriptive word. For example, if you registered the prefix xyz, your schema name would start with xyz in lowercase, with each descriptive work in initial caps; for example, xyzKillerClass and xyzKillerAttribute.

3. Consider using LDIF

LDAP Data Interchange Format (LDIF) is designed to be readable and portable across LDAP directories. LDIF files are the preferred format for making schema extensions, as they provide a few distinct advantages:

  • Code does not need to be recompiled to make a change.

  • They are in human-readable format.

  • Administrators can easily see schema changes before they are made.

  • The format is based on open standards, making your extensions compatible with other LDAP directories.

Novell has developed a powerful utility to handle LDIF files. This Novell Import Convert Export utility allows you to import data from an LDIF file, an LDAP directory, or a delimited-data file. The imported data can then be exported to an LDAP directory, or to a different file format. If you would like to take a look at the LDIF format, this tool can be used to export schema definitions from and LDAP directory and import them to an LDIF file.

LDIF is defined in RFC 2849, "The LDAP Data Interchange Format (LDIF)-Technical Specification." For more information, see http://www.ietf.org/rfc/rfc2849.txt.

4. Use Auxiliary Classes

Where possible, do not add attributes to core NDS objects; use auxiliary classes instead. Auxiliary classes and their attributes are added to existing entries in the tree, and are great for extending entries with application-specific information, or for extending a subset of entries. Auxiliary classes provide a great deal of flexibility, and they can be removed easily.

Also note that if you are adding a new class definition or attributes to existing NDS classes, some modules in versions of NetWare earlier than NetWare 5 SP4 have a 4KB limit for a definition.

Before creating a new class or modifying an existing class, consider if the attributes would be better served in an auxiliary class.

5. Use the Correct Syntax

When designing new attributes, carefully evaluate the syntax you have selected for each attribute. Try to keep schema data simple and usable by multiple applications, and make sure that you have selected the best fit for the type of data you are storing.

NDS uses over 25 syntaxes. Taking the time to learn them is well worth the effort.

6. Define Inclusive Containment

If containment is defined for a class, make it as inclusive as possible (domain, locality, country, OU, O). If it is restricted, consider the reasons for doing so. Inclusive containment provides flexibility for a number of different configurations and makes your classes more adaptable.

7. Select Appropriate Class Flags and Attribute Constraints

When creating classes and attributes, take care to select only the appropriate flags and constraints. Understand each flag and constraint and their performance implications. For example, if you specify a sync immediate constraint for an attribute that is continually updated, performance could be affected.

For classes, you need to determine:

  • If the object should be a container

  • If administrators should be able to remove this class from the schema

For attributes, you need to determine:

  • Who should be allowed to read and modify the information, and if an administrator should be allowed to remove this attribute from the schema

  • When the information needs to be synchronized

  • If the value should be limited to a specific type of data, such as a sized attribute with an upper and lower bound

By taking the time to consider each flag or constraint when you create a new class or attribute, you can create the most efficient schema possible.

8. Comment Each Class and Attribute

Your schema extensions should contain a comment about the purpose of each class or attribute. Add enough information that someone unfamiliar with your code could determine what each class and attribute does. This is especially important for attributes that store in application-defined format using octet strings.

When creating attributes, add a note in the comments telling what syntax the attribute uses. This will save anyone reading the code from looking up the OID to determine the syntax type. If another developer needs to maintain this schema at a future time, explaining the definition and usage can save a lot of time and trouble.

These comments sometimes prove especially handy. It might be a long time before you are asked to make additional changes to the schema.

9. Add Attributes as Needed

Make sure that all attributes are used by a class definition. Attributes that might be used in a future release should be added in that future release. Your plans may change, or you may find a better approach at a future time. Remember that it is much easier to add new schema when needed than to change or remove existing schema.

10. Maintain Compatibility

Avoid making changes to schema that is already in use. If you make modifications, you should create another version of your file and add the modifications in a separate section. This will ensure that your schema remains backward compatible.

Conclusion

By following the guidelines and recommendations in this AppNote, you should be able to create effective schema extensions and avoid many of the pitfalls that can occur when working with a highly scalable, distributed enterprise directory.

Here is a list of reference manuals, utilities, and programming interfaces for creating schema extensions.

  • LDAPZone - This Web site contains news, developer forums, and the latest LDAP-related information. See http://www.ldapzone.com.

  • NDS Schema Reference - This reference contains definitions for all of the base attributes, classes, and syntaxes, as well as conceptual information on the NDS schema. If you perform any work with the NDS schema, this manual is a must. It can be viewed online, or it can be downloaded in PDF format with any of the NDS APIs. See http://developer.novell.com/ndk/doc/ndslib/index.html?schm_enu/data/h4q1mn1i.html.

  • NDS Technical Overview - This reference provides overview and conceptual information on NDS. It can be viewed online, or it can be downloaded in PDF format with any of the NDS APIs. See http://developer.novell.com/ndk/doc/ndslib/index.html?dsov_enu/data/h6tvg4z7.html.

  • LDAP and NDS Integration Guide - This guide explains terminology differences between NDS and LDAP, and discusses NDS support for the LDAP schema. It can be viewed online, or it can be downloaded in PDF format with any of the NDS APIs. See http://developer.novell.com/ndk/doc/ldapover/index.html?ldap_enu/data/a3wyu4m.html.

  • Novell Import Convert Export Utility - Included with the LDAP Libraries for C, this utility makes it easy to create schema extensions. By using popular formats such as LDIF and delimited-data files, schema extensions can be made without programming. This utility is the recommended method to make schema updates. See http://developer.novell.com/ndk/cldap.htm.

  • ConsoleOne - The Schema Manager built into the ConsoleOne utility lets you manage and view your schema, and the LDAP Group Object can be used to view LDAP to NDS class and attribute mappings. See http://www.novell.com/download/#Management.

  • LDAP Programming Interfaces - Novell provides two multi-platform LDAP programming libraries which contain APIs to extend the schema. The LDAP Libraries for C is a full-featured C API for LDAP. (See http://developer.novell.com/ndk/cldap.htm; on the LDAP Libraries for C page, the complete download contains the C libraries, all of the manuals in the reference sections, an API-specific manual, and the Novell Import Convert Export utility.) The LDAP Class Libraries for Java is a full-featured Java API for LDAP. (See http://developer.novell.com/ndk/jldap.htm.)

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates