Yesterday I’ve explained how to restrict LDAP attribute values using Regular Expression based syntaxes, with the OpenDS directory server. There is another use case for restricting attribute values: when there is an enumerated list of possible values. It’s possible to define finite list of values as a regular expression, but as we wanted to be able to provide additional values, we added in OpenDS the ability to define Enumeration based syntaxes, and we implemented it as a syntax definition extension as well.

Here’s an example of use of an Enumeration syntax for the day of the week. Let’s first define and load the syntax in the OpenDS directory server’s schema :

$ bin/ldapmodify -D cn=directory\ manager -p 1389

Password for user ‘cn=directory manager’:

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’ ) )

Processing MODIFY request for cn=schema

MODIFY operation successful for DN cn=schema

^D

Let’s use the syntax in an attribute, itself used in an object classes:

$ bin/ldapmodify -D cn=directory\ manager -p 1389

Password for user ‘cn=directory manager’:

dn: cn=schema

changetype: modify

add: attributetypes

attributetypes: ( 1.3.6.1.4.1.32473.5 NAME ‘test-attr-enum’

SYNTAX 1.3.6.1.4.1.32473.4 )

–

add: objectclasses

objectclasses: ( 1.3.6.1.4.1.32473.6 NAME ‘testOCenum’ SUP top

AUXILIARY MUST test-attr-enum)

–

Processing MODIFY request for cn=schema

MODIFY operation successful for DN cn=schema

^D

Let’s create a test entry :

$ bin/ldapmodify -D cn=directory\ manager -p 1389

Password for user ‘cn=directory manager’:

dn: cn=TestEntry,dc=example,dc=com

changetype: add

sn: TestEntry

cn: TestEntry

objectclass: Person

Processing ADD request for cn=TestEntry,dc=example,dc=com

ADD operation successful for DN cn=TestEntry,dc=example,dc=com

^D

And now, let’s make use of the newly created schema objects with that test entry :

$ bin/ldapmodify -D cn=directory\ manager -p 1389

Password for user ‘cn=directory manager’:

dn: cn=TestEntry,dc=example,dc=com

changetype: modify

add: objectclass

objectclass: testOCenum

–

add: test-attr-enum

test-attr-enum: monday

Processing MODIFY request for cn=TestEntry,dc=example,dc=com

MODIFY operation successful for DN cn=TestEntry,dc=example,dc=com

^D

But if the value isn’t part of the enumeration, it gets rejected :

$ bin/ldapmodify -D cn=directory\ manager -p 1389

Password for user ‘cn=directory manager’:

dn: cn=TestEntry,dc=example,dc=com

changetype: modify

replace: test-attr-enum

test-attr-enum: Lundi

Processing MODIFY request for cn=TestEntry,dc=example,dc=com

MODIFY operation failed

Result Code: 21 (Invalid Attribute Syntax)

Additional Information: When attempting to modify entry cn=TestEntry,dc=example,dc=com to replace the set of values for attribute test-attr-enum, value "Lundi" was found to be invalid according to the associated syntax: The provided value "Lundi" cannot be parsed because it is not allowed by enumeration syntax with OID "1.3.6.1.4.1.32473.4"

$

The enumeration syntaxes, like the regular expression one, matches like a DirectoryString, that is matches using CaseIgnoreMatch equality rule.

$ bin/ldapsearch -p 1389 -D cn=directory\ manager -w secret12 \

-b "dc=example,dc=com" ‘(test-attr-enum=Monday)’

dn: cn=TestEntry,dc=example,dc=com

objectClass: Person

objectClass: top

objectClass: testOCenum

test-attr-enum: monday

cn: TestEntry

sn: TestEntry

But the biggest advantage of the Enumeration syntax is the ability to use Ordering match, which is not based on strings, but on the order of the enumerated values in the syntax definition. So "Monday" is lower than "Tuesday" which is lower than "Wednesday"…

$ bin/ldapsearch -p 1389 -D cn=directory\ manager -w secret12 \

