Chilkat.JsonObject Class Overview

Chilkat.JsonObject provides DOM-style access to JSON objects. It can load, inspect, modify, create, search, sort, emit, and save JSON. It supports path-based access, index-based member access, automatic creation of nested paths, object and array references, Firebase-style updates, record searches, date/time conversion, binary data encoding, variable substitution, and optional secure secret resolution.

What the Class Is Used For

Use Chilkat.JsonObject when an application needs to parse JSON into an editable in-memory object tree, access values by path or index, update nested data, build JSON programmatically, search record arrays, and emit compact or human-readable JSON.

Load and Emit JSON Load from strings, files, BinData, or StringBuilder, then emit as compact or pretty JSON.
Path-Based Access Retrieve and update values using JSON paths, with configurable delimiter characters and reusable path prefixes.
Build JSON Objects Append or insert strings, numbers, booleans, nulls, arrays, and nested objects.
Search and Modify Records Find or delete records in arrays where a field matches a value or pattern.

Typical Workflow

  1. Load JSON using Load, LoadFile, LoadBd, or LoadSb.
  2. Configure optional path behavior with DelimiterChar, PathPrefix, and index variables I, J, and K.
  3. Read values with path-based methods such as StringOf, IntOf, BoolOf, ObjectOf, or ArrayOf.
  4. Modify values with Set*Of methods when a path already exists, or Update* methods when the path should be created automatically if needed.
  5. Add new members with Append* or Add*At methods.
  6. Search, reorder, rename, delete, or sort members using methods such as FindRecord, MoveMember, Rename, Delete, and Sort.
  7. Emit or save the result using Emit, EmitSb, EmitBd, or WriteFile.

Core Concepts

Concept Meaning Important Members
JSON Object The current object containing name/value members. The object may be the document root or a nested object within a larger JSON document. Size, NameAt, TypeAt, GetDocRoot
JSON Path A string used to address nested values, objects, and arrays. DelimiterChar, PathPrefix, HasMember, StringOf
Index Variables The I, J, and K properties are used when evaluating JSON paths that contain these index placeholders. I, J, K
Object / Array References Methods can return references to nested JSON objects or arrays. The full document remains in memory while at least one reference exists. ObjectOf, ArrayOf, GetDocRoot, CopyRef
Append vs Update Append methods add a direct member name. Update methods use JSON paths and automatically create missing path components. AppendString, UpdateString, UpdateNewObject
Emit Options Output can be compact or pretty-printed, with configurable line endings. EmitCompact, EmitCrLf, Emit

Loading, Clearing, and Saving

Task Methods Use When
Load JSON from text Load Parse a JSON string and load it into the object for DOM-style access.
Load JSON from file LoadFile Read and parse a JSON file from disk.
Load JSON from memory objects LoadBd, LoadSb Load JSON from BinData or StringBuilder.
Clear object Clear Clears the contents, equivalent to loading {}.
Save JSON to file WriteFile Saves the current JSON document to a file.
Store and reload predefined JSON Predefine, LoadPredefined Adds or replaces a JSON document in an internal global predefined set, then loads it later by name.

Emitting JSON

Need Member Behavior
Compact vs pretty output EmitCompact Default true emits a single compact line. Set to false for human-readable indentation.
CRLF vs LF line endings EmitCrLf Applies only to non-compact output. Default true emits CRLF line endings.
Emit to string Emit Returns the JSON document rooted at the current object as a string.
Emit to memory objects EmitBd, EmitSb Appends emitted JSON to BinData or StringBuilder.
Emit with substitutions EmitWithSubs Emits JSON while applying variable substitutions from a Hashtable. Can omit members with empty strings or empty arrays.

Path Handling

Feature Property Guidance
Path delimiter DelimiterChar Default is .. Set to / for Firebase-style paths.
Automatic path prefix PathPrefix Automatically prepends a prefix to JSON paths passed to methods such as StringOf, UpdateString, SetBoolOf, and SizeOfArray.
Path index placeholders I, J, K Store index values used when evaluating paths containing the corresponding path index variables.
Lowercase member names on load LowerCaseNames If true, member names are converted to lowercase when loading JSON with Load, LoadBd, LoadSb, or LoadFile.
Member name vs JSON path: Methods such as AppendString, AppendObject, and AppendArray take a direct member name, not a JSON path. Use Update* methods when you want path-based creation or modification.

