DN & Attribute Transformers
Relevant source files
The following files were used as context for generating this wiki page:
DN and Attribute Transformers within the flext-ldif library provide essential mechanisms for normalizing, cleaning, and migrating LDAP Distinguished Names (DNs) and entry attributes. These components ensure that LDIF data adheres to RFC 4514 and RFC 2849 standards while allowing for complex transformations required during migrations between different LDAP server types, such as Oracle Internet Directory (OID) and RFC-compliant servers.
The transformation logic is distributed across specialized utility classes for DN handling and server-specific entry implementations that manage attribute-level shifts, such as boolean conversion and ACL name remapping. This system is critical for maintaining data integrity during "round-trip" processing where original formatting must often be preserved or reconstructed. Sources: [src/README.md](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/README.md), [src/flext_ldif/_utilities/dn.py:31-75](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/_utilities/dn.py#L31-L75), [src/flext_ldif/servers/_oid/entry.py:16-30](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/servers/_oid/entry.py#L16-L30).
DN Transformation and Normalization
DN transformation focuses on converting raw strings into canonical, RFC 4514-compliant formats. This involves cleaning whitespace, normalizing character escapes, and handling case sensitivity for attribute types while preserving specific formatting for values where necessary.
DN Cleaning and Statistics
The system provides a comprehensive clean_dn_with_statistics method that tracks exactly what changes were applied to a DN string. This is used for diagnostic and audit purposes to ensure that transformations like tab normalization or space cleaning are transparent.
The diagram shows the flow of a raw DN string through various normalization patterns to produce a cleaned DN and a statistics object.
Sources: [src/flext_ldif/_utilities/dn.py:108-164](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/_utilities/dn.py#L108-L164), [src/flext_ldif/_utilities/dn.py:356-423](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/_utilities/dn.py#L356-L423).
Hierarchical Base DN Transformation
A core feature is the ability to rewrite DNs and DN-valued attributes (like member or manager) when moving entries between different directory branches.
| Function | Description |
|---|---|
transform_dn_attribute | Replaces a source base DN with a target base DN in a single string. |
transform_entry_base_dn | Iterates through an entry's attributes to update all DN-valued fields. |
transform_ldif_content | Performs a bulk regex-based replacement of base DNs in raw LDIF text. |
Sources: [src/flext_ldif/_utilities/dn.py:730-845](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/_utilities/dn.py#L730-L845), [src/flext_ldif/constants.py:84-99](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/constants.py#L84-L99).
Attribute Transformers
Attribute transformers handle the conversion of specific LDAP attribute names and values, particularly during server-specific migrations.
Boolean Value Conversion
Different LDAP servers represent boolean values differently. The OID server implementation specifically handles the conversion between OID's 0/1 format and the RFC-standard FALSE/TRUE format.
- OID to RFC: Converts
0toFALSEand1toTRUE. - RFC to OID: Restores OID specific
0/1values during write operations if metadata indicates an OID target.
Sources: [src/flext_ldif/servers/_oid/entry.py:32-75](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/servers/_oid/entry.py#L32-L75), [src/flext_ldif/constants.py:101-125](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/constants.py#L101-L125).
ACL Name Normalization
Access Control List (ACL) attributes often use proprietary names. The transformers normalize these to a standard aci name for internal processing while maintaining the original name in metadata for reconstruction.
Sequence of events during the parsing of an OID-specific ACL attribute.
Sources: [src/flext_ldif/servers/_oid/entry.py:101-112](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/servers/_oid/entry.py#L101-L112), [src/flext_ldif/servers/_oid/entry.py:171-187](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/servers/_oid/entry.py#L171-L187).
Schema Normalization
Schema definitions require specific transformations to handle inconsistencies in matching rules and syntax OIDs.
- Matching Rules: Corrects substring matching rules incorrectly placed in the
EQUALITYfield (e.g.,caseIgnoreSubStringsMatchtocaseIgnoreMatch). - Syntax OIDs: Removes unnecessary quotes from syntax OIDs and replaces proprietary OIDs with RFC equivalents.
- Case Normalization: Normalizes attribute names by removing suffixes like
;binaryand replacing underscores with hyphens.
Sources: [tests/unit/servers/test_schema_transformer.py:18-115](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/tests/unit/servers/test_schema_transformer.py#L18-L115), [src/flext_ldif/servers/_oid/entry.py:657-710](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/servers/_oid/entry.py#L657-L710).
Transformation Metadata and Audit Trails
To support zero-data-loss migrations, the library captures detailed metadata about every transformation applied to an entry.
Metadata Components
The ServerMetadata model stores the history of changes:
attribute_transformations: Audit records for every renamed or modified attribute.boolean_conversions: Specifically tracks boolean value shifts.original_attribute_case: Preserves the original casing of attribute names (e.g.,objectClassvsobjectclass).minimal_differences: Tracks exact spacing and punctuation changes for perfect round-trip reconstruction.
Sources: [src/flext_ldif/_models/domain_metadata.py:135-240](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/_models/domain_metadata.py#L135-L240), [src/flext_ldif/servers/_oid/entry.py:465-498](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/servers/_oid/entry.py#L465-L498).
Conversion Tracking
| Field | Purpose |
|---|---|
conversion_notes | Human-readable descriptions of operations (e.g., "oid_to_rfc"). |
conversion_history | A step-by-step sequence of transformation events with timestamps. |
original_strings | Complete preservation of the original LDIF line before any transformations. |
Sources: [src/flext_ldif/_models/domain_metadata.py:207-252](https://github.com/flext-sh/flext-ldif/blob/3bbcfeea6481b713fb94c6d3d3b13d843741ebaa/src/flext_ldif/_models/domain_metadata.py#L207-L252).
Summary
DN and Attribute Transformers form the backbone of the flext-ldif migration engine. By combining strict RFC-compliant DN utilities with flexible, metadata-aware attribute processors, the system facilitates high-fidelity data movement between disparate LDAP environments while providing a detailed audit trail of all modifications.