XmobiTea Json

Lightweight JSON parser/serializer plus dictionary-backed typed data wrappers for Unity.

AI Quick Contract

This section is the shortest summary when you only need the core usage rules.

• This package is not a generic POCO serializer like JsonUtility or Newtonsoft.Json.
• Core parser/serializer is CXJson.
• Main container types are:
  • CXData
  • CXRequestData
  • CXObject
• Parsed JSON objects become Dictionary<string, object>.
• Parsed JSON arrays become List<object>.
• Parsed numbers are read as double by the parser.
• Typed getters in CXData convert from those stored values with explicit fallback rules.
• CXObject.FromJson(...) only succeeds when the JSON root is an object, not when the root is an array.
• Serialization recognizes ICXData and serializes its BaseData.

Need-Based Routing

Open these only when the current task needs them. There is no fixed read order.

• AGENTS.md: package-level rules for code generation and maintenance.
• AI_USAGE.md: short machine-friendly usage rules for using this package without reading the implementation.

What This Package Provides

CXJson

Low-level JSON parser and serializer.

CXData

Dictionary-backed typed read container with convenience getters and list accessors.

CXRequestData

Mutable request-building container with Add* helper methods.

CXObject

Object-root wrapper on top of CXRequestData, commonly used for parsed JSON objects.

ICXData

Interface exposing BaseData so wrapper types can be serialized through CXJson.

Runtime Files

• Runtime/ICXData.cs
• Runtime/CXData.cs
• Runtime/CXJson.cs
• Runtime/CXRequestData.cs
• Runtime/CXObject.cs

Exact Runtime Behavior

1. CXJson

Parsing

CXJson.From(string json) returns:

• Dictionary<string, object> for object roots
• List<object> for array roots
• primitive values for primitive roots
• null when parsing fails or input is null

Important parser behaviors:

• numbers are parsed as double
• booleans are parsed as bool
• strings are parsed as string
• arrays are parsed as List<object>
• objects are parsed as Dictionary<string, object>
• null becomes null

This means numeric getters in higher-level wrappers often need to convert from double.

Serialization

CXJson.To(object obj) serializes:

• ICXData by serializing BaseData
• IDictionary as JSON object
• IList as JSON array
• strings/chars as JSON strings
• numeric primitives with invariant culture
• unsupported objects by calling ToString() and serializing that string

Important implication:

• arbitrary custom classes are not reflected into JSON fields,
• they become strings unless they implement ICXData or are already dictionaries/lists/primitives.

2. CXData

CXData is the main typed read wrapper.

Its backing store is:

IDictionary<string, object>

Construction

Supported constructors:

• empty constructor
• from another CXData
• from IDictionary<string, object>

When constructed from a dictionary:

• nested Dictionary<string, object> values are converted into CXObject
• other values are stored as-is

JSON

JSON serializes the current backing dictionary through CXJson.To(...).

Indexer

this[string key]:

• returns null if the key does not exist
• overwrites existing keys on set

Scalar getters

Important getter rules:

• GetString(...) returns string.Empty when the key is missing or not a string
• numeric getters return nullable types
• many numeric getters accept both the target numeric type and parsed double
• GetBoolean(...) returns bool?
• GetDate(...) expects exact UTC string format:

yyyy-MM-dd'T'HH:mm'Z'

If the stored string does not match that exact format, parsing will fail.

List getters

List getters work only when the stored value is compatible with the expected internal representation.

Typical cases:

• parsed JSON arrays are usually List<object>
• list getters then iterate and convert compatible values

Important behavior:

• unsupported element types are silently skipped
• unsupported list shapes return null

Object getters

• GetObject(...) returns CXData
• GetCXData(...) returns CXRequestData
• GetCXDataList(...) returns List<CXRequestData>

These methods wrap nested dictionaries into the corresponding wrapper types.

3. CXRequestData

CXRequestData inherits from CXData and adds mutable builder-style methods.

Important methods:

• Add(...)
• Remove(...)
• AddString(...)
• AddJSONStringAsObject(...)
• AddDate(...)
• AddNumber(...)
• AddNumberList(...)
• AddObject(...)
• AddObjectList(...)
• AddStringList(...)
• AddBoolean(...)

Date behavior

AddDate(...) serializes the date as UTC string using:

