CR-1346 Fix for OPENDJ-641: Describe attribute syntaxes & matching rules

Mark Craig

01.45.2013 59ccf269fa256fe649e9474ba64509d7b3e8aaa4

CR-1346 Fix for OPENDJ-641: Describe attribute syntaxes & matching rules

 opendj3/src/main/docbkx/admin-guide/chap-schema.xml

@@ -20,7 +20,7 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2012 ForgeRock AS
  !      Copyright 2011-2013 ForgeRock AS
  !    
-->
<chapter xml:id='chap-schema'
@@ -102,6 +102,82 @@
    types that must be included, and the attribute types that may be included
    on entries having the object class.</para>
   </listitem>

   <listitem>
    <para>An <firstterm>attribute syntax</firstterm> constrains what directory
    clients can store as attribute values.</para>

    <para>An attribute syntax is identified in an attribute type definitions by
    its OID. String-based syntax OIDs are optionally followed by a number, set
    between braces, that represents a minimum upper bound on the number of
    characters in the attribute value. For example, in the attribute type
    definition shown above, the syntax is
    <literal>1.3.6.1.4.1.1466.115.121.1.26{256}</literal>. The syntax is an
    IA5 string (composed of characters from the international version of the
    ASCII character set) that can be up to a maximum of at least 256
    characters long.</para>

    <para>You can find a table matching attribute syntax OIDs with their
    human-readable names in RFC 4517, <link xlink:show="new"
    xlink:href="http://tools.ietf.org/html/rfc4517#appendix-A">Appendix A.
    Summary of Syntax Object Identifiers</link>. The RFC describes
    attribute syntaxes in detail. Alternatively, you can see the attribute
    syntaxes that OpenDJ supports by opening the OpenDJ Control Panel and
    browsing to Schema &gt; Manage Schema &gt; Attribute Syntaxes. You can
    also list them by using the <command>dsconfig</command> command.</para>

    <para>Although attribute syntaxes are often specified in attribute type
    definitions, directory servers do not always check that attribute values
    comply with attribute syntaxes. OpenDJ directory server does tend to
    enforce compliance by default, in particular for certificates, country
    strings, directory strings, JPEG photos, and telephone numbers. The aim
    is to avoid accumulating garbage in your directory data.</para>

    <para>If you are trying unsuccessfully to import non-compliant data from a
    more lenient directory server, you can either clean the data before
    importing it, or if cleaning the data is not an option, read <xref
    linkend="schema-legacy-support" />.</para>

    <para>When creating your own attribute type definitions, use existing
    attribute syntaxes where possible.</para>
   </listitem>

   <listitem>
    <para>Matching rules determine how the directory server compares attribute
    values to assertion values for LDAP search and LDAP compare
    operations.</para>

    <para>For example, suppose you search with the filter
    <literal>(uid=bjensen)</literal>. The assertion value in this case is
    <literal>bjensen</literal>.</para>

    <para>OpenDJ has the following schema definition for the user ID
    attribute.</para>

    <programlisting language="ldif"
    >attributeTypes: ( 0.9.2342.19200300.100.1.1 NAME ( 'uid' 'userid' )
 EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} X-ORIGIN 'RFC 4519' )</programlisting>

    <para>When finding an equality match for your search, OpenDJ uses the
    <literal>caseIgnoreMatch</literal> matching rule to check for user ID
    attribute values that equal <literal>bjensen</literal> without regard
    to case.</para>

    <para>You can see the matching rules that OpenDJ supports by opening the
    OpenDJ Control Panel and browsing to Schema &gt; Manage Schema &gt;
    Matching Rules. Notice that many matching rules support string collation
    in languages other than English. You can also list matching rules by
    using the <command>dsconfig</command> command.</para>

    <para>As you can read in examples like, <link
    xlink:href="admin-guide#extensible-match-search"
    xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Search: List
    Active Accounts</citetitle></link>, OpenDJ matching rules enable
    directory clients to do more interesting searches than simply comparing
    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