04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder<?xml version="1.0" encoding="UTF-8"?>

c208973c890b8f993297720fd0247bc7481d4304Christian Maeder<chapter xml:id='chap-schema'

55c5e901b5c3466300009135585bc70bd576dcb6Christian Maeder xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'

54ea981a0503c396c2923a1c06421c6235baf27fChristian Maeder xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

54ea981a0503c396c2923a1c06421c6235baf27fChristian Maeder xmlns:xlink='http://www.w3.org/1999/xlink'

54ea981a0503c396c2923a1c06421c6235baf27fChristian Maeder xmlns:xinclude='http://www.w3.org/2001/XInclude'>

697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder <title>Managing Schema</title>

54ea981a0503c396c2923a1c06421c6235baf27fChristian Maeder <indexterm><primary>Schema</primary></indexterm>

697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <para>Schema definitions describe the data, and especially the object classes

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken and attribute types that can be stored in the directory. By default OpenDJ

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken conforms strictly to LDAPv3 standards pertaining to schema definitions and

e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder attribute syntax checking, ensuring that data stored is valid and properly

afe76697dd6888856a066934a1112a38809b27faChristian Maeder formed. Unless your data use only standard schema present in OpenDJ when

58aa0caa9f05787b4bffc2e32d1494cc1766b8cfRazvan Pascanu you install, then you must add additional schema definitions to account

2c81e2bd9f9dee247c74a642c03620a2f799d0a4Razvan Pascanu the data your applications stored.</para>

a5c67efbd82e10368fda4e30d528157066d45c03Christian Maeder

a5c67efbd82e10368fda4e30d528157066d45c03Christian Maeder <para>Out of the box, OpenDJ comes with many standard schema definitions.

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder In addition you can update and extend schema definitions while OpenDJ

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder is online. As a result you can add new applications requiring additional

2c81e2bd9f9dee247c74a642c03620a2f799d0a4Razvan Pascanu data without stopping your directory service.</para>

04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder

a5c67efbd82e10368fda4e30d528157066d45c03Christian Maeder <para>This chapter demonstrates how to change and to extend OpenDJ schema.

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder This chapter also identifies the standard schema definitions available when

04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder you install OpenDJ.</para>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder

e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder <section xml:id="about-schema">

333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder <title>About Directory Schema</title>

2c81e2bd9f9dee247c74a642c03620a2f799d0a4Razvan Pascanu

d5aadb569823a9d41ef761433f27dd00d7e4e147Christian Maeder <para>Directory schema, described in <link

da955132262baab309a50fdffe228c9efe68251dCui Jian xlink:href='http://tools.ietf.org/html/rfc4512'>RFC 4512</link>, defines

c458c6f5a2ce173d8af7a7f5cb434813eb870937Jorina Freya Gerken the kinds of information you find in the directory, and can define how

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder the information are related. This chapter focuses primarily on two types

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder of directory schema definitions.</para>

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <itemizedlist>

fd4856f5eeac6f144f6116002233e5ce4cc8f41bJorina Freya Gerken <listitem>

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <para><firstterm>Attribute type</firstterm> definitions describe attributes

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder of directory entries, such as <literal>givenName</literal> or

7ec5cb48d588cc641d27fb2dbeccb6c28856c8daChristian Maeder <literal>mail</literal>.</para>

7ec5cb48d588cc641d27fb2dbeccb6c28856c8daChristian Maeder <para>Here is an example of an attribute type definition.</para>

c458c6f5a2ce173d8af7a7f5cb434813eb870937Jorina Freya Gerken <programlisting language="ldif"># Attribute type definition

fd4856f5eeac6f144f6116002233e5ce4cc8f41bJorina Freya GerkenattributeTypes: ( 0.9.2342.19200300.100.1.3 NAME ( 'mail' 'rfc822Mailbox' )

e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder EQUALITY caseIgnoreIA5Match SUBSTR caseIgnoreIA5SubstringsMatch

e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{256} X-ORIGIN 'RFC 4524' )</programlisting>

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder <para>Attribute type definitions start with an object identifier (OID),

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder and generally a short name or names that are easier to remember than the

d11391a2447a2005329a95b5d770f24e62bf5b63Christian Maeder OID. The attribute type definition can specify how attribute values

