From 59ccf269fa256fe649e9474ba64509d7b3e8aaa4 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Fri, 01 Mar 2013 08:45:23 +0000
Subject: [PATCH] CR-1346 Fix for OPENDJ-641: Describe attribute syntaxes & matching rules

---
 opendj3/src/main/docbkx/admin-guide/chap-schema.xml |   78 ++++++++++++++++++++++++++++++++++++++
 1 files changed, 77 insertions(+), 1 deletions(-)

diff --git a/opendj3/src/main/docbkx/admin-guide/chap-schema.xml b/opendj3/src/main/docbkx/admin-guide/chap-schema.xml
index 069d0b6..c21a824 100644
--- a/opendj3/src/main/docbkx/admin-guide/chap-schema.xml
+++ b/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

--
Gitblit v1.10.0