Unicode Normalization
Files.com stores file and folder names using the Unicode spelling supplied when they are created, while using a fixed comparison map to determine whether paths are equivalent. This lets applications match paths consistently when names arrive from different systems, without changing the spelling people see or use in requests.
For example, Résumé.txt and resume.txt compare equally, as do the Japanese characters か and カ. The Files.com map defines these equivalences. A programming language's general lowercasing, case-folding, or Unicode normalization functions do not reproduce the complete comparison rules.
Exact Algorithm for Path Normalization
Integrations need two distinct operations. Normalize cleans up path syntax while preserving name spelling. Normalize For Comparison produces a key for equality checks, such as matching a local file to an entry returned by Files.com. Use spelling-preserving paths for API requests, storage, display, and local filenames; use comparison keys only for matching.
The official Files.com SDKs provide these helpers in JavaScript, Go, Ruby, Python, Java, .NET, and PHP. Use the SDK helpers to keep local matching consistent with the service. For example, JavaScript's pathNormalizer.same and Python's path_util.is_same compare two paths using the shared rules.
Normalize Algorithm
Apply ordinary path syntax normalization before sending a path or building its comparison key:
- Interpret the path as Unicode text, using UTF-8 for encoded path values.
- Remove null characters (
U+0000). - Convert backslashes (
\) to forward slashes (/). - Remove leading and trailing slashes.
- Remove path components that are exactly
.or... - Replace duplicate forward slashes with a single
/.
Removing a .. component does not remove the preceding folder. For example, /Reports/../Résumé.TXT becomes Reports/Résumé.TXT. This operation preserves the names' case, accents, and whitespace; it does not apply the comparison map.
Normalize For Comparison Algorithm
The SDKs bundle the versioned Files.com comparison map, path_comparison.json. Its mapping object supplies replacements keyed by hexadecimal Unicode scalar value. For example, 0041 identifies A, and its replacement is a. Use this shared data when implementing your own integration so the result does not depend on your language's Unicode version or locale.
- Run the path through the Normalize algorithm above.
- Read the normalized input in order, one Unicode scalar at a time. Look up its scalar value in
mapping, interpreting the map's keys as hexadecimal numbers. If an entry exists, append its replacement to the output. An empty replacement removes the scalar; a replacement can also contain several characters. If no entry exists, append the original scalar unchanged. - Use the resulting string as the comparison key.
Iterate Unicode scalars, not UTF-8 bytes or individual UTF-16 code units. A combining accent is a separate scalar from its base letter, and a character outside the Basic Multilingual Plane is one scalar even when represented by two UTF-16 code units.
Apply each replacement once. Do not process replacement text again or apply Unicode normalization, lowercasing, case folding, whitespace trimming, or another path-syntax cleanup after mapping. The map already supplies the comparison form; additional transformations can change which paths match.
Compare the resulting keys as exact strings, without numeric conversion or locale-sensitive comparison. In particular, 0e1 and 0e2 remain different filenames even in a language that can interpret both strings as the number zero. Keys determine equality; sorting them lexicographically does not reproduce the Files.com name-sorting contract.
Comparison Examples
These examples show equality results for names in the same folder. Quotation marks delimit strings; \u0301 represents a combining acute accent, and the space before the closing quote in "report.txt " is part of the filename.
| First Name | Second Name | Comparison Result |
|---|---|---|
"Résumé.TXT" | "resume.txt" | Equal: both keys are resume.txt. |
"q\u0301.txt" | "q.txt" | Equal: the map removes the combining accent. |
"か.txt" | "カ.txt" | Equal: both keys are か.txt. |
"straße.txt" | "strasse.txt" | Equal: the map replaces ß with ss. |
"report.txt" | "report.txt " | Different: the trailing space remains significant. |
"0e1" | "0e2" | Different: the keys are compared as strings. |
The SDK's shared comparison_examples.json provides exact input/output pairs for checking an implementation, including characters that remain unchanged, empty replacements, multi-character replacements, and supplementary characters. Use the map and examples from the same version.
Comparison and Valid Names
A comparison result does not establish that a name is valid. The comparison helpers compute keys; they do not provide a client-side filename-validation policy. Names still need to satisfy Files.com's restricted-character rules, including restrictions on names whose comparison form is empty, is . or .., or contains a path separator.
Trailing spaces, tabs, and newlines remain significant during comparison. Files.com native storage permits trailing whitespace in otherwise valid file names, while folder names cannot end in whitespace, including Unicode whitespace. These are separate naming rules, not instructions to trim a comparison key.
Remote Server Mounts also depend on the remote system's naming and case-sensitivity rules. Preserve the actual spelling when addressing those files, and choose names that work on every system involved in the transfer.