d11391a2447a2005329a95b5d770f24e62bf5b63Christian Maeder should be collated for sorting, and what syntax they use. The X-ORIGIN

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder is an extension to identify where the definition originated. When you

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder define your own schema, you likely want to provide an X-ORIGIN to help

d11391a2447a2005329a95b5d770f24e62bf5b63Christian Maeder you to track versions of definitions, and where the definitions came

d11391a2447a2005329a95b5d770f24e62bf5b63Christian Maeder from.</para>

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder </listitem>

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <listitem>

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder <para><firstterm>Object class</firstterm> definitions identify the

c458c6f5a2ce173d8af7a7f5cb434813eb870937Jorina Freya Gerken attribute types that an entry must have, and may have. Examples of

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder object classes include <literal>person</literal> and

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <literal>organizationalUnit</literal>.</para>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <para>Here is an example of an object class definition.</para>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <programlisting language="ldif"># Object class definition

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian MaederobjectClasses: ( 2.5.6.6 NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn )

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder MAY ( userPassword $ telephoneNumber $ seeAlso $ description )

afe76697dd6888856a066934a1112a38809b27faChristian Maeder X-ORIGIN 'RFC 4519' )</programlisting>

ce3e8067c8e5c5ffe7e76d75ead46e2b67adcafcChristian Maeder <para>Entries all have an attribute identifying their object classes,

ce3e8067c8e5c5ffe7e76d75ead46e2b67adcafcChristian Maeder called <literal>objectClass</literal>.</para>

ce3e8067c8e5c5ffe7e76d75ead46e2b67adcafcChristian Maeder <para>Object class definitions start with an object identifier (OID), and

ce3e8067c8e5c5ffe7e76d75ead46e2b67adcafcChristian Maeder generally a short name that is easier to remember than the OID. The

ce3e8067c8e5c5ffe7e76d75ead46e2b67adcafcChristian Maeder definition here says that the person object class inherits from the top

fd4856f5eeac6f144f6116002233e5ce4cc8f41bJorina Freya Gerken object class, which is the top-level parent of all object classes. When

afe76697dd6888856a066934a1112a38809b27faChristian Maeder you view the objectclass attribute values on an entry, you see the list

fb88eac77c89b668f5c306173a6fbe2d513e4bccMarkus Gross of object classes that the entry takes. An entry can have one STRUCTURAL

fb88eac77c89b668f5c306173a6fbe2d513e4bccMarkus Gross object class inheritance branch, such as <literal>top</literal> -

ce3e8067c8e5c5ffe7e76d75ead46e2b67adcafcChristian Maeder <literal>person</literal> - <literal>organizationalPerson</literal> -

ce3e8067c8e5c5ffe7e76d75ead46e2b67adcafcChristian Maeder <literal>inetOrgPerson</literal>. Yet entries can have multiple

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder AUXILIARY object classes. The object class then defines the attribute

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder types that must be included, and the attribute types that may be included

fd4856f5eeac6f144f6116002233e5ce4cc8f41bJorina Freya Gerken on entries having the object class.</para>

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder </listitem>

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <listitem>

fd4856f5eeac6f144f6116002233e5ce4cc8f41bJorina Freya Gerken <para>An <firstterm>attribute syntax</firstterm> constrains what directory

ce3e8067c8e5c5ffe7e76d75ead46e2b67adcafcChristian Maeder clients can store as attribute values.</para>

e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <para>An attribute syntax is identified in an attribute type definition by

afe76697dd6888856a066934a1112a38809b27faChristian Maeder its OID. String-based syntax OIDs are optionally followed by a number, set

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder between braces, that represents a minimum upper bound on the number of

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder characters in the attribute value. For example, in the attribute type

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder definition shown above, the syntax is

2c81e2bd9f9dee247c74a642c03620a2f799d0a4Razvan Pascanu <literal>1.3.6.1.4.1.1466.115.121.1.26{256}</literal>. The syntax is an

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder IA5 string (composed of characters from the international version of the

04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder ASCII character set) that can contain at least 256 characters.</para>

04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <para>You can find a table matching attribute syntax OIDs with their

e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder human-readable names in RFC 4517, <link xlink:show="new"

