JSON Files - JavaScript Object Notation

Origin and Support of the JSON Format

JSON files were developed for simple data exchange. The files are readable easily both by computers and humans. The file format was originally developed for the programming language JavaScript and is part of the international standard ECMA–262 (European Computer Manufacturers Association). JavaScript is an implementation of the ECMAScript standard, developed by Netscape, or the Mozilla Foundation, respectively.

PropEdit supports the original, strict interpretation of the ECMA standard, as it is commonly used in macOS and is part of the Internet standard RFC 8259, but PropEdit also supports its extension JSON5 as well. This means:

• If the top-level value in a JSON file is a list (array) or an object in form of a key-value mapping (dictionary), the enclosing delimiters (brackets or braces) must not be omitted.
• JSON fragments are permitted. It is allowed that a file only contains a single scalar value.
• Only arrays, dictionaries, strings, and numbers are allowed as data values. Also permitted are the logical values true (yes), false (no), and the special value null.
• Only strings are allowed as keys for dictionaries.
• Use of the standard extension JSON5 is permitted. This includes:
  • Simple or double quotes can be used as delimiters for strings.
  • For keys in dictionaries it is allowed to omit the quotes, as long as the key is not a reserved word of the ECMAscript standard.
  • A trailing comma at the end of an array or dictionary is permitted, no value needs to follow.
  • Strings can span multiple lines, using a backslash at the end of a line.
  • The notation \xdd can be used to specify Latin characters with a code between 0 and 255 (in Unicode) via two hexadecimal digits.
  • C-style comments with // oder /* … */ are possible.
  • Hexadecimal number representation with a 0x prefix, leading decimal points and zeros, and an explicit plus sign for positive numbers are allowed.
  • The special values NaN (not a number), Infinity and -Infinity can be used.

Easily Readable or Compact Presentation

It’s common to break up JSON files using spaces and lines so that a human can easily read them. In this way, the individual items of arrays and dictionaries are each listed clearly on one line, while nested objects are often indented when written.

For a computer, however, an easy-to-read display is not necessary. Instead, the goal is often to save storage space. It’s therefore also possible to arrange JSON files in a particularly compact manner. Spaces and lines breaks will then only be used if absolutely necessary.

PropEdit uses the easily readable file variant by default. Compact storage can be enforced by using the Export feature in the application.

Compatibility between Property Lists and JSON files

Files in plist and JSON formats can both be used as property lists. In practice, the two types can usually be converted into each other immediately. However, note the following limitations that arise directly from the definitions mentioned above:

• A plist file cannot store values of type null. A null value must be represented in another way, e.g. using the number 0 or the string “null”.
• A JSON file cannot store values of type Date and Binary Data.

Limitations when Writing JSON Data

As mentioned earlier, white space (spaces and line breaks) is commonly used to create indentation and separate lines to make JSON data readable. Which exact way this should be done is not standardized, however. So when you open a file, modify it with PropEdit, then save it again, it will usually happen in most cases that the internal notation of the data changes. This cannot be avoided. For this reason, please consider the following limitations and policies that are a direct result of this fact:

• Comments (in accordance with the JSON5 standard) are removed when saving the file.
• Hexadecimal representations of integer numbers are converted to decimal representations.
• Hexadecimal representations of Unicode characters are resolved and replaced by readable characters in the UTF8 standard.
• The representation and accuracy of floating-point numbers can change. This complies with the usual technical limitations of the IEEE 754 standard.
• When using the easily readable variant, the preferred indentation and line breaking style of macOS will be used.
• When saving in compact format, all whitespace and line endings are removed if technically possible.