A powerful Unity tool for seamless bidirectional conversion between JSON and ScriptableObjects. Create, edit, save, and load JSON data directly in the Unity Editor with full serialization support.
JSONSO now uses string-backed JSON storage to avoid Unity's serialization depth limit of 10 levels. This means:
- ✅ No depth limit - Store deeply nested JSON structures without warnings
- ✅ Compact .asset files - JSON stored as readable string instead of verbose Unity serialization
- ✅ Better git diffs - Changes are human-readable JSON text
- ✅ Lazy loading - JsonValue tree is built on-demand for better performance
Note:
JsonValueis no longer Unity-serializable. UseJsonScriptableObjectDatato store JSON data, which handles serialization automatically via string storage.
- 🔄 Bidirectional Conversion - Convert ScriptableObjects to JSON and vice versa
- 📝 Dynamic JSON Data - Create flexible JSON structures without predefined classes
- 🎨 Custom Editor - Visual tree-view editor for JSON data manipulation
- 💾 File I/O - Save and load JSON files directly from ScriptableObjects
- 🔗 Object Mapping - Map any C# object to a ScriptableObject and back
- 📦 Unity Serialization - Full support for Unity's serialization system
- 🎯 Type Safe - Strongly typed value access with
JsonValue
- Open Package Manager in Unity (
Window > Package Manager) - Click the
+button and selectAdd package from git URL... - Enter the following URL:
https://github.com/xavierarpa/JSONSO.git- Download the latest
.unitypackagefrom Releases - Import it into your Unity project (
Assets > Import Package > Custom Package)
- Download or clone the repository
- Copy the
JSONSOfolder into your project'sAssetsfolder
Right-click in the Project window and select Create > JSONSO > Json Data to create a new JSON data asset.
usingJSONSO;usingUnityEngine;publicclassExample:MonoBehaviour{publicJsonScriptableObjectDatajsonData;voidStart(){// Set values directlyjsonData["playerName"]="Hero";jsonData["level"]=25;jsonData["isActive"]=true;// Create nested objectsjsonData["stats"]=JsonValue.Object();jsonData["stats"]["health"]=100;jsonData["stats"]["mana"]=50;jsonData["stats"]["strength"]=15;// Create arraysjsonData["inventory"]=JsonValue.Array();jsonData["inventory"].Add("sword");jsonData["inventory"].Add("shield");jsonData["inventory"].Add("potion");// Convert to JSON stringstringjson=jsonData.ToJson(prettyPrint:true);Debug.Log(json);}}Output:
{
"playerName": "Hero",
"level": 25,
"isActive": true,
"stats": {
"health": 100,
"mana": 50,
"strength": 15
},
"inventory": ["sword", "shield", "potion"]
}Inherit from JsonScriptableObject to create your own typed ScriptableObjects with JSON support:
usingJSONSO;usingUnityEngine;[CreateAssetMenu(fileName="PlayerData",menuName="Game/Player Data")]publicclassPlayerData:JsonScriptableObject{publicstringplayerName;publicintlevel;publicfloatexperience;publicboolisPremium;protectedoverridevoidOnBeforeSerialize(){// Called before converting to JSON// Useful for data preparation}protectedoverridevoidOnAfterDeserialize(){// Called after loading from JSON// Useful for validation}}// Convert ScriptableObject to JSONstringjson=playerData.ToJson(prettyPrint:true);// Load JSON into ScriptableObjectplayerData.FromJson(jsonString);// Save to fileplayerData.SaveToFile("path/to/player.json");// Load from fileplayerData.LoadFromFile("path/to/player.json");Convert any C# object to a ScriptableObject:
// Your existing classpublicclassGameSave{publicstringsaveName;publicintscore;publicfloatplayTime;}// Load object data into ScriptableObjectvargameSave=newGameSave{saveName="Save1",score=1000,playTime=3600f};playerData.LoadFromObject(gameSave);// Convert ScriptableObject to objectGameSaveloadedSave=playerData.ToObject<GameSave>();| Method | Description |
|---|---|
ToJson(bool prettyPrint) | Converts the ScriptableObject to a JSON string |
FromJson(string json) | Loads data from a JSON string |
ToObject<T>() | Converts to an object of type T |
LoadFromObject(object obj) | Loads data from any object |
SaveToFile(string path) | Saves to a JSON file |
LoadFromFile(string path) | Loads from a JSON file |
| Property/Method | Description |
|---|---|
Root | The root JsonValue object (lazy-loaded from string) |
this[string key] | Direct access to root properties |
HasKey(string key) | Checks if a key exists |
Remove(string key) | Removes a key |
Count | Number of root properties |
Clear() | Clears all data |
MarkDirty() | Marks cache as modified (call after direct Root changes) |
FlushToString() | Forces immediate serialization to string |
RawJson | Gets the raw JSON string for debugging |
| Factory Method | Description |
|---|---|
JsonValue.Null() | Creates a null value |
JsonValue.String(value) | Creates a string value |
JsonValue.Number(value) | Creates a numeric value |
JsonValue.Bool(value) | Creates a boolean value |
JsonValue.Object() | Creates an empty object (dictionary) |
JsonValue.Array() | Creates an empty array |
JsonValue.Parse(json) | Parses a JSON string |
| Property | Description |
|---|---|
Type | The JsonValueType of this value |
AsString | Gets as string |
AsFloat | Gets as float |
AsInt | Gets as int |
AsBool | Gets as bool |
AsObject | Gets as Dictionary<string, JsonValue> |
AsArray | Gets as List |
IsNull | Checks if null |
IsObject | Checks if object |
IsArray | Checks if array |
publicenumJsonValueType{Null,String,Number,Boolean,Object,// Nested dictionaryArray// List of JsonValues}The custom editor provides:
- Visual Tree View - Navigate and edit nested JSON structures
- Add Property Button - Easily add new properties
- Type Selection - Change value types on the fly
- JSON Preview - See the raw JSON output
- Drag & Reorder - Organize your data structure
- Clear All - Reset the entire data
JSONSO/
├── Runtime/
│ ├── JsonScriptableObject.cs # Base class for JSON-serializable SOs
│ ├── JsonScriptableObjectData.cs # Generic JSON data container
│ ├── JsonValue.cs # Dynamic JSON value type
│ ├── JsonKeyValue.cs # Key-value pair for serialization
│ ├── JsonValueType.cs # Value type enumeration
│ └── JSONSO.asmdef
├── Editor/
│ ├── JsonScriptableObjectEditor.cs # Custom inspector
│ ├── JsonValueDrawer.cs # Property drawer
│ └── JSONSO.Editor.asmdef
└── README.md
- Game Configuration - Store game settings as editable JSON
- Save System - Create flexible save files
- Data Import/Export - Exchange data with external tools
- API Integration - Parse and store API responses
- Localization - Manage translation data
- Level Data - Store level configurations
- Debug Tools - Inspect and modify runtime data
- Unity 2019.4 or higher
- .NET Standard 2.0 / .NET 4.x
MIT License
Copyright (c) 2026 Xavier Arpa López Thomas Peter ('xavierarpa')
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Contributions are welcome! Please feel free to submit a Pull Request.
- Author: Xavier Arpa López Thomas Peter
- Email: arpaxavier@gmail.com
- GitHub: @xavierarpa