04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder xlink:href="http://tools.ietf.org/html/rfc4517#appendix-A">Appendix A.

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken Summary of Syntax Object Identifiers</link>. The RFC describes

d5aadb569823a9d41ef761433f27dd00d7e4e147Christian Maeder attribute syntaxes in detail. Alternatively, you can see the attribute

58aa0caa9f05787b4bffc2e32d1494cc1766b8cfRazvan Pascanu syntaxes that OpenDJ supports by opening the OpenDJ Control Panel and

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken browsing to Schema &gt; Manage Schema &gt; Attribute Syntaxes. You can

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder also list them by using the <command>dsconfig</command> command.</para>

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <para>Although attribute syntaxes are often specified in attribute type

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken definitions, directory servers do not always check that attribute values

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder comply with attribute syntaxes. OpenDJ directory server does tend to

afe76697dd6888856a066934a1112a38809b27faChristian Maeder enforce compliance by default, in particular for certificates, country

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder strings, directory strings, JPEG photos, and telephone numbers. The aim

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder is to avoid accumulating garbage in your directory data.</para>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <para>If you are trying unsuccessfully to import non-compliant data from a

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder more lenient directory server, you can either clean the data before

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder importing it, or if cleaning the data is not an option, read <xref

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder linkend="schema-legacy-support" />.</para>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder

04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder <para>When creating your own attribute type definitions, use existing

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder attribute syntaxes where possible. If you must create your own attribute

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder syntax, then consider the extensions in

07eb349813c50aff304df13337b5cbc42f48c0a5Jorina Freya Gerken <xref linkend="attr-syntax-schema-definition-extensions" />.</para>

f45fad43ee1673ab280fbc700821d5d20a493eaaChristian Maeder </listitem>

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken <listitem>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <para>Matching rules determine how the directory server compares attribute

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken values to assertion values for LDAP search and LDAP compare

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder operations.</para>

04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <para>For example, suppose you search with the filter

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken <literal>(uid=bjensen)</literal>. The assertion value in this case is

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder <literal>bjensen</literal>.</para>

04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder

04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder <para>OpenDJ has the following schema definition for the user ID

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder attribute.</para>

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken <programlisting language="ldif"

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken >attributeTypes: ( 0.9.2342.19200300.100.1.1 NAME ( 'uid' 'userid' )

c458c6f5a2ce173d8af7a7f5cb434813eb870937Jorina Freya Gerken EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} X-ORIGIN 'RFC 4519' )</programlisting>

9192fdd8f0e682ac0f0183dd854d5210fbfa4ec5Christian Maeder

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder <para>When finding an equality match for your search, OpenDJ uses the

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder <literal>caseIgnoreMatch</literal> matching rule to check for user ID

9192fdd8f0e682ac0f0183dd854d5210fbfa4ec5Christian Maeder attribute values that equal <literal>bjensen</literal> without regard

9192fdd8f0e682ac0f0183dd854d5210fbfa4ec5Christian Maeder to case.</para>

9192fdd8f0e682ac0f0183dd854d5210fbfa4ec5Christian Maeder

0cbb0121c81f5307eeefe7ffbeeac79ff6c5cdf2Jorina Freya Gerken <para>You can see the matching rules that OpenDJ supports by opening the

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder OpenDJ Control Panel and browsing to Schema &gt; Manage Schema &gt;

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder Matching Rules. Notice that many matching rules support string collation

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder in languages other than English. You can also list matching rules by

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder using the <command>dsconfig</command> command.</para>

07eb349813c50aff304df13337b5cbc42f48c0a5Jorina Freya Gerken

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <para>As you can read in examples like, <link

07eb349813c50aff304df13337b5cbc42f48c0a5Jorina Freya Gerken xlink:href="admin-guide#extensible-match-search"

07eb349813c50aff304df13337b5cbc42f48c0a5Jorina Freya Gerken xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Search: List

07eb349813c50aff304df13337b5cbc42f48c0a5Jorina Freya Gerken Active Accounts</citetitle></link>, OpenDJ matching rules enable

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder directory clients to do more interesting searches than simply comparing

e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder strings. That example shows how to search for users who have

authenticated in the last three months.</para>

</listitem>

</itemizedlist>

<para>OpenDJ exposes schema over protocol through the

