Extended Object Names

Extended object naming mode allows MinIO 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, MinIO AIStor encodes object names to remove restricted characters before writing to the filesystem. When MinIO 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, MinIO AIStor leaves extended naming mode disabled. This causes MinIO AIStor to reject object names that may cause filesystem conflicts.

Extended object naming mode requires MinIO AIStor RELEASE.2025-12-20T04-58-37Z or later.

Enable extended mode

Use the --object-naming=extended parameter when starting up MinIO AIStor for the first time. You must use the same mode on all nodes in a MinIO 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

MinIO AIStor uses specific Unicode characters to represent special patterns when writing to disk. This is only visible if you introspect MinIO AIStor drives.

Users and applications do not encounter the encoded object name when MinIO AIStor serves it. MinIO 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 MinIO AIStor uses them:

Escape character rules

If an object name includes one of the characters used for encoding, MinIO AIStor replaces the character with an escaped form using the escape character ␣. The following table shows how the encoded characters are written on disk:

Reserved characters

The following five characters are reserved. While not currently used by MinIO AIStor, extended object name mode converts the following additional characters in object names for writing to the filesystem.

Extended object name example

For an object named data◊file.txt, MinIO AIStor writes it to the filesystem as data␣4file.txt◊.

The ◊ character in the original object name becomes ␣4 on the drive. MinIO AIStor marks the end of the object name on the drive by adding the terminal character, ◊, at the end.

When MinIO AIStor receives a GET request or other READ operation for the object, it decodes the name and serves it as data◊file.txt.