About Property Lists

A property list is a structured data representation used by Cocoa and Core Foundation as a convenient way to store, organize, and access standard types of data. It is colloquially referred to as a “plist.” Property lists are used extensively by applications and other software on OS X and iOS. For example, the OS X Finder—through bundles—uses property lists to store file and directory attributes. Applications on iOS use property lists in their Settings bundle to define the list of options displayed to users. This section explains what property lists are and when you should use them.

What is a Property List?

Property lists are based on an abstraction for expressing simple hierarchies of data. The items of data in a property list are of a limited number of types. Some types are for primitive values and others are for containers of values. The primitive types are strings, numbers, binary data, dates, and Boolean values. The containers are arrays—indexed collections of values—and dictionaries—collections of values each identified by a key. The containers can contain other containers as well as the primitive types. Thus you might have an array of dictionaries, and each dictionary might contain other arrays and dictionaries, as well as the primitive types. A root property-list object is at the top of this hierarchy, and in almost all cases is a dictionary or an array. Note, however, that a root property-list object does not have to be a dictionary or array; for example, you could have a single string, number, or date, and that primitive value by itself can constitute a property list.

From the basic abstraction derives both a static representation of the property-list data and a runtime representation of the property list. The static representation of a property list, which is used for storage, can be either XML or binary data. (The binary version is a more compact form of the XML property list.) In XML, each type is represented by a certain element. The runtime representation of a property list is based on objects corresponding to the abstract types. The objects can be Cocoa or Core Foundation objects. Table 2-1 lists the types and their corresponding static and runtime representations.

Table 2-1  Property list types and their various representations

Abstract type

XML element

Cocoa class

Core Foundation type




CFArray (CFArrayRef)




CFDictionary (CFDictionaryRef)




CFString (CFStringRef)




CFData (CFDataRef)




CFDate (CFDateRef)

number - integer


NSNumber (intValue)

CFNumber (CFNumberRef, integer value)

number - floating point


NSNumber (floatValue)

CFNumber (CFNumberRef, floating-point value)


<true/> or <false/>

NSNumber (boolValue == YES or boolValue == NO)

CFBoolean (CFBooleanRef ; kCFBooleanTrue or kCFBooleanFalse)

By convention, each Cocoa and Core Foundation object listed in Table 2-1 is called a property-list object. Conceptually, you can think of “property list” as being an abstract superclass of all these classes. If you receive a property list object from some method or function, you know that it must be an instance of one of these types, but a priori you may not know which type. If a property-list object is a container (that is, an array or dictionary), all objects contained within it must also be property-list objects. If an array or dictionary contains objects that are not property-list objects, then you cannot save and restore the hierarchy of data using the various property-list methods and functions. And although NSDictionary and CFDictionary objects allow their keys to be objects of any type, if the keys are not string objects, the collections are not property-list objects.

Because all these types can be automatically cast to and from their corresponding Cocoa types, you can use the Core Foundation property list API with Cocoa objects. In most cases, however, methods provided by the NSPropertyListSerialization class should provide enough flexibility.

When to Use Property Lists

Many applications require a mechanism for storing information that will be needed at a later time. For situations where you need to store small amounts of persistent data—say less than a few hundred kilobytes—property lists offer a uniform and convenient means of organizing, storing, and accessing the data.

In some situations, the property-list architecture may prove insufficient. If you need a way to store large, complex graphs of objects, objects not supported by the property-list architecture, or objects whose mutability settings must be retained, use archiving. See Archives and Serializations Programming Guide for more information.

If you are looking for a way to implement user or application preferences, Cocoa provides a class specifically for this purpose. While the user defaults system does use property lists to store information, you do not have to access these plists directly. See Preferences and Settings Programming Guide and Preferences Programming Topics for Core Foundation for more information.

Note that property lists should be used for data that consists primarily of strings and numbers. They are very inefficient when used with large blocks of binary data.

Property List Representations

A property list can be stored in one of three different ways: in an XML representation, in a binary format, or in an “old-style” ASCII format inherited from OpenStep. You can serialize property lists in the XML and binary formats. The serialization API with the old-style format is read-only.

XML property lists are more portable than the binary alternative and can be manually edited, but binary property lists are much more compact; as a result, they require less memory and can be read and written much faster than XML property lists. In general, if your property list is relatively small, the benefits of XML property lists outweigh the I/O speed and compactness that comes with binary property lists. If you have a large data set, binary property lists, keyed archives, or custom data formats are a better solution.