<literal>cn=schema</literal> entry. OpenDJ stores the schema definitions

corresponding to the entry in LDIF under the

<filename>config/schema/</filename> directory. Many standard definitions

and definitions pertaining to the server configuration are included at

installation time.</para>

</section>

<section xml:id="update-schema">

<title>Updating Directory Schema</title>

<indexterm>

<primary>Replication</primary>

<secondary>Schema definitions</secondary>

</indexterm>

<para>OpenDJ directory server is designed to permit updating the list of

directory schema definitions while the server is running. As a result you can

add support for new applications that require new attributes or new kinds

of entries without interrupting the directory service. OpenDJ also replicates

schema definitions, so the schema you add on one replica is propagated to

other replicas without you having to intervene manually.</para>

<para>As it is easy to introduce typos into schema definitions, the

best way to start defining your own schema is with the OpenDJ Control

Panel. Open the Control Panel &gt; Schema &gt; Manage Schema window to

get started creating your custom object classes and attribute types.</para>

<mediaobject xml:id="figure-manage-schema">

<imageobject>

<imagedata fileref="images/Manage-Schema.png" format="PNG" />

</imageobject>

</mediaobject>

<para>As object classes reference attribute types, you first create

custom attribute types, and then create the object class that references

the attribute types.</para>

<para>Create a custom attribute type through the New Attribute window.</para>

<mediaobject xml:id="figure-custom-attrtype">

<imageobject>

<imagedata fileref="images/custom-attrtype.png" format="PNG" />

</imageobject>

</mediaobject>

<para>Using the New Object Class window, create an auxiliary object class

that allows your new custom attribute type. You set the type to Auxiliary

under Extra Options.</para>

<mediaobject xml:id="figure-custom-objclass">

<imageobject>

<imagedata fileref="images/custom-objclass.png" format="PNG" />

</imageobject>

</mediaobject>

<para>When you finish, the schema changes show up by default in the file

<filename>config/schema/99-user.ldif</filename>. Notice that the file name

starts with a number, 99. This number is larger than the numbers prefixing

other schema file names. In fact, OpenDJ reads the schema files in sorted

order, reading schema definitions as they occur. If OpenDJ reads a schema

definition for an object class before it has read the definitions of the

attribute types mentioned in the object class definition, then it displays

an error. Therefore, when naming your schema file, make sure the name appears

in the sorted list of file names <emphasis>after</emphasis> all the schema

files containing definitions that your schema definitions depends on. The

default file name for your schema, <filename>99-user.ldif</filename>, ensures

that your definitions load only after all of the schema files installed by

default.</para>

<para>You can create this file in the lab using the Control Panel, and then

apply the definitions in production by adapting the content for use with the

<command>ldapmodify</command> command, for example.</para>

<screen>$ cat config/schema/99-user.ldif

dn: cn=schema

objectClass: top

objectClass: ldapSubentry

objectClass: subschema

cn: schema

attributeTypes: ( temporary-fake-attr-id NAME 'myCustomAttribute' EQUALITY case

IgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstrings

Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications )

