< Previous PageNext Page > Hide TOC

Assigning Values to Metadata Attributes

Spotlight defines standard metadata attributes that provide a wide range of options for storing your document's metadata. In order for users to be able to find data easily, it is important to use existing keys whenever possible.

Contents:

Spotlight’s Metadata Attributes
Localizing Metadata Attribute Values
Defining Custom Attributes

Spotlight’s Metadata Attributes

Spotlight provides predefined metadata attributes for the following:

• File system attributes. For example, file size, owner, and modification date. These are extracted from the file system automatically by Spotlight.

• Image related attributes. For example, bits per sample, color space, pixel height, and width.

• Video related attributes. For example, codec, video bit rate, and audio bit rate.

• Audio related attributes. For example, sample rate, track number, composer, and time signature.

• Attributes common to many applications. For example, authors, city, organization, email addresses, and headline.

The Spotlight provided metadata attributes are documented in Spotlight Metadata Attributes Reference.

In addition to the data-specific attributes Spotlight provides a general text attribute (kMDItemTextContent) that importers can populate with a text representation of a document's content. Applications can create queries that reference this attribute, but are not able to read the value of this attribute directly.

You should avoid creating new metadata attributes if an existing key would be appropriate. For example, if your document tracks the photographer of an image, use the kMDItemAuthors attribute rather than defining a custom photographer key. Or, if your document includes a company name, use the kMDItemOrganizations attribute.

See “Assigning Values to Metadata Attributes” in “Writing a Spotlight Importer” for an example of how to assign values to metadata attributes.

Localizing Metadata Attribute Values

A Spotlight importer can provide localized values for an attribute by returning a dictionary object instead of a string value. The dictionary must contain keys that correspond to the localized languages. For example “en” for English, “fr” for French, etc. The value for each key should be the corresponding localized attribute value.

Defining Custom Attributes

If none of the existing Spotlight attributes are appropriate or adaptable to your metadata, you can define a custom metadata attribute. An importer specifies the name of the custom attribute, as well as the type of data it contains, in its schema.xml file.

Attribute Naming Conventions

Custom metadata attributes must have unique names. To ensure this you use the reverse DNS naming convention as a prefix for keys that are specific to your document types, replacing “.” with “_” characters. For example, the Mail program would prefix its custom attributes with com_apple_mail.

Defining the Value Object Type

You must specify the type of object that is returned in your custom attribute. The supported types are: CFString, CFNumber, CFBoolean, and CFDate.

Returning Multiple Values in an Attribute

Attributes that return an array of objects rather than a single object are said to be multivalued. If your custom attributes can contain multiple objects, you should declare them as multivalue in your importer's schema file and always return an array, even if it contains only a single instance.

Attribute Display Names and Descriptions

Spotlight importers that declare custom metadata attributes should also provide a display name and description for each attribute. These strings are contained in the file schema.strings in your importer bundle.

The file must be UTF-16 text encoded formatted as a standard strings file. The display name keys correspond to the custom metadata attribute’s name. The description string is specified by appending “.Description” to the key name. Listing 1 shows a sample schema.strings file.

Listing 1  Sample importer’s schema.strings file

"com_apple_myCocoaDocumentApp_myCustomDocument_notes" = "Notes";

"com_apple_myCocoaDocumentApp_myCustomDocument_notes.Description" = "What it is you're supposed to remember.";

You can localize schema.strings files using the standard conventions.

< Previous PageNext Page > Hide TOC