How to Read the NDS Schema Reference Document: The Object Class Definition Page
Articles and Tips: article
Senior Editor
DeveloperNet University
nmclain@novell.com
01 Feb 2001
Takes a look at how to read the Novell Directory Services schema document.
As you work with NDS objects and attributes, you'll find referring to the schema reference document useful. You'll find this document beneficial whether:
You're setting up an NDS tree and must know what attributes certain objects have, as well as which of these objects are mandatory or which are optional.
You're extending the NDS schema and need to know which objects that already exist can meet your needs, or which object you can base your new object on.
You're querying for objects with specific attributes.
You're a developer and must know such information as an object's class flags and mandatory attributes, or an attribute's syntax.
The schema defines the rules for behavior, placement and matching for all the NDS objects and attributes. The NDS schema reference documents these definitions and rules. It contains all the information about NDS objects and attributes. For instance, information you can find in the schema reference include which objects are containers, the type of container each object can be held by, and the attribute that names them. You can freely download this reference from http://developer.novell.com.
This article describes how to read an object class definition page from within the NDS schema reference document. Next month's column will describe how to read an attribute definition page.
As a place to begin, the first chapter in the schema reference discusses general schema concepts and describes the schema structure. The rest of the schema reference defines the actual classes, attributes and syntaxes in the schema. The second and third chapters of the schema reference discuss operational and base object classes.
Reading Object Class Definitions
The schema reference refers to either classes or object classes instead of objects. That's because classes are the definition for objects. You create an object from an object class (or class). In other words, objects actually represent a specific physical resource in your network. NDS created these objects from object classes defined in the schema.
Chapters two and three are organized similarly because they both discuss classes. The Operational Object Class Definitions chapter lists the operational object classes in alphabetic order and documents their definitions. Operational object classes are those classes that make up the actual schema. Any classes other than those described in this chapter actually extend the schema. The "Base Object Class Definitions" chapter lists and defines the base object classes in alphabetic order. Base object classes are those classes that extend the operational schema in a default installation.
Both operational and base class objects have identical page layouts. Figures 1, 2, and 3 show the Country operational object class page. This is a typical object class definition page that we can examine to find out what information the object class definitions contain.
Country Operational Object Class Definition, Page 1
Country Operational Object Class Class Definition, Page 2
Country Operational Object Class Definition, Page 3
Using Effective and Noneffective Class Declarations
In Figure 1, you can see that the class name (Country) is followed by a brief description of the class's purpose. The information immediately below the description tells you whether the class is effective or noneffective. You can use an effective class to define an object. You can't use a noneffective class to define an object. In other words, because the Country object class is effective, you can use it to create Country objects.
However, other object classes in the schema, such as the Device object class, are non-effective. That means you can't define a Device object. You can use the Device object class to define another class, such as a Fax object class. Because of where the Fax object class is defined, it would inherit the Device object class's attributes. You could then add any necessary attributes to the Fax object class. If you declared your Fax object class as effective, you could then use it to create Fax objects.
You can think of non-effective classes as holding the attributes and other properties you want a more specific class to inherit. This is one of the ways you can make the NDS directory conform more directly to your company's needs.
LDAP Name
The next piece of information on the object class definition page is the LDAP name. If the object class has the same definition and purpose as any LDAP object class, you can find the names of the LDAP object classes here. Some object classes in the NDS schema have no corresponding LDAP object classes, while other object classes, such as Group, have more than one corresponding LDAP object class. These are the LDAP object class names to which the NDS object class name is mapped.
ASN.1 ID
The next piece of information on the page shown in Figure 1 is the ASN.1 ID (Abstract Syntax Notation One Identification). Every object class and attribute in the NDS schema has an ASN.1 ID assigned to it. An ASN.1 ID is an identification assigned to object classes and attributes when they are registered. Companies that develop NDS or LDAP applications can be assigned a unique ASN.1 ID which they can use to allocate their own ASN.1 ID numbers.
Novell strongly recommends that you register your schema extensions before you release a product that extends the NDS schema. All schema object and attribute class definitions must be unique to the NDS tree. If you don't register your schema extension, your product could encounter a name collision during its installation. Novell maintains an NDS schema registry to avoid these collisions.
To register your schema extension, call Developer Support at 800-REDWORD (800-733-9673), or at the international number, 801-429-5588. You can also register at the Novell Developer Support Web site: http://www.developer.novell.com/support/schreg2c.htm.
When you register, you receive a unique prefix that you prepend to the names of your new attribute and class definitions. You also receive two ASN.1 identifiers: one for object classes and one for attribute definitions. You can expand these to include as many unique IDs as you need for object classes and attributes.
Starting with NetWare 5, all object classes and attributes must have ASN.1 IDs in order to pass Novell certification. ASN.1 IDs serve as a common syntax for transferring information between two systems.
Once you've registered your schema extension, it becomes available for other people to use. So, if you must modify your schema extension, be careful before you remove or redefine any of its attribute meanings because other developers might be using your extensions. Remember that anyone can:
Extend it with new attributes
Create an auxiliary class to add to your current object class
Create a new extension
This way, you won't create problems for other developers who have used your extension.
Class Flags
The next piece of information on the Country class object definition page that is shown in Figure 1 is the Class Flags and their settings. Class flags define allowable class operations. When you extend the schema, you can set the following flags on object class definitions. The object class definition page lists the flags that are turned on for the object class. If the flag isn't listed, you can assume that the flag is turned off for that object class.
|
Flag
|
Description
|
|
Container Flag |
Indicates whether the object can contain other objects. Turn the flag ON for those object classes that are designated as container classes. Leave the flag OFF for leaf object classes. |
|
Effective Flag |
Indicates whether an object class is effective or noneffective. Turn the flag ON for effective classes, or those classes that can be used both to provide definition and to create objects. Leave the flag OFF for classes which provide definition but cannot be used to create objects. |
|
Auxiliary Flag |
Indicates whether an object class is an auxiliary class. When this flag is turned on, NDS ignores the container and effective class flags. Turn the flag ON for auxiliary classes. This flag is new in NDS 8. |
|
Non-removable Flag |
Indicates whether the object class can be removed from the schema. Turn the flag ON for objects that can't be removed. Leave the flag OFF for object classes that can be remove. All operational schema object classes are flagged nonremovable. Object classes added to extend the schema are the only classes that can have the nonremovable flag turned OFF. In NDS 8, you can turn this flag ON. In previous NDS versions, this flag was reserved for NDS. |
NDS controls the rest of the object class flags. These flags are:
|
Flag
|
Description
|
|
Ambiguous Container Flag |
Indicates whether the object class has clearly defined containment classes. As a general rule, noneffective classes can be created with ambiguous containment, but effective classes must have nonambiguous containment. (Ambiguous containment occurs when an object inherits non-identical containment classes from different super classes.)Only in special cases can effective classes be created with ambiguous containment. The Alias class object is one of these special cases since it needs to inherit the containment classes of its reference object class. For most object classes in the operational schema, the Ambiguous Container flag is turned Off. It is turned On for object classes Top, Alias, and Partition. |
|
Ambiguous Naming Flag |
Indicates whether the object class has clearly defined naming attributes. As a general rule, noneffective classes can be created with ambiguous naming, but effective classes must have nonambiguous naming attributes. Ambiguous naming occurs when an object inherits non-identical naming attributes from different super classes. Only in special cases can effective classes be created with ambiguous naming. The Alias class object is one of these special cases since it needs to inherit the naming attributes of its reference object class. For most object classes in the operational schema, the Ambiguous Naming flag is turned Off. The only object classes where this flag is turned On are Top, Alias, and Partition. |
|
Operational Flag |
Indicates that NDS requires this object class to exist. This flag is turned ON for object classes that NDS must have in order to operate correctly. |
Class Structure
The next table on an object class definition page is labeled "Class Structure", and it contains three pieces of information:
Super Classes
Containment
Named By
In the example pages, this table spans across Figures 1 and 2.
Super Classes
The object class inherits information from the object classes listed in this section. All object classes must have one or more super classes, except for the Top object class. The Top object class is at the top of the schema hierarchy, and all other object classes inherit from it. In other words, the Top object class is a super class to all classes. On the class definition pages, super classes are listed in a hierarchical manner, with the super class at the bottom of the list being the immediate super class from which the current class inherits.
In Figure 1, we can see that the Country object class inherits only from the Top object class. However, other object classes, such as Directory Map, inherit from more than one super class. Directory Map inherits from both the Top and the Resource super classes. An object class can only inherit from other object classes in its hierarchy. It can't inherit from an object class that is not in its hierarchy.
For example, an object class such as Directory Map is created from the Resource class, which is created from the Top object class. So, it inherits from those classes. The Directory Map object can't inherit from the Computer object class because the Computer object class has no place in the hierarchy from which Directory Map is created.
Containment
Objects of the class can be created only as subordinates in the NDS tree to objects of the classes listed here. An object of the class cannot be subordinate to any object of a class that is not listed here. For example, a Country object can be contained by a domain, Top, or Tree Root container object. It can't be contained by a Locality container object. Locality isn't in its Containment list.
Named By
The partial name or Relative Distinguished Name (RDN) of objects of the class consists of at least one of the attributes listed here. These attributes can be either mandatory or optional attributes, but at least one must be given a value when creating an object of the class. If the only Named By attribute is optional, it is in effect mandatory.
Attributes listed in this section will also be listed in the Mandatory Attributes and Optional Attributes sections. For example, a Country object is named by a "C" (Country Name) attribute, which is a mandatory attribute.
This is the name which NDS can use to locate the object.
Mandatory and Optional Attributes
Figure 2 shows the next pieces of information on the Country Object Class Definition page. This information is the mandatory and optional attributes.
Object classes have attributes associated with them. These attributes hold information that defines the object. If a class has been derived from an existing class, that class inherits a set of mandatory and optional attributes. Mandatory attributes must have values assigned to them when the object is created. Optional attributes don't require a value. They can also have values assigned to them later.
If these two lists don't include an attribute you want your object to include, you can extend the schema by creating a new object class that holds the additional attribute. If the schema doesn't include the attribute you need, you can also extend the schema by creating the new attribute.
Default ACL Template
Figure 3 shows the next piece of information: the default ACL Template. All object classes inherit a default ACL template from the Top object class. This ACL template provides a minimum amount of security. It gives all objects the rights to supervise any objects they create. This ensures that every object added to the NDS tree has a supervisor.
The default ACL template holds information about which trustees have access to the object itself (entry rights) and which trustees have access to the attributes for the object. This information is stored in sets of information containing the trustee name, privileges, and the affected attribute (entry, all attributes, or a specific attribute). For example, the default template for the Country object class is that the creator of an object has the supervisor right on [Entry Rights].
Some object classes define a default set of values for their ACL. Objects also inherit default ACL values from their super classes. Therefore, every object class inherits a default ACL template from the Top object class.
When an object is created, its ACL contains the values that are in the default ACL template for that object. There are two cases where the ACL values are different:
Your code overrides the default values.
The creator of the object has effective rights comparable to those in the default template. In this case, the rights are not granted explicitly.
In addition to the default ACL template they inherit from Top, object classes inherit any default ACL templates that are defined for any of their super classes. The Country object class inherits only the Top object class's default ACL template, because the Country object class was created directly from Top. Other object classes, such as the NCP Server object inherit more than one default ACL template. The NCP Server object class inherits a default ACL template from Top and Server, and then defines one for itself.
Remarks
The last piece of information on an object class definition page is the Remarks section. This sections gives more detail about how to use the class and objects created from the class.
Conclusion
The schema reference document is an extremely valuable document, whether you're a network administrator, engineer, or developer. This document describes every operational and base object class in the schema. It includes information such as:
LDAP Name
ASN.1 ID
Class Flags
Class Structure
Mandatory Attributes
Optional Attributes
Default ACL Template
The schema reference document is available with a basic, free, subscription to DeveloperNet. You can choose to download or view the document at http://developer.novell.com/ndk.
* 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.