JSONKit is licensed under the terms of the BSD License.
JavaScript Object Notation, or JSON, is a lightweight, text-based, serialization format for structured data that is used by many web-based services and API's. It is defined by RFC 4627
JSON provides the following primitive types:
null
- Boolean
true
andfalse
- Number
- String
- Array
- Associative Arrays (Objects in RFC 4627 nomenclature, a.k.a. Key / Value Hash Tables, Maps, Dictionaries, etc.)
These primitive types are mapped to the following Objective-C Foundation classes:
JSON | Objective-C |
---|---|
null | NSNull |
true and false | NSNumber |
Number | NSNumber |
String | NSString |
Array | NSArray |
Associative Arrays | NSDictionary |
JSONKit uses Core Foundation internally, and it is assumed that Core
Foundation ≡ Foundation for every equivalent base type, i.e. CFString
≡ NSString
.
-
While the JSON specification specifies that the serialized JSON must be encoded in Unicode, it does not specify how Unicode encoding errors should be handled. In general, JSONKit will not accept JSON that contains ill-formed Unicode.
When the
JKParseOptionLooseUnicode
option is used, JSONKit follows the specifications and recommendations given in The Unicode 5.2 standard, Chapter 3, section 3.9 Unicode Encoding Forms. As a general rule of thumb, the Unicode code pointU+FFFD
is substituted for any ill-formed Unicode encountered. JSONKit attempts to follow the recommended Best Practice for Using U+FFFD: Replace each maximal subpart of an ill-formed subsequence by a single U+FFFD. Additionally, the following Unicode code points are treated as ill-formed Unicode, and ifJKParseOptionLooseUnicode
is enabled, causeU+FFFD
to be substituted in their place:U+0000
.
U+D800
thruU+DFFF
, inclusive.
U+FDD0
thruU+FDEF
, inclusive.
U+
nFFFE
andU+
nFFFF
, where n is from0x0
to0x10
The code points
U+FDD0
thruU+FDEF
,U+
nFFFE
, andU+
nFFFF
(where n is from0x0
to0x10
), are defined as Noncharacters by the Unicode standard and "should never be interchanged".RFC 4627 allows for these limitations under section 4, Parsers:
An implementation may set limits on the length and character contents of strings.
The
NSString
class may place additional restrictions or otherwise transform the JSON String in such a way so that the JSON String is not bijective with the instantiatedNSString
object. In other words, JSONKit can not guarantee that when you round trip a JSON String to aNSString
and then back to a JSON String that the two JSON Strings will be exactly the same, even though in practice they are. For clarity, "exactly" in this case means bit for bit identical. JSONKit can not even guarantee that the two JSON Strings will be Unicode equivalent, even though in practice they will be and would be the most likely cause for the two round tripped JSON Strings to no longer be bit for bit identical. -
JSONKit maps
true
andfalse
to theCFBoolean
valueskCFBooleanTrue
andkCFBooleanFalse
, respectively. Conceptually,CFBoolean
values can be thought of, and treated as,NSNumber
class objects. The benefit to usingCFBoolean
is thattrue
andfalse
JSON values can be round trip deserialized and serialized without conversion or promotion to aNSNumber
with a value of0
or1
. -
The JSON specification does not specify the details or requirements for JSON Number values, nor does it specify how errors due to conversion should be handled. In general, JSONKit will not accept JSON that contains JSON Number values that it can not convert with out error or loss of precision.
For non-floating-point numbers (i.e., JSON Number values that do not include a
.
ore|E
), JSONKit uses a 64-bit C primitive type internally, regardless of whether the target architecture is 32-bit or 64-bit. For unsigned values (i.e., those that do not begin with a-
), this allows for values up to264-1
, and up to-263
for negative values. As a special case, the JSON Number-0
is treated as a floating-point number since the underlying floating-point primitive type is capable of representing a negative zero, whereas the underlying twos-complement non-floating-point primitive type can not. JSON that contains Number values that exceed these limits will fail to parse and optionally return aNSError
object. The functionsstrtoll()
andstrtoull()
are used to perform the conversions.The C
double
primitive type, or IEEE 754 Double 64-bit floating-point, is used to represent floating-point JSON Number values. JSON that contains floating-point Number values that can not be represented as adouble
(i.e., due to over or underflow) will fail to parse and optionally return aNSError
object. The functionstrtod()
is used to perform the conversion. Note that the JSON standard does not allow for infinities orNaN
(Not a Number). -
For JSON Associative Arrays (or
object
in RFC 4627 nomenclature), RFC 4627 saysThe names within an object SHOULD be unique
(note:name
is akey
in JSONKit nomenclature). At this time the JSONKit behavior isundefined
for JSON that contains names within an object that are not unique. However, JSONKit currently tries to follow a "the last key / value pair parsed is the one chosen" policy. This behavior is not finalized and should not be depended on.
-
The
NSDictionary
class allows for any object, which can be of any class, to be used as akey
. JSON, however, only permits Strings to be used askeys
. Therefore JSONKit will fail with an error if it encounters aNSDictionary
that contains keys that are notNSString
objects during serialization. -
JSON does not allow for Numbers that are
±Infinity
or±NaN
. Therefore JSONKit will fail with an error if it encounters aNSNumber
that contains such a value during serialization. -
JSONKit will fail with an error if it encounters an object that is not a
NSNull
,NSNumber
,NSString
,NSArray
, orNSDictionary
class object during serialization. -
Objects created with
[NSNumber numberWithBool:YES]
and[NSNumber numberWithBool:NO]
will be mapped to the JSON values oftrue
andfalse
, respectively.