Extended Object Names
RELEASE.2025-12-20T04-58-37Z or later.
Extended object naming mode allows AIStor to encode object names to use characters that can be written to typical filesystems.
The S3 specification allows for the use of all UTF-8 characters in object names. However, filesystems have their own restrictions on what is allowed to be written to disk.
For example, the XFS filesystem that MinIO recommends is one of many that use the / character to indicate directory structure.
With extended naming mode enabled, AIStor encodes object names to remove restricted characters before writing to the filesystem. When AIStor receives a request for these objects, it decodes the filesystem name and serves it as the original object name.
You can only enable extended object naming mode on the initial cluster start. You cannot change the extended object name mode later, either to enable or disable it.
By default, AIStor leaves extended naming mode disabled. This causes AIStor to reject object names that may cause filesystem conflicts.
Enable extended mode
Use the --object-name=extended parameter when starting up AIStor for the first time.
You must use the same mode on all nodes in an AIStor cluster.
For example, if running a local test server with extended name mode, include the --object-naming parameter in the minio server command:
minio server --object-naming=extended /data
For production servers, set the MINIO_OBJECT_NAMING environment variable to extended before running the minio server command for the first time.
For example, include the following line in your environment variable file:
MINIO_OBJECT_NAMING=extended
You cannot modify the object naming mode after initializing the cluster. Similarly, you cannot change or migrate backend formats at a later date.
Character encoding
AIStor uses specific Unicode characters to represent special patterns when writing to disk. This is only visible if you introspect AIStor drives.
Users and applications do not encounter the encoded object name when AIStor serves it. AIStor retrieves the object and decodes the object name, serving the original object name to the user or application.
The following table lists the encoding characters and when AIStor uses them:
| Character | Unicode | Name | Purpose | Example |
|---|---|---|---|---|
⫽ |
U+2AFD | Extra Slash | Marks double slashes | my//object → my⫽/object |
◖ |
U+25D6 | Leading Slash | Marks leading slashes | /myobject → ◖myobject |
◗ |
U+25D7 | Trailing Slash | Marks trailing slashes | myobject/ → myobject◗ |
◊ |
U+25CA | Terminal | Prevents filesystem conflicts | All names end with ◊ |
␣ |
U+2423 | Escape | Escapes special characters | See escape rules below |
Escape character rules
If an object name includes one of the characters used for encoding, AIStor replaces the character with an escaped form using the escape character ␣.
The following table shows how the encoded characters are written on disk:
| Original Character | Escaped Form | Description |
|---|---|---|
␣ |
␣0 |
Escape character itself |
⫽ |
␣1 |
Extra slash marker |
◖ |
␣2 |
Leading slash marker |
◗ |
␣3 |
Trailing slash marker |
◊ |
␣4 |
Terminal marker |
Reserved characters
The following five characters are reserved. While not currently used by AIStor, extended object name mode converts the following additional characters in object names for writing to the filesystem.
| Character | Unicode | Converts to |
|---|---|---|
◉ (Fisheye) |
U+25C9 | ␣5 |
◈ (White diamond containing black small diamond) |
U+25C8 | ␣6 |
◇ (White diamond) |
U+25C7 | ␣7 |
◆ (Black diamond) |
U+25C6 | ␣8 |
⬡ (White hexagon) |
U+2B21 | ␣9 |
Extended object name example
For an object named data◊file.txt, AIStor writes it to the filesystem as data␣4file.txt◊.
The ◊ character in the original object name becomes ␣4 on the drive.
AIStor marks the end of the object name on the drive by adding the terminal character, ◊, at the end.
When AIStor receives a GET request or other READ operation for the object, it decodes the name and serves it as data◊file.txt.