Table of Contents
I. Introduction ........................................................................................................................ 2
Overview
Changes From Previous Versions
Limitations
Installation
Consoles and Other Unmapped Platforms
Unsupported Platforms
II. Working with the Defaults ............................................................................................... 5
Modifying Default Serialization Settings
Built-in Json Converters
III. Serializing and Deserializing Data ................................................................................. 7
Basic Serialization and Deserialization
Serialization and Deserialization using Converters
Custom Object Creation with CustomCreationConverter
IV. Customizing Serialization Settings .............................................................................. 12
Providing Custom Serialization Settings
V. Using Json Attributes ...................................................................................................... 15
JsonConverter Attribute
JsonProperty Attribute
JsonIgnore Attribute
Additional Attributes
VI. Advanced Serialization and Deserialization ............................................................... 17
Json Without a Matching Class
Serializing With Interfaces or Base / Inherited Classes
VII. Creating a Custom JsonConverter ............................................................................... 20
VIII. Binary Serialization with BSON ..................................................................................... 21
IX. Appendix A: Platform DLL Mapping ........................................................................... 23
X. Appendix B: JSON Structure Primer ........................................................................... 24
XI. Developer Support Contact .......................................................................................... 25
Introduction
Overview
Json .Net for Unity is a port of the official Json .Net library. It was created to bring the power of Json .Net to Unity as
the official library is not compatible with most Unity platforms and is not compatible with any platform using IL2CPP
builds. The aim of this document is to provide clear usage examples and technical explanation for Unity developers
and should be fairly easy to understand whether you are a novice or seasoned developer. It does not detail every
feature of Json .Net. Comprehensive documentation can be found on the official Json .Net help page.
As the official Json .Net does not support Unity, any questions or problems related to this asset should be sent to us.
Changes From Previous Versions
There are some important changes in Json .Net for Unity 2.0. Currently we are no longer supporting Unity versions
prior to Unity 5. This was a design decision made keep the asset clean. Prior versions of Unity did not allow mapping
of DLLs to different target platforms. This meant that Json .Net for Unity had to be included in the project as full
source code as it relies heavily on compiler directives to compile the correct code for each target platform.
Additionally, this approach made supporting new platforms extremely difficult. Json .Net for Unity was previously
based on an old (4.x) version of Json .Net and bug fixes and modifications were patched in over time. This made
updating the profile extremely difficult and it also meant that in order to support new platforms, complete new
versions of Json .Net had to be ported which was the reason for the WinRT folder (it was actually an entirely different
version of Json .Net).
As of version 2.0, Json .Net for Unity is making better use of branching strategies. It started with a clean slate, and a
brand new clean clone from the official repository. Bug fixes in the official repository can more easily be migrated to
Json .Net for Unity, while Unity specific enhancements can continue to be made.
Source code is still provided in an included .zip archive. This code includes a Visual Studio solution which divides a
single code base into multiple projects. This will be discussed in more detail later in this document.
Additionally, we have also removed support for WebPlayer as it is being deprecated by Unity and is no longer
supported in most modern browsers and tentatively removed support for Windows Phone 8.1 in favor of Windows 10
UWP.
Limitations
Some built in Unity objects are not directly supported. These include GameObjects and anything that inherits from
Monobehavior. There are a few reasons for this. There is limited utility in directly serializing a GameObject because
you can’t simply “new” one up. They need to be added to the scene by instiantiating. For this reason you couldn’t
deserialize one. This is necessary also to maintain the parent / child relationship. Unity also overrides the equality
check (== operator) for some objects so they pretend to be null even when they really aren’t. These properties (such
as rigidbody) have been deprecated, however they are visible via reflection and the serializer will attempt to serialize
them which will result in Unity throwing an exception. You can create your own proxy classes to serialize these,
however and then repopulate them once they are instantiated.
Installation
As of version 2.0, the structure of Json .Net for Unity has changed. This change provides a cleaner folder structure
with less “noise” and make it easier to identify and use. Due to API differences between Unity target platforms, the
asset is compiled into multiple DLLs. These DLLs are mapped to various platform targets.
It is always recommended that you delete your existing /JsonDotNet folder before importing a new version. This
ensures that you get a clean version. Once the new package is imported you will have the following folder structure:
In addition to the compressed source and assemblies, Json .Net for Unity includes its own link.xml file. This file is
used to prevent Unity from stripping built in classes that Json .Net uses. As new stripping issues are discovered, this
file will be updated. If you wish to add your own items it is recommended that you do so in your own link.xml file
outside of the /JsonDotNet folder to ensure they aren’t overwritten when the asset is updated.
Finally, the destination folder for Json .Net is not important. You may move the asset to any folder you desire. Just
make sure the link.xml file is retained. If you move the files from outside of Unity you will also need to re-map the
DLLs to their appropriate platforms. There is a mapping guide at the end of this document to assist you with
mapping the DLLs to the proper target platform.
Consoles and Other Unmapped Platforms
Consoles and most other unmapped platforms are supported out of the box, however they require access to their
respective SDKs and specialized Unity builds in order to map the appropriate DLLs for the platform. For all consoles
(and nearly all other cases), these platforms should be mapped to the
/JsonDotNet/Assemblies/Aot/Newtonsoft.Json.dll file. In order to map this file, select the DLL in the inspector. Find
the proper platform(s) in the platform list and select it. Some platforms require a “placeholder” DLL which is used in
the editor and pre-build. If the Placeholder option is present, click the dropdown and choose
the ../Assemblies/Standalone/Newtonsoft.Json.dll assembly. Click “Apply” and you should be ready to build.
When in doubt, please see the Platform DLL Mapping Guide at the end of this document. If you are having trouble
with a particular platform, contact us and we would be happy to help.
Unsupported Platforms
Json .Net for Unity does not support legacy Unity platforms such as Blackberry or Flash. As of version 2.0 we also no
longer support Webplayer, Windows 8.0 or Windows Phone 8.0. Windows 8.1 and 8.1 Universal are supported for the
8.1 SDK. This version currently does not support Windows Phone 8.1 out of the box. It may be possible to create a
build for it if necessary.
