NSJSONSerialization Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 5.0 and later.
Declared in
NSJSONSerialization.h

Overview

You use the NSJSONSerialization class to convert JSON to Foundation objects and convert Foundation objects to JSON.

An object that may be converted to JSON must have the following properties:

Other rules may apply. Calling isValidJSONObject: or attempting a conversion are the definitive ways to tell if a given object can be converted to JSON data.

Tasks

Creating a JSON Object

Creating JSON Data

Class Methods

dataWithJSONObject:options:error:

Returns JSON data from a Foundation object.

+ (NSData *)dataWithJSONObject:(id)obj options:(NSJSONWritingOptions)opt error:(NSError **)error
Parameters
obj

The object from which to generate JSON data. Must not be nil. Must be an

opt

Options for creating the JSON data.

See “NSJSONWritingOptions” for possible values. Pass 0 to specify no options.

error

If an internal error occurs, upon return contains an NSError object that describes the problem.

Return Value

JSON data for obj, or nil if an internal error occurs. The resulting data is a encoded in UTF-8.

Discussion

If obj will not produce valid JSON, an exception is thrown. This exception is thrown prior to parsing and represents a programming error, not an internal error. You should check whether the input will produce valid JSON before calling this method by using isValidJSONObject:.

Setting the NSJSONWritingPrettyPrinted option will generate JSON with whitespace designed to make the output more readable. If that option is not set, the most compact possible JSON will be generated.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSJSONSerialization.h

isValidJSONObject:

Returns a Boolean value that indicates whether a given object can be converted to JSON data.

+ (BOOL)isValidJSONObject:(id)obj
Parameters
obj

The object to test.

Return Value

YES if obj can be converted to JSON data, otherwise NO.

Discussion

Availability
  • Available in iOS 5.0 and later.
Declared In
NSJSONSerialization.h

JSONObjectWithData:options:error:

Returns a Foundation object from given JSON data.

+ (id)JSONObjectWithData:(NSData *)data options:(NSJSONReadingOptions)opt error:(NSError **)error
Parameters
data

A data object containing JSON data.

opt

Options for reading the JSON data and creating the Foundation objects.

For possible values, see “NSJSONReadingOptions.”

error

If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

A Foundation object from the JSON data in data, or nil if an error occurs.

Discussion

The data must be in one of the 5 supported encodings listed in the JSON specification: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. The data may or may not have a BOM. The most efficient encoding to use for parsing is UTF-8, so if you have a choice in encoding the data passed to this method, use UTF-8.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSJSONSerialization.h

JSONObjectWithStream:options:error:

Returns a Foundation object from JSON data in a given stream.

+ (id)JSONObjectWithStream:(NSInputStream *)stream options:(NSJSONReadingOptions)opt error:(NSError **)error
Parameters
stream

A stream from which to read JSON data.

The stream should be opened and configured.

opt

Options for reading the JSON data and creating the Foundation objects.

For possible values, see “NSJSONReadingOptions.”

error

If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

A Foundation object from the JSON data in stream.

Discussion

The data in the stream must be in one of the 5 supported encodings listed in the JSON specification: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. The data may or may not have a BOM. The most efficient encoding to use for parsing is UTF-8, so if you have a choice in encoding the data passed to this method, use UTF-8.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSJSONSerialization.h

writeJSONObject:toStream:options:error:

Writes a given JSON object to a stream.

+ (NSInteger)writeJSONObject:(id)obj toStream:(NSOutputStream *)stream options:(NSJSONWritingOptions)opt error:(NSError **)error
Parameters
obj

The object to write to stream.

stream

The stream to which to write.

The stream should be opened and configured.

opt

Options for writing the JSON data.

See “NSJSONWritingOptions” for possible values. Pass 0 to specify no options.

error

If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

The number of bytes written to the stream, or 0 if an error occurs.

Discussion

Availability
  • Available in iOS 5.0 and later.
Declared In
NSJSONSerialization.h

Constants

NSJSONReadingOptions

Options used when creating Foundation objects from JSON data—see JSONObjectWithData:options:error: and JSONObjectWithStream:options:error:.

enum {
   NSJSONReadingMutableContainers = (1UL << 0),
   NSJSONReadingMutableLeaves = (1UL << 1),
   NSJSONReadingAllowFragments = (1UL << 2)
};
typedef NSUInteger NSJSONReadingOptions;
Constants
NSJSONReadingMutableContainers

Specifies that arrays and dictionaries are created as mutable objects.

Available in iOS 5.0 and later.

Declared in NSJSONSerialization.h.

NSJSONReadingMutableLeaves

Specifies that leaf strings in the JSON object graph are created as instances of NSMutableString.

Available in iOS 5.0 and later.

Declared in NSJSONSerialization.h.

NSJSONReadingAllowFragments

Specifies that the parser should allow top-level objects that are not an instance of NSArray or NSDictionary.

Available in iOS 5.0 and later.

Declared in NSJSONSerialization.h.

NSJSONWritingOptions

Options for writing JSON data.

enum {     NSJSONWritingPrettyPrinted = (1UL << 0) }; typedef NSUInteger NSJSONWritingOptions;
Constants
NSJSONWritingPrettyPrinted

Specifies that the JSON data should be generated with whitespace designed to make the output more readable. If this option is not set, the most compact possible JSON representation is generated.

Available in iOS 5.0 and later.

Declared in NSJSONSerialization.h.