Reading Values

Value Type By Index By JSON Path
String StringAt StringOf, StringOfSb, StringOfEquals
Integer / unsigned integer IntAt IntOf, UIntOf
Boolean BoolAt BoolOf
Null check IsNullAt IsNullOf
Object ObjectAt, ObjectAt2 ObjectOf, ObjectOf2
Array ArrayAt, ArrayAt2 ArrayOf, ArrayOf2, SizeOfArray
Binary data encoded as JSON string Not index-specific. BytesOf
Date/time Not index-specific. DateOf, DtOf
Type inspection TypeAt JsonTypeOf
Type values: TypeAt and JsonTypeOf return 1 string, 2 number, 3 object, 4 array, 5 boolean, 6 null, or -1 when no member exists.

Adding and Appending Members

Need Insert at Index Append to End
String AddStringAt AppendString
Integer AddIntAt AppendInt
Number from string AddNumberAt Use update or add-at method as appropriate.
Boolean AddBoolAt AppendBool
Null AddNullAt Use add-at or update method as appropriate.
Object AddObjectAt, AddObjectCopyAt AppendObject, AppendObject2, AppendObjectCopy
Array AddArrayAt, AddArrayCopyAt AppendArray, AppendArray2, AppendArrayCopy, AppendStringArray
Insert positions: For Add*At methods, use index 0 to prepend and -1 to append. Indexing is zero-based.

Setting and Updating Values

Value Type Set Existing Value Update or Auto-Create Path
String SetStringAt, SetStringOf UpdateString, UpdateSb
Integer / unsigned integer SetIntAt, SetIntOf UpdateInt, UpdateUInt
Number from string SetNumberAt, SetNumberOf UpdateNumber
Boolean SetBoolAt, SetBoolOf UpdateBool
Null SetNullAt, SetNullOf UpdateNull
Object NewObjectOf UpdateNewObject
Array NewArrayOf UpdateNewArray
Binary data encoded as string Not index-specific. UpdateBd
Update methods create paths: UpdateString, UpdateInt, UpdateBool, UpdateNewObject, and related methods automatically create missing path components as needed.

Deleting, Renaming, Reordering, and Sorting

Task Method Notes
Delete by member name Delete Deletes a direct member by name. The name is not a JSON path.
Delete by index DeleteAt Deletes the zero-based member at the specified index.
Rename by member name Rename Renames a direct member from one name to another.
Rename by index RenameAt Renames the member at the specified zero-based index.
Move member MoveMember Moves a member from one index to another. Use -1 as the target to move it to the end.
Swap members Swap Swaps the positions of two members.
Sort members Sort Sorts members by name, with ascending and case-sensitive options.

Searching JSON

Search Task Method Purpose
Find object containing a member FindObjectWithMember, FindObjectWithMember2 Recursively searches the current JSON subtree for the first object that contains the named member.
Find a record in an array FindRecord, FindRecord2 Locates a JSON object in an array where a field equals or matches a value or pattern.
Find a string within a matching record FindRecordString Finds a record by one field and returns another value from that matching record.
Delete matching records DeleteRecords Deletes records from an array where a relative field equals or matches a specified value or pattern. Returns the number deleted.
Check member existence HasMember Returns true if the item at the given JSON path exists.
Find direct member index IndexOf Returns the zero-based index of a direct member name, or -1 when not found.

Firebase-Style Updates

Task Method / Property Behavior
Use Firebase path delimiter DelimiterChar = "/" Makes path syntax match Firebase-style slash-separated paths.
Apply Firebase event FirebaseApplyEvent Applies a Firebase put or patch event containing JSON such as {"path": "/", "data": {...}}.
Apply patch FirebasePatch For each key in the supplied JSON data, updates or adds the corresponding key at the target path.
Apply put FirebasePut Inserts or replaces a value at a path. The value can be JSON text, a number, boolean, null, or a quoted string.

Object References and Copies

Need Method Important Detail
Reference a nested object ObjectOf, ObjectOf2 The returned object references the same underlying JSON document.
Reference a nested array ArrayOf, ArrayOf2 Returns or assigns a JsonArray reference.
Get document root GetDocRoot, GetDocRoot2 Returns the root object from any object within the JSON document.
Copy reference CopyRef Updates another JsonObject to reference the same JSON object.
Make a deep copy MakeCopy Copies the JSON object into another JsonObject.
Append a copy AppendObjectCopy, AppendArrayCopy, AddObjectCopyAt, AddArrayCopyAt Inserts or appends a copied object or array instead of referencing the original.
Lifetime note: The entire JSON document stays in memory as long as at least one object reference exists. Once the last reference is removed, the document is automatically deallocated.