yyyy-MM-dd'T'HH:mm'Z'

This matches the format expected by GetDate(...).

Object behavior

AddObject(...) stores child.BaseData, not the wrapper instance itself.

AddObjectList(...) stores the provided List<CXData> directly. Serialization still works because CXJson handles ICXData elements inside lists.

4. CXObject

CXObject is a specialized wrapper for object-root JSON.

Important behavior:

• CXObject.FromJson(...) returns null if the root JSON is not an object
• constructor CXObject(string type) stores @class = type

Use CXObject when your JSON root must be an object rather than an array.

Basic Usage

Build request-style data

using XmobiTea.MiniJson;

var request = new CXRequestData()
	.AddString("name", "Player")
	.AddNumber("score", 10)
	.AddBoolean("vip", true);

UnityEngine.Debug.Log(request.JSON);

Parse object-root JSON

using XmobiTea.MiniJson;

var json = "{\"name\":\"Player\",\"score\":10}";
var data = CXObject.FromJson(json);

var name = data.GetString("name");
var score = data.GetInt("score");

Nested object access

using XmobiTea.MiniJson;

var parent = new CXRequestData();
parent.AddObject("child", new CXRequestData().AddString("id", "abc"));

var child = parent.GetCXData("child");
var id = child.GetString("id");

Do / Don't

Do

• Do treat parsed numeric JSON values as double internally unless a wrapper converted them.
• Do use CXObject.FromJson(...) only when the root is known to be a JSON object.
• Do use CXRequestData for request-building and mutation.
• Do use CXData / CXObject for typed reads.
• Do treat unsupported custom objects as non-serializable unless converted first.

Don't

• Don't assume this package reflects arbitrary C# classes into JSON fields.
• Don't assume all getters throw on mismatch. Most return nullable/default fallback values.
• Don't assume array roots can be parsed by CXObject.FromJson(...).
• Don't assume GetString(...) returns null for missing keys. It returns string.Empty.
• Don't assume all numeric precision is preserved when data passes through double.

Common Mistakes

Mistake 1: Using CXObject.FromJson(...) for array roots

Wrong:

var data = CXObject.FromJson("[1,2,3]");

This returns null because the root is not a dictionary/object.

Mistake 2: Expecting numbers to stay strongly typed after parse

Parsed JSON numbers become double first.

So getters like GetInt(...), GetLong(...), GetFloat(...), and GetDecimal(...) often convert from double.

Mistake 3: Expecting arbitrary object serialization

Wrong assumption:

• CXJson.To(myCustomClass) serializes all fields of myCustomClass.

That is false.

Current behavior:

• unknown object types are serialized using ToString().

Mistake 4: Assuming missing strings return null

GetString(...) returns string.Empty, not null.

Repository Usage Pattern

Inside this repository, direct usage is currently lightweight. Assets/TestBehaviour.cs demonstrates building a CXRequestData, serializing it through JSON, and reading typed values after constructing a wrapper from JSON.

Use the package with this pattern:

• parse dynamic JSON into wrappers,
• read with typed helper methods,
• build request-like payloads with CXRequestData.

Decision Table

Use this package when:

• you need lightweight dynamic JSON parsing without an external dependency,
• you want dictionary-backed typed accessors,
• you want simple request-style JSON construction.

Do not use this package when:

• you need full POCO serialization/deserialization,
• you need attribute-driven mapping,
• you need exact numeric semantics across arbitrary large values,
• you need advanced schema validation.

Expected AI Usage Pattern

When an AI agent generates code using this package, the correct default pattern is:

1. Use CXObject.FromJson(...) for object-root JSON.
2. Use CXRequestData for building payloads.
3. Treat numeric parse results as conversion-based, not strongly typed from the source.
4. Treat returned wrapper values as nullable/default-based rather than exception-based.

An AI agent should not:

• claim this package is equivalent to JsonUtility or Newtonsoft.Json,
• serialize arbitrary complex classes without manually converting them,
• assume array-root JSON can be consumed by CXObject.FromJson(...).

Namespace

using XmobiTea.MiniJson;

Assembly Definition

Runtime assembly:

com.xmobitea.changx.mini-json.runtime

Package Metadata

• Package name: com.xmobitea.changx.mini-json
• Unity version: 2022.3+
• License: Apache-2.0