Ben Summers presents
Spotlight, the way you've always wanted it! is a domain registered for the purpose of adding structured metadata in xattr records and Spotlight.

This web site documents how the metdata keys and data are formatted, and presents example code to read and write them. It also documents how to integrate with the SpotMeta utility to add the fields to the Spotlight user interface.

Basic key structure

Keys, both in xattr records and Spotlight schemas, are of the form


where type is a two character type encoding, and name is a user presentable name encoded from 16 bit unicode to A-Z, a-z, 0-9 and the underscore character (the only allowed characters in a Spotlight attribute name.)

The type and the user's presentable name are encoded directly in the attribute for two reasons. Firstly, so it is easily transportable from one installation to another, and secondly, so the SpotMeta Bridging Importer does not need to have read a schema to be able to convert an attribute for use in Spotlight.

Given that this is the case, an external utility can just create the xattr records and then make Spotlight queries (from a program or the command line) without even informing anything of the schema definitions for these keys.

Types and data encodings

The type is encoded in two characters. The first specifies whether the value is a single item or multi-value.

sSingle value
mMultiple values

Note that this part of the type does not encode whether there is currently one or more than one value in the value part, but whether it is possible at all. If the type was to change, it would be treated as a separate key.

The second character specifies the type of the data. All data is encoded as UTF-8 string representations. Multiple values are simply separated by the ASCII record separator control code, hex value 0x1E,

tTextSimple UTF-8 string
cChoiceSimple UTF-8 string, but it is assumed that there are a limited number of possibilities. The distinction between this and text is mainly in the user interface.
nNumberDecimal, optional floating point part
bBoolean value"0" = false, "1" = true
dDate (and time)GMT time encoded as YYYYMMDDHHMMSS

The encoding is intended to be human readable, yet easy to parse.

Name encoding

Encoding of the name part of the metadata key is slightly complex. It is desirable to encode the full 16 bit unicode text, yet it should be as human readable as possible, and, given the 128 byte limitation on xattr key size, should be compact.

While xattr keys are UTF-8 encoded, Spotlight restricts them to A-Z, a-z, 0-9 and the underscore character.

The underscore character is used as the escape character. Other characters are passed untouched. A space is encoded as a double underscore.

Other characters are encoded as follows. If the value of the character is c

This coding uses up to four characters (3 digits plus the _ escape character) but for English strings tends to use two or three characters.

You are encouraged to use the example code to encode and decode strings.

Implementation notes

After writing the metadata in xattr strings, run mdimport on the file, as the changes are not picked up by Spotlight automatically. The SpotMeta Bridging Importer will hopefully handle this properly in the future.

Note that running mdimport on a directory will re-import all the files in that directory and subdirectories, which is probably not a particular desirable operation.

Spotlight does not require that you register any metadata keys using importer schemas; for some application where it is not necessary for the end user to search on the metadata from the Finder interface, it may not be worth setting up a schema entry.

Example code

coming soon....




How SpotMeta helps you organise your files

Using SpotMeta

Information for Advanced Users


Contact the author

Project status


SpotMeta is an Open Source project, licensed under the GPL.

See note about development status on the contact page.