Understanding Attribute Syntaxes

Attribute syntaxes are essentially data type definitions. The syntax for an attribute type indicates the type of data meant to be held by the corresponding values. This can be used to determine whether a particular value is acceptable for a given attribute, as well as to provide information about how Oracle Unified Directory should interact with existing values.

Oracle Unified Directory supports the ability to reject values that violate the associated attribute syntax, and this is the default behavior for the purposes of standards compliance. It is possible to disable this attribute syntax checking completely if necessary, but it is also possible to accept values that violate the associated syntax but log a warning message to Oracle Unified Directory's error log every time this occurs. However, if attributes are allowed to have values that violate their associated syntax, matching operations might not behave as expected with such values. For information about disabling schema checking, see Configuring Schema Checking in Oracle Fusion Middleware Administration Guide for Oracle Unified Directory.

The following sections discuss attribute syntax:

• The Attribute Syntax Description Format

• Commonly Used Attribute Syntaxes

• The Pattern-Matching Syntax Extension

• The Enumeration Syntax Extension

• Substitution Syntax Extension

The Attribute Syntax Description Format

The attribute syntax description format is described in RFC 4512, section 4.1.5, as shown in this example:

SyntaxDescription = LPAREN WSP
numericoid                 ; object identifier
[ SP "DESC" SP qdstring ]  ; description
extensions WSP RPAREN      ; extensions

The attribute syntax description includes these elements:

numericoid

The numeric OID used to uniquely identify the attribute syntax in Oracle Unified Directory.

DESC

An optional description for the syntax. If it is provided, then it must be enclosed in single quotation marks.

extensions

An optional set of extensions for the attribute syntax. Oracle Unified Directory supports the following extensions:

X_PATTERN

Specifies that the attribute uses the regular expression syntax. See The Pattern-Matching Syntax Extension for more information.

X-ENUM

Specifies that the attribute uses the enumerated syntax. See The Enumeration Syntax Extension for more information.

X-SUBST

Specifies that the attribute uses the substitution syntax. See Substitution Syntax Extension for more information.

The following example shows the attribute syntax description for the standard directory string syntax:

( 1.3.6.1.4.1.1466.115.121.1.15 DESC 'Directory String' ) 

In this case, the OID is 1.3.6.1.4.1.1466.115.121.1.15, and the description is Directory String. This example specifies no extensions.

Commonly Used Attribute Syntaxes

There are a number of attribute syntaxes defined in LDAP, both in the core protocol specification and in other related RFCs and Internet Drafts. Many of these attribute syntaxes are defined in RFC 4517 (LDAP Syntaxes and Matching Rules) in section 3.3. Some of the most commonly used attribute syntaxes include:

Directory String

The Directory String syntax is used to hold general-purpose string values containing one or more UTF-8 characters. Technically, empty values (that is, those with zero characters) are not allowed. Because Oracle Directory Server Enterprise Edition has historically allowed empty values, Oracle Unified Directory offers a configuration option that can be used to allow it as well although it is disabled by default for standards compliance.

IA5 String

The IA5 String syntax is used to hold string values based on the IA5 character set, which is also known as the ASCII character set.

Printable String

The Printable String syntax is used to hold string values that contain one or more characters from the set of uppercase and lowercase letters, numeric digits, single quotes, left and right parentheses, plus sign, comma, hyphen, period, and equal sign.

Boolean

The Boolean syntax is used to hold values of either TRUE or FALSE. No other values are allowed for attributes with this syntax.

Integer

The Integer syntax is used to hold integer values, which must contain at least one digit. It can start with a hyphen to indicate a negative value. Zero can be used as the first digit only when the value is zero.

Octet String

The Octet String syntax is used to hold a set of zero or more bytes. It has been used to replace the former Binary syntax.

DN

The DN syntax is used to hold distinguished name values, comprised of zero or more RDN components. Values should be in the format specified in RFC 4514 (LDAP String Representation of Distinguished Names).

The Pattern-Matching Syntax Extension

The X-PATTERN attribute syntax extension can be used to define new string syntaxes with values restricted by one or more regular expressions. The following example adds an X-PATTERN attribute syntax to the schema.

