Extending the PingDirectory server schema

The PingDirectory server stores its schema as LDIF files in the <server-root>/config/schema directory.

At startup, the PingDirectory server reads the schema files in alphanumeric order starting with 00-core.ldif and ending with any custom schema definition files, such as 99-user.ldif, if present.

You can extend the schema to include additional customizations necessary for your PingDirectory server data using one of the following methods:

Using the Schema Editor

This method is the easiest and quickest way to set up a schema definition and have it validated for the correct ASN.1 formatting. The Editor lets you define your schema properties, load your custom file, or perform a cut-and-paste operation on a new schema element. If any errors exist in the file, the Schema Editor generates an error message if the schema definitions do not pass compliance.
Using a custom schema file

You can create a custom schema file with your new definitions using a text editor, save it as 99-user.ldif, and then import the file using the Schema Editor or the ldapmodify tool. You must name the custom LDIF file with a high two-digit number prefix, so that the PingDirectory server reads the file after the core schema files are read at startup. For example, you can name the file 99-myschema.ldif.

For more information on the requirements for naming each file, see the next section, General tips on extending the schema.
Using the command line

If you have a small number of additions, you can extend the schema over LDAP and from the command line using the ldapmodify tool. The PingDirectory server writes the new schema changes to a file such as 99-user.ldif in the <server-root>/config/schema directory. However, this method can be cumbersome because schema definitions require strict adherence to text spacing and white space characters.

General tips on extending the schema

Consider the following points when extending the schema:

Never modify the default schema files because doing so could damage the PingDirectory server’s processing capabilities.
Define all attributes before they can be used in an object class. If you are using the Schema Editor to add new schema elements, use the Quick Add Attributes option when defining new object classes.
Define the parent object class before creating object classes that inherit from the parent.
You must name custom schema files according to the following syntax:
1. Begin with exactly two digits.
2. Follow the two digits with a non-digit character.
3. Follow the non-digit character with a zero or more characters.
4. End in .ldif.
  
  The two digits don’t need to be followed by a dash ("-").
  
  Any files that do not meet this criteria are ignored and either a NOTICE or SEVERE_WARNING message is logged.
Any file in the <server-root>/config/schema directory with a name that starts with "." or ends with a tilde (’~’), .swp, or .tmp generates a NOTICE message indicating that temporary files will be ignored. Any other file that does not meet the naming criteria generates a SEVERE_WARNING message indicating that it will be ignored.
Define custom attributes and object classes in one file. Typically, this file is the 99-user.ldif. You can specify a different file name that the PingDirectory server writes to using the X-SCHEMA-FILE element and the file name in the definition, as in the following example.
```
add: attributeTypes attributeTypes: ( 1.3.6.1.4.1.32473.3.1.9.1
  NAME 'contractorStatus'
  EQUALITY booleanMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
  SINGLE-VALUE
  USAGE userApplications
  X-ORIGIN 'Directory Server Example'
  X-SCHEMA-FILE '99-custom.ldif' )
```
In the white space characters in the schema definitions, WSP means zero or more space characters, and SP means one or more space characters. The LDIF specification states that LDIF parsers should ignore exactly one space at the beginning of each continuation line because continuation lines must begin with a space character.

If you define a new schema definition with each keyword on a separate continuation line, you should add two spaces before an element keyword to guarantee correct formatting. For example, the following attribute definition has two spaces before the keywords NAME, SUP, and X-ORIGIN.
```
attributeTypes: ( 2.5.4.32 NAME 'owner' SUP distinguishedName X-ORIGIN 'RFC 4519' )
```
In a replicated topology, any new schema additions are replicated to other replication servers to their respective Schema backend. The additions are written to the file specified by the X-SCHEMA-FILE extension or written to 99-user.ldif if no file is specified.