Dates, Binary Data, and Numbers

Data Type Methods Notes
Date/time strings DateOf, DtOf Auto-recognizes ISO-8061-style timestamps, RFC 822 date/time strings, and Unix timestamp integers. DtOf can return local or UTC/GMT values.
Binary data stored as encoded string BytesOf, UpdateBd Decode or encode binary data using encodings such as base64 or hex.
Number as exact string AddNumberAt, SetNumberAt, SetNumberOf, UpdateNumber Pass the number already converted to the exact string representation desired by the application.
64-bit workaround patterns UpdateNumber, SetNumberOf Numeric strings are useful when the environment needs to preserve large numeric values exactly.

Secrets Support

EnableSecrets allows selected string-setting methods to resolve credentials from operating-system secure storage instead of embedding literal secrets directly in code.

Property / Format Details
EnableSecrets Default is false. When true, supported methods accept secret specifier strings beginning with !!.
Secure stores Windows Credential Manager on Windows and Apple Keychain on macOS.
Specifier format !![appName|]service[|domain]|username
Supported methods AddStringAt, AppendString, SetStringAt, SetStringOf, UpdateSb, UpdateString

Diagnostics and Troubleshooting

Problem Area Member What to Check
Load, parse, or method failure LastErrorText Provides detailed information about the last method or property access. Check it after failures or unexpected results.
Path does not resolve HasMember, DelimiterChar, PathPrefix Confirm the path delimiter, prefix, and existence of the target member.
Unexpected type JsonTypeOf, TypeAt Verify whether the value is a string, number, object, array, boolean, or null before reading it.
Append did not create nested data Append* methods, Update* methods Remember that append methods take direct member names, not JSON paths. Use update methods for path-based creation.
Case-sensitive member mismatch LowerCaseNames Consider whether member names were converted to lowercase on load.
Wrong array size or index SizeOfArray, I, J, K Check the array size and any path index variables used in the path.

Common Pitfalls

Pitfall Better Approach
Passing a JSON path to AppendString or another append method. Append methods take a direct member name. Use UpdateString or another Update* method for paths.
Assuming SetStringOf creates missing parents. Use UpdateString when the path should be created automatically.
Reading a value without checking that it exists. Use HasMember and JsonTypeOf before reading optional values.
Forgetting that PathPrefix changes later path calls. Clear or update PathPrefix when switching to a different part of the document.
Expecting pretty JSON while EmitCompact remains true. Set EmitCompact = false before calling Emit.
Using the wrong delimiter for Firebase-style paths. Set DelimiterChar = "/" when using Firebase-style slash paths.

Best Practices

Recommendation Reason
Use Update* methods for building nested JSON. They automatically create missing path components and reduce boilerplate.
Use Append* and Add*At when controlling direct member order. These methods work at the current object level and support precise insertion positions.
Check type before reading when JSON is externally supplied. JsonTypeOf and TypeAt help avoid incorrect assumptions about input JSON.
Use ObjectOf and ArrayOf to work naturally with nested data. They return references to sub-objects or arrays so code can operate at the correct level of the JSON tree.
Use numeric strings for precise number formatting. Methods such as UpdateNumber and SetNumberOf preserve the application’s chosen numeric string representation.
Use EmitCompact = false for readable diagnostics. Pretty output is easier to inspect in logs, examples, and documentation.
Use EnableSecrets for JSON that needs credentials. Supported string methods can resolve secrets from Windows Credential Manager or Apple Keychain at runtime.
Check LastErrorText after failures. It provides the most useful diagnostic detail for load, path, update, search, emit, and file operations.

Summary

Chilkat.JsonObject is the primary JSON object class for loading, editing, searching, and emitting JSON. It provides both index-based and path-based access, object and array references, automatic nested-path creation, record search and deletion helpers, Firebase-style update support, compact or pretty output, binary/date handling, predefined documents, member reordering, and optional secure secret resolution.

For most JSON-building tasks, use Update* methods to create nested paths automatically. Use Append* or Add*At methods when adding direct members at a known position in the current object.