objectClasses: ( temporary-fake-oc-id NAME 'myCustomObjClass

' SUP top AUXILIARY MAY myCustomAttribute )

modifiersName: cn=Directory Manager,cn=Root DNs,cn=config

modifyTimestamp: 20110620095948Z

</screen>

<para>To test your schema definition, add the object class and attribute

to an entry.</para>

<screen>$ cat custom-attr.ldif

dn: uid=bjensen,ou=People,dc=example,dc=com

changetype: modify

add: objectClass

objectClass: myCustomObjClass

-

add: myCustomAttribute

myCustomAttribute: Testing 1, 2, 3...

$ ldapmodify

--port 1389

--bindDN "cn=Directory Manager"

--bindPassword password

--filename custom-attr.ldif

Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com

MODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com

$ ldapsearch

--port 1389

--baseDN dc=example,dc=com

uid=bjensen

myCustomAttribute

dn: uid=bjensen,ou=People,dc=example,dc=com

myCustomAttribute: Testing 1, 2, 3...

</screen>

<para>In addition to supporting the standard schema definitions that are

described in <link xlink:href="http://tools.ietf.org/html/rfc4512#section-4.1"

>RFC 4512, section 4.1</link>, OpenDJ also supports the following extensions

that you can use when adding your own definitions.</para>

<variablelist xml:id="general-schema-definition-extensions">

<title>Extensions for All Schema Definitions</title>

<indexterm>

<primary>Schema</primary>

<secondary>Schema definition extensions</secondary>

</indexterm>

<varlistentry>

<term><literal>X-ORIGIN</literal></term>

<listitem>

<para>Used to specify the origin of a schema element. Examples include

<literal>X-ORIGIN 'RFC 4519'</literal>, <literal>X-ORIGIN

'draft-ietf-ldup-subentry'</literal>, and <literal>X-ORIGIN

'OpenDJ Directory Server'</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><literal>X-SCHEMA-FILE</literal></term>

<listitem>

<para>Used to specify the relative path to the schema file containing the

schema element such as <literal>X-SCHEMA-FILE '00-core.ldif'</literal>.

Schema definitions are located by default in

<filename>/path/to/opendj/config/schema/*.ldif</filename> files.</para>

</listitem>

</varlistentry>

</variablelist>

<variablelist xml:id="attr-syntax-schema-definition-extensions">

<title>Extensions for Attribute Syntax Descriptions</title>

<indexterm>

<primary>Schema</primary>

<secondary>Schema definition extensions</secondary>

</indexterm>

<varlistentry>

<term><literal>X-ENUM</literal></term>

<listitem>

<para>Used to define a syntax that is an enumeration of values. The

following attribute syntax description defines a syntax allowing four

possible attribute values for example.</para>

<programlisting language="ldif"

>ldapSyntaxes: ( security-label-syntax-oid DESC 'Security Label'

X-ENUM ( 'top-secret' 'secret' 'confidential' 'unclassified' ) )</programlisting>

</listitem>

</varlistentry>

<varlistentry>

<term><literal>X-PATTERN</literal></term>

<listitem>

<para>Used to define a syntax based on a regular expression pattern, where

valid regular expressions are those defined for <link xlink:show="new"

xlink:href="http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html"

><literal>java.util.regex.Pattern</literal></link>. The following attribute

syntax description defines a simple, lenient SIP phone URI syntax

check.</para>

<programlisting language="ldif"

>ldapSyntaxes: ( simple-sip-uri-syntax-oid DESC 'Lenient SIP URI Syntax'

X-PATTERN '^sip:[a-zA-Z0-9.]+@[a-zA-Z0-9.]+(:[0-9]+)?$' )</programlisting>

</listitem>

</varlistentry>

<varlistentry>

<term><literal>X-SUBST</literal></term>

<listitem>

<para>Used as a fallback to substitute a defined syntax for one that

OpenDJ does not implement. The following example substitutes Directory

String syntax, which has OID 1.3.6.1.4.1.1466.115.121.1.15, for a syntax

that OpenDJ does not implement.</para>

<programlisting language="ldif"

>ldapSyntaxes: ( non-implemented-syntax-oid DESC 'Not Implemented in OpenDJ'

X-SUBST '1.3.6.1.4.1.1466.115.121.1.15' )</programlisting>

</listitem>

</varlistentry>

</variablelist>

<variablelist xml:id="attr-type-schema-definition-extensions">

<title>Extension for Attribute Type Descriptions</title>

<indexterm>

<primary>Schema</primary>

<secondary>Schema definition extensions</secondary>

</indexterm>

<varlistentry>

<term><literal>X-APPROX</literal></term>

<listitem>

<para><literal>X-APPROX</literal> is used to specify the approximate

matching rule to use for a given attribute type when not using the default,

which is the <link xlink:href="http://aspell.net/metaphone/"

xlink:show="new">double metaphone approximate match</link>.</para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="schema-legacy-support">

<title>Relaxing Schema Checking to Import Legacy Data</title>

<indexterm>

<primary>Schema</primary>

<secondary>Legacy data</secondary>

</indexterm>

<para>By default, OpenDJ accepts data that follows the standards in terms of

what is allowed and what is rejected. You might have legacy data from a

directory service that is more lenient, allowing non-standard constructions

such as multiple structural object classes per entry, not checking attribute

value syntax, or even not respecting schema definitions.</para>

<para>For example, when importing data with multiple structural object

classes defined per entry, you can relax schema checking to warn rather

than reject entries having this issue.</para>

<screen>$ dsconfig

set-global-configuration-prop

--hostname opendj.example.com

--port 4444

--bindDN "cn=Directory Manager"

--bindPassword password

--set single-structural-objectclass-behavior:warn

--trustAll

--no-prompt</screen>

<para>You can allow attribute values that do not respect the defined syntax

with the <command>dsconfig</command> command as well.</para>

<screen>$ dsconfig

set-global-configuration-prop

--hostname opendj.example.com

--port 4444

--bindDN "cn=Directory Manager"

--bindPassword password

--set invalid-attribute-syntax-behavior:warn

--trustAll

--no-prompt</screen>

<para>You can even turn off schema checking altogether, although turning

off schema checking only really makes sense when you are absolutely sure

that the entries and attribute values respect the schema definitions, and

you simply want to turn off schema checking temporarily to speed up import

processing.</para>

<screen>$ dsconfig

set-global-configuration-prop

--hostname opendj.example.com

--port 4444

--bindDN "cn=Directory Manager"

--bindPassword password

--set check-schema:false

--trustAll

--no-prompt</screen>

</section>

<section xml:id="standard-schema">

<title>Standard Schema Included With OpenDJ</title>

<indexterm>

<primary>Schema</primary>

<secondary>Bundled definitions</secondary>

</indexterm>

<para>The following files under <filename>config/schema/</filename>

contain schema definitions out of the box.</para>

<variablelist>

<varlistentry>

<term>

<filename>00-core.ldif</filename>

</term>

<listitem>

<para>This file contains a core set of attribute type and objectlass

definitions from several standard LDAP documents, including

draft-ietf-boreham-numsubordinates, draft-findlay-ldap-groupofentries,

draft-furuseth-ldap-untypedobject, draft-good-ldap-changelog,

draft-ietf-ldup-subentry, draft-wahl-ldap-adminaddr, RFC 1274, RFC 2079,

RFC 2256, RFC 2798, RFC 3045, RFC 3296, RFC 3671, RFC 3672, RFC 4512,

RFC 4519, RFC 4523, RFC 4524, RFC 4530, RFC 5020, and X.501.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>01-pwpolicy.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions from

draft-behera-ldap-password-policy, which defines a mechanism for storing

password policy information in an LDAP directory server.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>02-config.ldif</filename>

</term>

<listitem>

<para>This file contains the attribute type and objectclass definitions

for use with the directory server configuration.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>03-changelog.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions from

draft-good-ldap-changelog, which defines a mechanism for storing

information about changes to directory server data.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>03-rfc2713.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions from RFC 2713, which defines a

mechanism for storing serialized Java objects in the directory

server.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>03-rfc2714.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions from RFC 2714, which defines a

mechanism for storing CORBA objects in the directory server.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>03-rfc2739.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions from RFC 2739, which defines a

mechanism for storing calendar and vCard objects in the directory server.

Note that the definition in RFC 2739 contains a number of errors, and this

schema file has been altered from the standard definition in order to fix

a number of those problems.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>03-rfc2926.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions from RFC 2926, which defines a

mechanism for mapping between Service Location Protocol (SLP)

advertisements and LDAP.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>03-rfc3112.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions from RFC 3112, which defines

the authentication password schema.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>03-rfc3712.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions from RFC 3712, which defines a

mechanism for storing printer information in the directory server.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>03-uddiv3.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions from RFC 4403,

which defines a mechanism for storing UDDIv3 information in the directory

server.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>04-rfc2307bis.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions from the

draft-howard-rfc2307bis specification, used to store naming service

information in the directory server.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>05-rfc4876.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions from RFC 4876, which defines

a schema for storing Directory User Agent (DUA) profiles and preferences

in the directory server.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>05-samba.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions required when storing Samba

user accounts in the directory server.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>05-solaris.ldif</filename>

</term>

<listitem>

<para>This file contains schema definitions required for Solaris and

OpenSolaris LDAP naming services.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<filename>06-compat.ldif</filename>

</term>

<listitem>

<para>This file contains the attribute type and objectclass definitions

for use with the directory server configuration.</para>

</listitem>

</varlistentry>

</variablelist>

</section>

</chapter>