Update: This post is old but still accurate as far as comparing JSON with property lists, with examples for Objective-C code. If you’re using Swift, see my newer post that updates this one for
Codableand Swift examples.
Mac OS X and iOS include support for JSON and property lists, two generic structured data formats, both in common use in different places. If Stack Overflow is any indication, there’s a fair amount of confusion regarding the two. It’s true, they’re very similar, so much that it’s tempting to think the differences are merely syntax choices. In some cases it’s possible to read data from one format and write it to the other as-is, with no conversion. But not always. JSON isn’t a property list and a property list isn’t JSON, but they do have a lot in common.
Both of these are generic data formats, in that they’re designed to be flexible enough to store structured data for a wide variety of uses. For any given use, neither is likely to be the optimum format by any metric– except flexibility and familiarity. Each handles so many different uses that they’ve become the go-to format in their respective domains, regardless of the nature of the data.
What’s a Property List?
Property lists have been used with Objective-C and Cocoa since before either were part of Apple. The origins are lost in the mists of antiquity. In general, a property list is any collection of property list objects, which are
NSDate. There’s also a rule that for an
NSDictionary to be considered a property list, the keys must be
NSStrings (this isn’t true for non-property list dictionaries, where any object that conforms to
NSCopying can be a key). Any of these objects can be a property list all by itself– there’s no requirement for a specific root object.
This format is ubiquitous in Mac and iOS development, not least because there’s been direct API support pretty much forever. You can easily read a property list into an
NSDictionary via the
+dictionaryWithContentsOfFile: method, or write one back out to a property list
-writeToFile:atomically:. Either direction is just one method call. These methods only work if the data is a valid property list. No custom objects, no other Cocoa objects, and making your class comply with
NSCoding doesn’t make any difference. (If you want to read and write objects with
NSUserDefaults uses property lists, so only property list types can go into user defaults. So does pretty much every app you’ve used on Mac OS X and iOS, via the ubiquitous
Property lists have used different file formats over the years, starting with an ASCII format that was remarkably similar to JSON. These days either XML or an undocumented binary format are preferred, and the older format can only be read, not written.
JSON serves more or less the same purpose in web apps and web-based APIs. It wasn’t widely used on Mac OS X, but with the debut of iOS apps, interest took off. Initially there was no direct JSON support from iOS frameworks, so Jon Wight’s TouchJSON became the de facto standard. Beginning with iOS 5 and Mac OS X 10.7, Apple provides
NSJSONSerialization to convert between JSON and Cocoa objects.
In Cocoa terms, JSON can include
NSNull (more on that later). As with property lists, dictionary keys must be strings. There are a couple of other rules that don’t apply to property lists:
- The root object must be an
- Numbers must not be infinite or
Why can’t I convert my JSON to a property list?
The differences described above mean that while it’s often possible to take some valid JSON and write it to a property list, this is not always the case. The most common error seems to relate to JSON’s use of
With JSON, the usual approach seems to be that all keys that are part of an object must be represented. If there’s no value for some key, the JSON way is to use a value of
null in Cocoa? It’s the singleton instance of
NSNull. If you’ve been paying attention, you’ll notice that
NSNull is not a property list type. As a result, if your JSON might contain a
null value, there’s a decent chance that you can’t save it as a property list.
Not without some work, anyway. If you really want to use property list formatting, you’ll need to recursively run through your JSON, find any
null values, and replace or remove them. With Cocoa, if there’s no value for a key, the usual approach is to just not put that key in the dictionary. That makes its value implicitly
nil (which is not
null, and definitely not
NSNull). It would be reasonable, then, to just drop any
Before doing that though, ask yourself, is this conversion necessary?
NSJSONSerialization can read and write files. If you have JSON structured data, you may be better off just leaving it as JSON and not bothering with conversions.
Why can’t I convert my property list to JSON?
Going this direction, the potential conflicts are numerous. In approximate order of how likely you are to run into them:
- Property lists can contain
NSDates. JSON doesn’t have a native date format. ISO8601 formatting is common but not actually standard. It would be possible to use a default date format when writing JSON, but there’s no guarantee it would be compatible with any particular API. Worse, when reading JSON, it would be necessary to match every string value against date format regular expressions to see if anything matched.
NSData, a property list can contain an arbitrary binary blob as an array element or a dictionary value. This could probably be base64 encoded when saving as JSON, but it isn’t. As with dates, it would be possible to make default conversions, but writing wouldn’t guarantee compatibility and reading would be error-prone and slow.
- Numeric values in property lists can be infinite, or can indicate an invalid value by simply reading and writing
NaN. JSON doesn’t like this.
As a simple example, this array is a valid property list:
NSArray *myArray = @[@123, @456.789, @YES, [NSDecimalNumber notANumber], [NSNumber numberWithFloat:1.0/0.0], [NSDate date] ];
Write this to a property list file via the built-in
writeToFile:atomically: and you get:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <array> <integer>123</integer> <real>456.78899999999999</real> <true/> <real>nan</real> <real>+infinity</real> <date>2013-04-03T17:00:12Z</date> </array> </plist>
If you tried to write this as JSON, well, you wouldn’t, because it’s invalid in multiple ways. It’s interesting to see that the XML tags reflect on the type of numeric values– rather than
number or something like that, we get
real, and the Boolean shows up as simply
true. They all convert to/from
NSNumber transparently, since it can handle all three.
As an aside, holy crap, “456.78899999999999”? Wow.
How can I find out if I can’t convert?
If you must convert your data format, the best approach is to just not make any assumptions. JSON is allowed to contain stuff that’s illegal in property lists and vice versa. When converting, scan your data and make whatever changes are needed. Don’t assume that because it’s working today that there won’t be unexpected changes tomorrow. The web service you’re using might change their API tomorrow, and you don’t want that to crash your app.
There are a couple of useful methods you can use to find out if any given object is valid for either format. If you want JSON and aren’t sure if you have it, ask
BOOL validJSON = [NSJSONSerialization isValidJSONObject:myArray];
When writing as a property list, check out the extremely useful
BOOL validPlist = [NSPropertyListSerialization propertyList:myArray isValidForFormat:NSPropertyListXMLFormat_v1_0];