Serialize and deserialize complex object graphs to JSON
Serializr is feature complete, and easily extendable. Since there are no active maintainers the project is frozen feature wise. Bug reports and well designed pull requests are welcome and will be addressed.
The JSON.stringify() method converts a JavaScript object or value to a JSON string, optionally replacing values if a replacer function is specified or optionally including only the specified properties if a replacer array is specified. Object serialization is the process of converting an object’s state to a string from which it can later be restored. ECMAScript 5 provides native functions JSON.stringify() and JSON.parse() to serialize and restore JavaScript objects. These functions use the JSON data interchange format.
Want to maintain a small open source project or having great ideas for this project? We are looking for maintainers, so apply!
Serializr is a utility library that helps converting json structures into complex object graphs and the other way around.For a quick overview, read the introduction blog post
Features:
- (De)serialize objects created with a constructor / class
- (De)serialize primitive values
- (De)serialize nested objects, maps and arrays
- Resolve references asynchronously (during deserialization)
- Supports inheritance
- Works on any ES5 environment (if ES3 is needed file a feature request)
- Convenience decorators for ESNext / Typescript
- Ships with typescript / flow typings
- Generic solution that works well with for example MobX out of the box
Non-features:
- Serializr is not an ORM or data management library. It doesn't manage object instances, provided api's like fetch, search etc. If you are building such a thing though, serializr might definitely take care of the serialization part for you :-).
- Serializr is not a MobX specific (de)serialization mechanism, it is generic and should fit work with any type of model objects
From npm:
npm install serializr --save
From CDN: https://unpkg.com/serializr which declares the global
serializr
object.Using decorators (optional)
With decorators (TypeScript or ESNext) building model schemas is even more trivial:
Decorator: Caveats
Babel 6.x does not allow decorators to self-reference during their creation, so the above code would not work for the Message class. Instead write:
Enabling decorators (optional)
TypeScript
Enable the compiler option
experimentalDecorators
in tsconfig.json
or pass it as flag --experimentalDecorators
to the compiler.Babel 7.x:
Install support for decorators:
npm i --save-dev @babel/plugin-proposal-class-properties @babel/plugin-proposal-decorators
. And enable it in your .babelrc
file:Babel 6.x:
Install support for decorators:
npm i --save-dev babel-plugin-transform-decorators-legacy
. And enable it in your .babelrc
file:Babel 5.x
Probably you have more plugins and presets in your
.babelrc
already, note that the order is important and transform-decorators-legacy
should come as first.The two most important functions exposed by serializr are
serialize(modelschema?, object) -> json tree
and deserialize(modelschema, json tree) -> object graph
.What are those model schemas?ModelSchema
The driving concept behind (de)serialization is a ModelSchema.It describes how model object instances can be (de)serialize to json.
A simple model schema looks like this:
The
factory
tells how to construct new instances during deserialization.The optional extends
property denotes that this model schema inherits its props from another model schema.The props section describes how individual model properties are to be (de)serialized. Their names match the model field names.The combination fieldname: true
is simply a shorthand for fieldname: primitive()
For convenience, model schemas can be stored on the constructor function of a class.This allows you to pass in a class reference wherever a model schema is required.See the examples below.
PropSchema
PropSchemas contain the strategy on how individual fields should be serialized.It denotes whether a field is a primitive, list, whether it needs to be aliased, refers to other model objects etc.PropSchemas are composable. See the API section below for the details, but these are the built-in property schemas:
primitive()
: Serialize a field as primitive valueidentifier()
: Serialize a field as primitive value, use it as identifier when serializing references (seereference
)date()
: Serializes dates (as epoch number)alias(name, propSchema)
: Serializes a field under a different namelist(propSchema)
: Serializes an array based collectionmap(propSchema)
: Serializes an Map or string key based collectionmapAsArray(propSchema, keyPropertyName)
: Serializes a map to an array of elementsobject(modelSchema)
: Serializes an child model elementreference(modelSchema, lookupFunction?)
: Serializes a reference to another model elementcustom(serializeFunction, deserializeFunction)
: Create your own property serializer by providing two functions, one that converts modelValue to jsonValue, and one that does the inverse- There is a special prop schema:
'*': true
that serializes all enumerable, non mentioned values as primitive
It is possible to define your own prop schemas. You can define your own propSchema by creating a function that returns an object with the following signature:
For inspiration, take a look at the source code of the existing ones on how they work, it is pretty straightforward.
Deserialization context
The context object is an advanced feature and can be used to obtain additional context-related information about the deserialization process.
context
is available as:- first argument of factory functions
- third argument of the lookup callback of
ref
prop schema's (see below) - third argument of the
deserializer
of a custom propSchema
When deserializing a model elememt / property, the following fields are available on the context object:
json
: Returns the complete current json object that is being deserializedtarget
: The object currently being deserialized. This is the object that is returned from the factory function.parentContext
: Returns the parent context of the current context. For example if a child element is being deserialized, thecontext.target
refers to the current model object, andcontext.parentContext.target
refers to the parent model object that owns the current model object.args
: If custom arguments were passed to thedeserialize
/update
function, they are available ascontext.args
.
AdditionalPropArgs
A PropSchema can be further parameterized using AdditionalPropArgs. Currently, they can be used to specify lifecycle functions. During deserialization they can be useful, e.g. in case you want to
- react to errors in the deserialization on a value level and retry with corrected value,
- remove invalid items e.g. in arrays or maps,
- react to changes in field names, e.g. due to schema migration (i.e. only one-directional changes that cannot be dealt with by alias operators).
It is possible to define those functions by passing them as additional property arguments to the propSchema during its creation.
A more detailed example can be found in test/typescript/ts.ts.
Table of Contents
- ModelSchema
- createSimpleSchema
- createModelSchema
- getDefaultModelSchema
- setDefaultModelSchema
- serializable
- serialize
- serializeAll
- cancelDeserialize
- deserialize
- update
- primitive
- identifier
- date
- alias
- custom
- object
- reference
- list
- map
- mapAsArray
- raw
- SKIP
ModelSchema
JSDOC type defintions for usage w/o typescript.
Type: object
Parameters
value
anywriteable
booleanget
(Function | undefined)set
(Function | undefined)configurable
booleanenumerable
booleansourcePropertyValue
anyjsonValue
anycallback
cpsCallbackcontext
ContextcurrentPropertyValue
anyid
anytarget
objectcontext
Contextresult
anyerror
anyid
stringcallback
cpsCallbackfactory
props
targetClass
Properties
serializer
serializerFunctiondeserializer
deserializerFunctionidentifier
boolean
Returns any any - serialized object
Returns any void
Returns any void
Returns any void
createSimpleSchema
Creates a model schema that (de)serializes from / to plain javascript objects.Its factory method is:
() => ({})
Parameters
props
object property mapping,
Examples
Returns object model schema
createModelSchema
Creates a model schema that (de)serializes an object created by a constructor function (class).The created model schema is associated by the targeted type as default model schema, see setDefaultModelSchema.Its factory method is
() => new clazz()
(unless overriden, see third arg).Parameters
clazz
(constructor | class) class or constructor functionprops
object property mappingfactory
function optional custom factory. Receives context as first arg
Examples
Returns object model schema
getDefaultModelSchema
Returns the standard model schema associated with a class / constructor function
Parameters
thing
object
Returns ModelSchema model schema
setDefaultModelSchema
Sets the default model schema for class / constructor function.Everywhere where a model schema is required as argument, this class / constructor functioncan be passed in as well (for example when using
object
or ref
.When passing an instance of this class to
serialize
, it is not required to pass the model schemaas first argument anymore, because the default schema will be inferred from the instance type.Parameters
clazz
(constructor | class) class or constructor functionmodelSchema
ModelSchema a model schema
Returns ModelSchema model schema
serializable
Decorator that defines a new property mapping on the default model schema for the classit is used in.
When using typescript, the decorator can also be used on fields declared as constructor arguments (using the
private
/ protected
/ public
keywords).The default factory will then invoke the constructor with the correct arguments as well.Parameters
arg1
arg2
arg3
Examples
Returns PropertyDescriptor
serialize
Serializes an object (graph) into json using the provided model schema.The model schema can be omitted if the object type has a default model schema associated with it.If a list of objects is provided, they should have an uniform type.
Parameters
arg1
modelschema to use. Optionalarg2
object(s) to serialize
Returns object serialized representation of the object
serializeAll
The
serializeAll
decorator can be used on a class to signal that all primitive properties should be serialized automatically.Parameters
target
cancelDeserialize
Cancels an asynchronous deserialization or update operation for the specified target object.
Parameters
instance
object that was previously returned from deserialize or update method
deserialize
Deserializes a json structure into an object graph.
This process might be asynchronous (for example if there are references with an asynchronouslookup function). The function returns an object (or array of objects), but the returned objectmight be incomplete until the callback has fired as well (which might happen immediately)
Parameters
schema
(object | array) to use for deserializationjson
json data to deserializecallback
function node style callback that is invoked once the deserialization hasfinished. First argument is the optional error, second argument is the deserialized object(same as the return value)customArgs
any custom arguments that are available ascontext.args
during thedeserialization process. This can be used as dependency injection mechanism to pass in, forexample, stores.
Returns (object | array) deserialized object, possibly incomplete.
update
Similar to deserialize, but updates an existing object instance.Properties will always updated entirely, but properties not present in the json will be kept as is.Further this method behaves similar to deserialize.
Parameters
modelSchema
object , optional if it can be inferred from the instance typetarget
object target instance to updatejson
object the json to deserializecallback
function the callback to invoke once deserialization has completed.customArgs
any custom arguments that are available ascontext.args
during the deserialization process. This can be used as dependency injection mechanism to pass in, for example, stores.
Returns (object | array) deserialized object, possibly incomplete.
primitive
Indicates that this field contains a primitive value (or Date) which should be serialized literally to json.
Parameters
additionalArgs
AdditionalPropArgs optional object that contains beforeDeserialize and/or afterDeserialize handlers
Examples
Returns ModelSchema
identifier
Similar to primitive, but this field will be marked as the identifier for the given Model type.This is used by for example
reference()
to serialize the referenceIdentifier accepts an optional
registerFn
with the signature:(id, target, context) => void
that can be used to register this object in some store. note that not all fields of this object mighthave been deserialized yet.Parameters
arg1
(RegisterFunction | AdditionalPropArgs) optional registerFn: function to register this object during creation.arg2
AdditionalPropArgs optional object that contains beforeDeserialize and/or afterDeserialize handlers
Examples
Returns PropSchema
date
Similar to primitive, serializes instances of Date objects
Parameters
additionalArgs
AdditionalPropArgs optional object that contains beforeDeserialize and/or afterDeserialize handlers
Returns PropSchema
alias
Alias indicates that this model property should be named differently in the generated json.Alias should be the outermost propschema.
Parameters
name
string name of the json field to be used for this propertypropSchema
PropSchema propSchema to (de)serialize the contents of this field
Examples
Returns PropSchema
custom
Can be used to create simple custom propSchema. Multiple things can be done inside of a custom propSchema, like deserializing and serializing other (polymorphic) objects, skipping the serialization of something or checking the context of the obj being (de)serialized.
The
custom
function takes two parameters, the serializer
function and the deserializer
function.The
serializer
function has the signature:(value, key, obj) => void
When serializing the object
{a: 1}
the serializer
function will be called with serializer(1, 'a', {a: 1})
.The
deserializer
function has the following signature for synchronous processing(value, context, oldValue) => void
For asynchronous processing the function expects the following signature
(value, context, oldValue, callback) => void
When deserializing the object
{b: 2}
the deserializer
function will be called with deserializer(2, contextObj)
(contextObj reference).Parameters
serializer
function function that takes a model value and turns it into a json valuedeserializer
function function that takes a json value and turns it into a model value. It also takes context argument, which can allow you to deserialize based on the context of other parameters.additionalArgs
AdditionalPropArgs optional object that contains beforeDeserialize and/or afterDeserialize handlers
Examples
Returns PropSchema
object
object
indicates that this property contains an object that needs to be (de)serializedusing its own model schema.N.B. mind issues with circular dependencies when importing model schema's from other files! The module resolve algorithm might expose classes before
createModelSchema
is executed for the target class.Parameters
modelSchema
ModelSchema to be used to (de)serialize the objectadditionalArgs
AdditionalPropArgs optional object that contains beforeDeserialize and/or afterDeserialize handlers
Examples
Returns PropSchema
reference
reference
can be used to (de)serialize references that point to other models.The first parameter should be either a ModelSchema that has an
identifier()
property (see identifier)or a string that represents which attribute in the target object represents the identifier of the object.The second parameter is a lookup function that is invoked during deserialization to resolve an identifier toan object. Its signature should be as follows:
lookupFunction(identifier, callback, context)
where:1. identifier
is the identifier being resolved2. callback
is a node style calblack function to be invoked with the found object (as second arg) or an error (first arg)3. context
see context.![Serialize Serialize](https://www.bennadel.com/resources/uploads/2017/json-stringify-will-recursively-call-tojson.png)
The lookupFunction is optional. If it is not provided, it will try to find an object of the expected type and required identifier within the same JSON document
N.B. mind issues with circular dependencies when importing model schemas from other files! The module resolve algorithm might expose classes before
createModelSchema
is executed for the target class.Parameters
target
: ModelSchema or stringlookupFn
(RefLookupFunction | AdditionalPropArgs) optional function or additionalArgs objectadditionalArgs
AdditionalPropArgs optional object that contains beforeDeserialize and/or afterDeserialize handlers
Examples
Returns PropSchema
list
List indicates that this property contains a list of things.Accepts a sub model schema to serialize the contents
Parameters
propSchema
PropSchema to be used to (de)serialize the contents of the arrayadditionalArgs
AdditionalPropArgs optional object that contains beforeDeserialize and/or afterDeserialize handlers
Examples
Returns PropSchema
map
Similar to list, but map represents a string keyed dynamic collection.This can be both plain objects (default) or ES6 Map like structures.This will be inferred from the initial value of the targetted attribute.
Parameters
propSchema
anyadditionalArgs
AdditionalPropArgs optional object that contains beforeDeserialize and/or afterDeserialize handlers
Returns PropSchema
mapAsArray
Similar to map, mapAsArray can be used to serialize a map-like collection where the key iscontained in the 'value object'. Example: consider Map<id: number, customer: Customer> where theCustomer object has the id stored on itself. mapAsArray stores all values from the map into anarray which is serialized. Deserialization returns a ES6 Map or plain object object where the
keyPropertyName
of each object is used for keys. For ES6 maps this has the benefit of beingallowed to have non-string keys in the map. The serialized json also may be slightly morecompact.Parameters
propSchema
anykeyPropertyName
string the property of stored objects used as key in the mapadditionalArgs
AdditionalPropArgs optional object that contains beforeDeserialize and/or afterDeserialize handlers
Returns PropSchema
raw
Indicates that this field is only need to putted in the serialized json ordeserialized instance, without any transformations. Stay with its original value
Parameters
additionalArgs
AdditionalPropArgs optional object that contains beforeDeserialize and/or afterDeserialize handlers
Examples
Returns ModelSchema
SKIP
In the event that a property needs to be deserialized, but not serialized, you can use the SKIP symbol to omit the property. This has to be used with the custom serializer.
Examples
1. Plain schema with plain objects
2. Create schema and store it on constructor
3. Create schema for simple argumentless constructors
4. Create schema for simple argumentless constructors using decorators
5. use custom factory methods to reuse model object instances
6. use custom arguments to inject stores to models
This pattern is useful to avoid singletons but allow to pass context specific data to constructors. This can be done by passing custom data to
deserialize
/ update
as last argument,which will be available as context.args
on all places where context is available:7. Putting it together: MobX store with plain objects, classes and internal references
- If MobX, optimize by leveraging createTransformer and transactions
- Support async serialization (future)
- Support ImmutableJS out of the box
- Make
'*': true
respect extends clauses
Filename extension | .json |
---|---|
Internet media type | application/json |
Type code | TEXT |
Uniform Type Identifier (UTI) | public.json |
Type of format | Data interchange |
Extended from | JavaScript |
Standard | STD 90/RFC8259, ECMA-404, ISO/IEC 21778:2017 |
Open format? | Yes |
Website | json.org |
In computing, JavaScript Object Notation (JSON) (/ˈdʒeɪsən/ 'Jason',[1][2]/ˈdʒeɪsɒn/) is an open-standardfile format that uses human-readable text to transmit data objects consisting of attribute–value pairs and array data types (or any other serializable value). It is a very common data format used for asynchronous browser–server communication, including as a replacement for XML in some AJAX-style systems.[3]
JSON is a language-independent data format. It was derived from JavaScript, but many modern programming languages include code to generate and parse JSON-format data. The official Internet media type for JSON is
application/json
. JSON filenames use the extension .json
.Douglas Crockford originally specified the JSON format in the early 2000s. It was first standardized in 2013 in RFC7158 and ECMA-404.[4] The latest JSON format standard was published in 2017 as RFC8259, and remains consistent with ECMA-404.[5] That same year, JSON was also standardized as ISO/IEC 21778:2017.[6] The ECMA and ISO standards describes only the allowed syntax, whereas the RFC covers some security and interoperability considerations.[7]
- 2Data types and syntax
- 2.3Using JSON in JavaScript
- 3Schema and metadata
- 6Applications
- 8Comparison with other formats
- 8.3Samples
History[edit]
Douglas Crockford at the Yahoo Building. (2007)
JSON grew out of a need for stateless, real-time server-to-browser communication protocol without using browser plugins such as Flash or Java applets, the dominant methods used in the early 2000s.[8]
Douglas Crockford first specified and popularized the JSON format.[9] The acronym originated at State Software, a company co-founded by Crockford and others in March 2001. The co-founders agreed to build a system that used standard browser capabilities and provided an abstraction layer for Web developers to create stateful Web applications that had a persistent duplex connection to a Web server by holding two Hypertext Transfer Protocol (HTTP) connections open and recycling them before standard browser time-outs if no further data were exchanged. The co-founders had a round-table discussion and voted whether to call the data format JSML or JSON, as well as under what license type to make it available. Crockford added a clause to the JSON license stating that 'The Software shall be used for Good, not Evil,' in order to open-source the JSON libraries while mocking corporate lawyers and those who are overly pedantic. Chip Morningstar developed the idea for the State Application Framework at State Software.[10][11] On the other hand, this clause led to license compatibility problems of the JSON license with other open-source licenses.[12]
A precursor to the JSON libraries was used in a children's digital asset trading game project named Cartoon Orbit at Communities.com (the State co-founders had all worked at this company previously) for Cartoon Network, which used a browser side plug-in with a proprietary messaging format to manipulate DHTML elements (this system is also owned by 3DO). Upon discovery of early Ajax capabilities, digiGroups, Noosh, and others used frames to pass information into the user browsers' visual field without refreshing a Web application's visual context, realizing real-time rich Web applications using only the standard HTTP, HTML and JavaScript capabilities of Netscape 4.0.5+ and IE 5+. Crockford then found that JavaScript could be used as an object-based messaging format for such a system. The system was sold to Sun Microsystems, Amazon.com and EDS. The JSON.org[13] website was launched in 2002. In December 2005, Yahoo! began offering some of its Web services in JSON.[14]
JSON was originally intended to be a subset of the JavaScript scripting language (specifically, Standard ECMA-262 3rd Edition—December 1999[15][need quotation to verify]) and is commonly used with Javascript, but it is a language-independent data format. Code for parsing and generating JSON data is readily available in many programming languages. JSON's website lists JSON libraries by language.
Though JSON was originally advertised and believed to be a strict subset of JavaScript and ECMAScript,[16][failed verification] it inadvertently allows some unescaped characters in strings that are illegal in JavaScript and ECMAScript string literals. See Data portability issues below.
JSON itself became an ECMA international standard in 2013 as the ECMA-404 standard.[17]In the same year RFC7158 used ECMA-404 as reference. In 2014 RFC7159 became the main reference for JSON's internet uses, superseding RFC4627 and RFC7158 (but preserving ECMA-262 and ECMA-404 as main references). ISO/IEC JTC 1/SC 22 published ISO/IEC 21778:2017[6] as an international standard in November 2017. In December 2017, RFC7159 was made obsolete by RFC8259.
Data types and syntax[edit]
JSON's basic data types are:
- Number: a signed decimal number that may contain a fractional part and may use exponential E notation, but cannot include non-numbers such as NaN. The format makes no distinction between integer and floating-point. JavaScript uses a double-precision floating-point format for all its numeric values, but other languages implementing JSON may encode numbers differently.
- String: a sequence of zero or more Unicode characters. Strings are delimited with double-quotation marks and support a backslash escaping syntax.
- Boolean: either of the values
true
orfalse
- Array: an ordered list of zero or more values, each of which may be of any type. Arrays use square bracket notation with comma-separated elements.
- Object: an unordered collection of name–value pairs where the names (also called keys) are strings. Since objects are intended to represent associative arrays,[17] it is recommended, though not required,[18] that each key is unique within an object. Objects are delimited with curly brackets and use commas to separate each pair, while within each pair the colon ':' character separates the key or name from its value.
null
: An empty value, using the wordnull
Whitespace is allowed and ignored around or between syntactic elements (values and punctuation, but not within a string value). Four specific characters are considered whitespace for this purpose: space, horizontal tab, line feed, and carriage return. In particular, the byte order mark must not be generated by a conforming implementation (though it may be accepted when parsing JSON). JSON does not provide syntax for comments.
Early versions of JSON (such as specified by RFC4627) required that a valid JSON text must consist of only an object or an array type, which could contain other types within them.
Example[edit]
The following example shows a possible JSON representation describing a person.
Data portability issues[edit]
Although Douglas Crockford originally asserted that JSON is a strict subset of JavaScript, his specification actually allows valid JSON documents that are invalid JavaScript; JSON allows the Unicode line terminatorsU+2028LINE SEPARATOR and U+2029PARAGRAPH SEPARATOR to appear unescaped in quoted strings, while ECMAScript 2018 and older does not.[19][20] This is a consequence of JSON disallowing only 'control characters'. For maximum portability, these characters should be backslash-escaped. This subtlety is important when generating JSONP.
JSON exchange in an open ecosystem must be encoded in UTF-8.[5] The encoding supports the full Unicode character set, including those characters outside the Basic Multilingual Plane (U+10000 to U+10FFFF). However, if escaped, those characters must be written using UTF-16 surrogate pairs, a detail missed by some JSON parsers. For example, to include the Emoji character U+1F602?FACE WITH TEARS OF JOY in JSON:
Numbers in JSON are agnostic with regard to their representation within programming languages. While this allows for numbers of arbitrary precision to be serialized, it may lead to portability issues. For example, since no differentiation is made between integer and floating-point values, some implementations may treat
42
, 42.0
, and 4.2E+1
as the same number, while others may not. The JSON standard make no requirements regarding implementation details such as overflow, underflow, loss of precision, rounding, or signed zeros, but it does recommend to expect no more than IEEE 754binary64 precision for 'good interoperability'. There is no inherent precision loss in serializing a machine-level binary representation of a floating-point number (like binary64) into a human-readable decimal representation (like numbers in JSON), and back, since there exist published algorithms to do this exactly and optimally.[21]Comments were purposefully excluded from JSON. In 2012, Douglas Crockford described his design decision thusly: 'I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability.' [22]
Using JSON in JavaScript[edit]
As of 2018, all major browsers support at least the fifth edition ECMAScript which provides a method of decoding JSON:[23]
Unsupported native data types[edit]
JavaScript syntax defines several native data types that are not included in the JSON standard:[18] Map, Set, Date, Error, Regular Expression, Function, Promise, and
undefined
.[note 1] These JavaScript data types must be represented by some other data format, with the programs on both ends agreeing on how to convert between the types. As of 2011, there are some de facto standards, e.g., converting from Date to String, but none universally recognized.[24][25] Other languages may have a different set of native types that must be serialized carefully to deal with this type of conversion.Schema and metadata[edit]
JSON Schema[edit]
JSON Schema specifies a JSON-based format to define the structure of JSON data for validation, documentation, and interaction control. It provides a contract for the JSON data required by a given application, and how that data can be modified.[26]
JSON Schema is based on the concepts from XML Schema (XSD), but is JSON-based. As in XSD, the same serialization/deserialization tools can be used both for the schema and data; and is self-describing. It is specified in an Internet Draft at the IETF, currently in its 7th draft, which was released on March 18, 2018.[27] There are several validators available for different programming languages,[28] each with varying levels of conformance.
There is no standard file extension, but some have suggested
.schema.json
.[29]Example JSON Schema (draft 4):
The JSON Schema above can be used to test the validity of the JSON text below:
MIME type[edit]
The official MIME type for JSON text is '
application/json
',[30] and most modern implementations have adopted this.The unofficial MIME type '
text/json
' or the content-type 'text/javascript
' also get legacy support by many service providers, browsers, servers, web applications, libraries, frameworks, and APIs. Notable examples include the Google Search API,[31] Yahoo!,[31][32] Flickr,[31] Facebook API,[33]Lift framework,[34] Dojo Toolkit 0.4,[35] etc.Object references[edit]
The JSON standard does not support object references, but an IETF draft standard for JSON-based object references exists.[36] The Dojo Toolkit supports object references using standard JSON; specifically, the
dojox.json.ref
module provides support for several forms of referencing including circular, multiple, inter-message, and lazy referencing. Internally both do so by assigning a '$ref'
key for such references and resolving it at parse-time; the IETF draft only specifies the URL syntax, but Dojo allows more.[37][38][39]Alternatively, non-standard solutions exist such as the use of Mozilla JavaScript Sharp Variables. However this functionality became obsolete with JavaScript 1.8.5 and was removed in Firefox version 12.[40]
Applications[edit]
JSON-RPC[edit]
JSON-RPC is a remote procedure call (RPC) protocol built on JSON, as a replacement for XML-RPC or SOAP. It is a simple protocol that defines only a handful of data types and commands. JSON-RPC lets a system send notifications (information to the server that does not require a response) and multiple calls to the server that can be answered out of order.Example of a JSON-RPC 2.0 request and response using positional parameters.
AJAJ[edit]
Asynchronous JavaScript and JSON (or AJAJ) refers to the same dynamic web page methodology as Ajax, but instead of XML, JSON is the data format. AJAJ is a web development technique that provides for the ability of a webpage to request new data after it has loaded into the web browser. Typically it renders new data from the server in response to user actions on that webpage. For example, what the user types into a search box, client-side code then sends to the server, which immediately responds with a drop-down list of matching database items.
The following JavaScript code is an example of a client using XMLHttpRequest to request data in JSON format from a server. (The server-side programming is omitted; it must be set up to service requests to the
url
containing a JSON-formatted string.)As a configuration language[edit]
While JSON is a data serialization format, it has seen ad hoc usage as a configuration language. In this use case, support for comments and other features have been deemed useful, which has led to several nonstandard JSON supersets being created. Among them HJSON[41], HOCON, and JSON5 (which despite its name, isn't the fifth version of JSON).[42][43]
In 2012, Douglas Crockford had this to say about comments in JSON when used as a configuration language: 'I know that the lack of comments makes some people sad, but it shouldn't. Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.'[22]
Security considerations[edit]
JSON is intended as a data serialization format. However, its design as a non-strict subset of JavaScript can lead to the misconception that it is safe to pass JSON texts to the JavaScript
eval()
function. This is not safe, due to the fact that certain valid JSON texts, specifically those containing U+2028 or U+2029, are actually not valid JavaScript code.[44]To avoid the many pitfalls caused by executing arbitrary code from the internet, a new function,
JSON.parse()
was first added to the fifth edition of ECMAScript[45], which as of 2017 is supported by all major browsers. For non-supported browsers, an API-compatible JavaScript library is provided by Douglas Crockford.[46] In addition, the TC39 proposal 'Subsume JSON' made ECMAScript a strict JSON superset as of the language's 2019 revision.[47][48]Various JSON parser implementations have suffered from denial-of-service attack and mass assignment vulnerability.[49][50]
Comparison with other formats[edit]
JSON is promoted as a low-overhead alternative to XML as both of these formats have widespread support for creation, reading, and decoding in the real-world situations where they are commonly used.[51] Apart from XML, examples could include CSV and YAML (a superset of JSON). Also, Google Protocol Buffers can fill this role, although it is not a data interchange language.
YAML[edit]
YAML version 1.2 is a superset of JSON; prior versions were 'not strictly compatible'. For example, escaping a slash (/) with a backslash () is valid in JSON, but was not valid in YAML. (This is common practice when injecting JSON into HTML to protect against cross-site scripting attacks.) Nonetheless, many YAML parsers can natively parse the output from many JSON encoders.[52]
YAML supports comments, but JSON does not.[42]
XML[edit]
XML has been used to describe structured data and to serialize objects. Various XML-based protocols exist to represent the same kind of data structures as JSON for the same kind of data interchange purposes. Data can be encoded in XML in several ways. The most expansive form using tag pairs results in a much larger representation than JSON, but if data is stored in attributes and 'short tag' form where the closing tag is replaced with '/>', the representation is often about the same size as JSON or just a little larger. However, an XML attribute can only have a single value and each attribute can appear at most once on each element.
XML separates 'data' from 'metadata' (via the use of elements and attributes), while JSON does not have such a concept.
Another key difference is the addressing of values. JSON has objects with a simple 'key' → 'value' mapping, whereas in XML addressing happens on 'nodes', which all receive a unique ID via the XML processor. Additionally, the XML standard defines a common attribute 'xml:id', that can be used by the user, to set an ID explicitly.
XML tag names cannot contain any of the characters !'#$%&'()*+,/;<=>?@[]^`{|}~, nor a space character, and cannot begin with '-', '.', or a numeric digit, whereas JSON keys can (even if quotation mark and reverse solidus must be escaped).[53]
XML values are strings of characters, with no built-in type safety. XML has the concept of schema, that permits strong typing, user-defined types, predefined tags, and formal structure, allowing for formal validation of an XML stream. JSON has strong typing built-in, and has a similar schema concept in JSON Schema.
XML supports comments, but JSON does not.[54]
Samples[edit]
JSON sample[edit]
Both of the following examples carry the same kind of information as the JSON example above in different ways, except that XML doesn't carry the data type. More JSON Examples.
YAML sample[edit]
The JSON text above is also entirely valid YAML. YAML also offers an alternative syntax intended to be more human-accessible by replacing nested delimiters like
{}
, []
, and '
marks with indentation.[52]XML samples[edit]
Note that the XML examples below don't encode the data type (e.g. that age is a number), and would need something like a schema to encode the same information as the JSON example above does as is. Note that the tag names are in camelCase, since XML tag names cannot have spaces in them (in contrast to JSON and YAML keys).[53]
The properties can also be serialized using attributes instead of tags:
See also[edit]
- JSON streaming – on delimiting JSON in stream protocols
- Related formats
- GeoJSON – an open format for encoding a variety of geographic data structures
- JSON-LD – JavaScript object notation for linked data, a W3C recommendation
- JSON-RPC – remote procedure call protocol encoded in JSON
- JsonML – markup language used to map between XML and JSON
- S-expression – the comparable LISP format for trees as text.
- SOAPjr – a hybrid of SOAP and JR (JSON-RPC)
- Related binary encodings
- BSON – with data types of specific interest to MongoDB
- CBOR – loosely based on JSON
- MessagePack – with data types loosely corresponding with JSON's
- Smile – based on JSON
- UBJSON – binary format directly imitating JSON
- EXI4JSON (EXI for JSON) – representation by means of the Efficient XML Interchange (EXI) standard
- Implementations:
- Jackson – JSON processor for Java
Notes[edit]
- ^The
undefined
type was left out of the JSON standard, and one finds suggestions thatnull
be used instead.In fact, the current standard says that for a sparse array such as:which behaves in JavaScript as if it were:with theundefined
entries being only implicit rather than explicit, should translate to JSON as if it were:with explicitnull
fillers for the undefined entries.Furthermore, in JavaScript{a: undefined}
often behaves the same as{}
. Both translate as'{}'
in JSON. Howeverundefined
as an explicit property value does have use in JavaScript inheritance situations such as:where the inheritance ofx
's propertya
is overridden inxi
and makes it pretty much behave as if nothing was inherited.JSON.stringify
itself ignores inherited values - it only translates the enumerable own properties as given byObject.keys(y)
. The default stringification, while not encoding inheritance, can (except forundefined
values) encode enough of an object to reconstruct it in an environment that knows what inheritance it should have.To encode JavaScript objects that contain explicitundefined
values a convention for representingundefined
must be established, such as mapping it to the string'UNDEFINED'
. One can then passJSON.stringify
the optionalreplacer
argument to translate with this convention:Converting this JSON back into JavaScript is not as straightforward. WhileJSON.parse
can take an optionalreviver
argument that is, essentially, the inverse of areplacer
, it can't be used in this situation. If that function returnsundefined
, theJSON.parse
logic interprets this to mean to not define a property rather than define one with aundefined
value. Instead one has to explicitly post process the result fromJSON.parse
replacing each'UNDEFINED'
withundefined
.
References[edit]
- ^'Doug Crockford 'Google Tech Talks: JavaScript: The Good Parts''. 7 February 2009.
- ^'Douglas Crockford: pronouncing'. Nov 14, 2014.
- ^'A Modern Reintroduction To AJAX'. Retrieved 12 April 2017.
- ^'Standard ECMA-404'. www.ecma-international.org.
- ^ ab'The JavaScript Object Notation (JSON) Data Interchange Format'. IETF. December 2017. Retrieved 16 February 2018.
- ^ ab14:00-17:00. 'ISO/IEC 21778:2017'. ISO. Retrieved 2019-07-29.
- ^Bray, Tim. 'JSON Redux AKA RFC8259'. Ongoing. Retrieved 16 March 2014.
- ^'Unofficial Java History'. Edu4Java. 26 May 2014. Archived from the original(html) on 26 May 2014. Retrieved 30 August 2019.
In 1996 , Macromedia launches Flash technology which occupies the space left by Java and ActiveX, becoming the de facto standard for animation on the client side.
- ^'Douglas Crockford — The JSON Saga'. YouTube. 28 August 2011. Retrieved 23 September 2016.
- ^'Chip Morningstar Biography'. n.d.
- ^'State Software Breaks Through Web App Development Barrier With State Application Framework: Software Lets Developers Create Truly Interactive Applications; Reduces Costs, Development Time and Improves User Experience'. PR Newswire. February 12, 2002. Archived from the original on June 5, 2013. Retrieved March 19, 2013.Cite uses deprecated parameter
|dead-url=
(help) - ^Apache and the JSON license on LWN.net by Jake Edge (November 30, 2016)
- ^'JSON'. json.org.
- ^Yahoo!. 'Using JSON with Yahoo! Web services'. Archived from the original on October 11, 2007. Retrieved July 3, 2009.
- ^Crockford, Douglas (May 28, 2009). 'Introducing JSON'. json.org. Retrieved July 3, 2009.
- ^Douglas Crockford (2016-07-10). 'JSON in JavaScript'. Archived from the original on 2016-07-10. Retrieved 2016-08-13.Cite uses deprecated parameter
|deadurl=
(help)CS1 maint: BOT: original-url status unknown (link) - ^ ab'The JSON Data Interchange Format'(PDF). ECMA International. October 2013. Retrieved 23 September 2016.
- ^ ab'JSON Web Token (JWT)'. IETF. May 2015. Retrieved 23 September 2016.
- ^Holm, Magnus (15 May 2011). 'JSON: The JavaScript subset that isn't'. The timeless repository. Retrieved 23 September 2016.
- ^'TC39 Proposal: Subsume JSON'. ECMA TC39 committee. 22 May 2018.
- ^Andrysco, Marc; Jhala, Ranjit; Lerner, Sorin. 'Printing Floating-Point Numbers - An Always Correct Method'(PDF). Retrieved 2019-07-27.
- ^ abCrockford, Douglas (2012-04-30). 'Comments in JSON'. Archived from the original on 2015-07-04.
I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't. Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
Cite uses deprecated parameter|deadurl=
(help) - ^'Standard ECMA-262'. ecma-international.org. Retrieved 13 September 2015.
- ^'jquery - Format a Microsoft JSON date? - Stack Overflow'. stackoverflow.com. Retrieved 13 September 2015.
- ^'Tales from the Evil Empire - Dates and JSON'. asp.net. Retrieved 13 September 2015.
- ^'JSON Schema and Hyper-Schema'. json-schema.org. Retrieved 13 September 2015.
- ^'draft-handrews-json-schema-01 - JSON Schema: A Media Type for Describing JSON Documents'. json-schema.org/. 2018-03-19. Retrieved 10 February 2019.
- ^'JSON Schema Implementations'. json-schema.org. Retrieved 10 February 2019.
- ^'Json Schema file extension'. Stack Overflow.
- ^'Media Types'. iana.org. Retrieved 13 September 2015.
- ^ abc'Handle application/json & text/json by benschwarz · Pull Request #2 · mislav/faraday-stack'. GitHub. Retrieved 13 September 2015.
- ^'Yahoo!, JavaScript, and JSON'. ProgrammableWeb. 2005-12-16. Retrieved 13 September 2015.
- ^'Make JSON requests allow text/javascript content by jakeboxer · Pull Request #148 · AFNetworking/AFNetworking'. GitHub. Retrieved 13 September 2015.
- ^'lift/Req.scala at master · lift/lift · GitHub'. GitHub. Retrieved 13 September 2015.
- ^'BrowserIO.js in legacy/branches/0.4/src/io – Dojo Toolkit'. dojotoolkit.org. Retrieved 13 September 2015.
- ^Zyp, Kris (September 16, 2012). Bryan, Paul C. (ed.). 'JSON Reference: draft-pbryan-zyp-json-ref-03'. Internet Engineering Task Force.
- ^Zyp, Kris. 'dojox.json.ref'. Dojo.
- ^Zyp, Kris (June 17, 2008). 'JSON referencing in Dojo'. SitePen. Retrieved July 3, 2009.
- ^von Gaza, Tys (Dec 7, 2010). 'JSON referencing in jQuery'. NUBUNTU. Archived from the original on May 7, 2015. Retrieved Dec 7, 2010.Cite uses deprecated parameter
|deadurl=
(help) - ^'Sharp variables in JavaScript'. Mozilla Developer Network. April 4, 2015. Retrieved 21 April 2012.
- ^Edelman, Jason; Lowe, Scott; Oswalt, Matt. Network Programmability and Automation. O'Reilly Media.
for data representation you can pick one of the following: YAML, YAMLEX, JSON, JSON5, HJSON, or even pure Python
- ^ abMcCombs, Thayne. 'Why JSON isn't a good configuration language'. Lucid Chart. Retrieved 15 June 2019.
- ^'HOCON (Human-Optimized Config Object Notation)'. GitHub. 2019-01-28. Retrieved 2019-08-28.
The primary goal is: keep the semantics (tree structure; set of types; encoding/escaping) from JSON, but make it more convenient as a human-editable config file format.
- ^'JSON: The JavaScript subset that isn't'. Magnus Holm. Retrieved 16 May 2011.
- ^'ECMAScript Fifth Edition'(PDF). Archived from the original(PDF) on April 14, 2011. Retrieved March 18, 2011.Cite uses deprecated parameter
|dead-url=
(help) - ^'douglascrockford/JSON-js'. GitHub. 2019-08-13.
- ^'Subsume JSON: Proposal to make all JSON text valid ECMA-262'. Ecma TC39. 23 August 2019. Retrieved 27 August 2019.
- ^'Advance to Stage 4 - tc39/proposal-json-superset'. GitHub. May 22, 2018.
- ^'Denial of Service and Unsafe Object Creation Vulnerability in JSON (CVE-2013-0269)'. Retrieved January 5, 2016.
- ^'Microsoft .NET Framework JSON Content Processing Denial of Service Vulnerability'. Retrieved January 5, 2016.
- ^'JSON: The Fat-Free Alternative to XML'. json.org. Retrieved 14 March 2011.
- ^ ab'YAML Ain't Markup Language (YAML™) Version 1.2'. yaml.org. Retrieved 13 September 2015.
- ^ ab'XML 1.1 Specification'. World Wide Web Consortium. Retrieved 2019-08-26.
- ^Saternos, Casimir (2014). Client-server web apps with Javascript and Java. p. 45. ISBN9781449369316.
External links[edit]
- 'ECMA-404 JSON Data Interchange Format'(PDF). ECMA Int'l.
- RFC8259, JSON Data Interchange Format
Retrieved from 'https://en.wikipedia.org/w/index.php?title=JSON&oldid=914741540'