$ ldapmodify -p 1389 -h localhost -D "cn=Directory Manager" -w password
dn: cn=schema
changetype: modify
add: ldapsyntaxes
ldapSyntaxes: ( 1.3.6.1.4.1.32473.1 DESC 'Host and Port in the format of HOST:PORT'
  X-PATTERN '^[a-zA-Z][a-zA-Z0-9-]+:[0-9]+$' )

This new syntax can be used to define attributes and object classes, as shown in the following example.

$ ldapmodify -p 1389 -h localhost -D "cn=Directory Manager" -w password
dn: cn=schema
changetype: modify
add: attributetypes
attributetypes: ( 1.3.6.1.4.1.32473.2 NAME 'example-attr-regex' SYNTAX
1.3.6.1.4.1.32473.1 )
-
add: objectclasses
objectclasses: ( 1.3.6.1.4.1.32473.3 NAME 'exampleOCregex' SUP top AUXILIARY MUST
example-attr-regex)
-

Values for example-attr-regex attributes must match the defined pattern, or the server rejects them. The following attribute fits pattern defined in the example syntax, so the server accepts it:

example-attr-regex: localhost:389

The following attribute is rejected because it does not include the required colon and numeric string:

localhost

The following attribute is rejected because it contains periods (.), which are not specified as part of the HOST component:

host.domain.com:389

The Enumeration Syntax Extension

The X-ENUM attribute syntax extension can be used to define new string syntaxes with values restricted to a set of defined, ordered values. The following example defines an X-ENUM attribute to the schema.

$ ldapmodify -p 1389 -h localhost -D "cn=Directory Manager" -w password
dn: cn=schema
changetype: modify
add: ldapsyntaxes
ldapSyntaxes: ( 1.3.6.1.4.1.32473.4 DESC 'Day Of The Week'
  X-ENUM ( 'monday' 'tuesday' 'wednesday' 'thursday'
  'friday' 'saturday' 'sunday' ) )

This new syntax can be used to define attributes and object classes, as shown in the following example.

$ ldapmodify -p 1389 -h localhost -D "cn=Directory Manager" -w password
dn: cn=schema
changetype: modify
add: attributetypes
attributetypes: ( 1.3.6.1.4.1.32473.5 NAME 'example-attr-enum' SYNTAX
1.3.6.1.4.1.32473.4 )
-
add: objectclasses
objectclasses: ( 1.3.6.1.4.1.32473.6 NAME 'exampleOCenum' SUP top AUXILIARY
MUST example-attr-enum)

Values for example-attr-enum attributes must match the defined pattern, or the server rejects them.

Enumerated values are not case-sensitive, so both of the following examples are accepted:

example-attr-enum: thursday
example-attr-enum: Thursday

Enumerated attribute values are literal (and not internationalized), so the following example does not match the pattern and is rejected, regardless of any semantic equivalence:

example-attr-enum: jeudi

The defined values specify an order, so enumerated attributes can be used in relative comparison filters, as shown in the following example:

(example-attr-enum>=wednesday)

The preceding comparison filter matches, for example, a value of thursday. The comparison is based on the order of the enumerated values, and ASCII values are not applicable in this case.

Substitution Syntax Extension

The X-SUBST attribute syntax extension can be used to define new string syntaxes with values in terms of existing syntaxes. It is provided for use when extending the native directory server schema with a non-standard schema (or an external schema) that uses syntaxes not supported by Oracle Unified Directory. Instead of altering the imported schema, extend it with the X-SUBST extension to instruct Oracle Unified Directory to treat values in terms of a supported syntax.

The following example defines a new syntax, AttCertPath, in terms of an existing syntax, 1.3.6.1.4.1.1466.115.121.1.15, directory string. This change must be made under cn=schema.

$ ldapmodify -p 1389 -h localhost -D "cn=Directory Manager" -w password
dn: cn=schema
objectClass: top
objectClass: ldapSubentry
objectClass: subschema
ldapSyntaxes: ( 1.3.6.1.4.1.4203.666.11.10.2.4
  DESC 'AttCertPath'
  X-SUBST '1.3.6.1.4.1.1466.115.121.1.15' )

This feature can be useful during migration and can lessen the impact on the schema. For example, during migration to Oracle Unified Directory, an incoming schema can contain attribute definitions that use an undefined syntax. The X-SUBST attribute syntax extension provides a means to define those missing syntaxes in terms of other, more general syntaxes. With this capability, the schema and data can be migrated without the need to modify the schema or data or to implement new syntaxes.