-b "dc=example,dc=com" ‘(test-attr-enum<=Thursday)’

dn: cn=TestEntry,dc=example,dc=com

objectClass: Person

objectClass: top

objectClass: testOCenum

test-attr-enum: monday

cn: TestEntry

sn: TestEntry

I hope you will find this useful and make use of these syntaxes. To do so, you need to download and install OpenDS 2.2 Release Candidate 1 (or higher).

And if you have additional requirements with syntaxes, I’d be happy to hear about them.

Technorati Tags: directory-server, java, ldap, opends, opensource

One of the question that I get frequently asked when discussing with customers or coworkers about defining custom schema and attributes, is how to restrict the values that can be set to an attribute. From a pure LDAP standard point of view, you would need to define a new syntax and describe the valid values. Then you would need to check with the directory server’s vendor or discuss with the open source developers to get the syntax implemented in the server, either in the core product, or as a plug-in extension. In the end, the easy choice goes to use a standard syntax (like DirectoryString) and let all client applications validate the values.

In OpenDS, we’ve choose another option. We have added support for regular expression based syntaxes, and implemented this as a syntax definition extension.

So in order to define, for example, an attribute whose values must be in the form of host:port, you simply need to define a new syntax for it with the regular expression pattern and load it in the server’s schema:

$ bin/ldapmodify -D cn=directory\ manager -p 1389

Password for user ‘cn=directory manager’:

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]+$’ )

Processing MODIFY request for cn=schema

MODIFY operation successful for DN cn=schema

^D

And then you can make use of the newly defined syntax in attributes.

$ bin/ldapmodify -D cn=directory\ manager -p 1389

Password for user ‘cn=directory manager’:

dn: cn=schema

changetype: modify

add: attributetypes

attributetypes: ( 1.3.6.1.4.1.32473.2 NAME ‘test-attr-regex’ SYNTAX 1.3.6.1.4.1.32473.1 )

–

add: objectclasses

objectclasses: ( 1.3.6.1.4.1.32473.3 NAME ‘testOCregex’ SUP top AUXILIARY MUST test-attr-regex)

–

Processing MODIFY request for cn=schema

MODIFY operation successful for DN cn=schema

^D

Let’s create a test entry

$ bin/ldapmodify -D cn=directory\ manager -p 1389

Password for user ‘cn=directory manager’:

dn: cn=TestEntry,dc=example,dc=com

changetype: add

sn: TestEntry

cn: TestEntry

objectclass: Person

Processing ADD request for cn=TestEntry,dc=example,dc=com

ADD operation successful for DN cn=TestEntry,dc=example,dc=com

^D

And now make use of this new attribute and objectclass:

$ bin/ldapmodify -D cn=directory\ manager -p 1389

Password for user ‘cn=directory manager’:

dn: cn=TestEntry,dc=example,dc=com

changetype: modify

add: objectclass

objectclass: testOCregex

–

add: test-attr-regex

test-attr-regex: localhost:1389

–

Processing MODIFY request for cn=TestEntry,dc=example,dc=com

MODIFY operation successful for DN cn=TestEntry,dc=example,dc=com

^D

$ bin/ldapmodify -D cn=directory\ manager -p 1389

Password for user ‘cn=directory manager’:

dn: cn=testentry,dc=example,dc=com

changetype: modify

replace: test-attr-regex

test-attr-regex: foobar.com

Processing MODIFY request for cn=testentry,dc=example,dc=com

MODIFY operation failed

Result Code: 21 (Invalid Attribute Syntax)

Additional Information: When attempting to modify entry cn=testentry,dc=example,dc=com to replace the set of values for attribute test-attr-regex, value "foobar.com" was found to be invalid according to the associated syntax: The provided value "foobar.com" cannot be parsed as a valid regex syntax because it does not match the pattern "^[a-zA-Z][.a-zA-Z0-9-]+:[0-9]+$"

It’s simple and efficient. But wait there’s more to come, tomorrow.

Technorati Tags: directory-server, java, ldap, opends, opensource