You can choose JsonToObjects for direct, name-matched creation of new model objects from JSON, or TaJson when you need a ViewModel to define, transform, read, or update a JSON hierarchy.
Choose the right JSON approach
| Requirement | Use | Why |
|---|---|---|
| Create new objects from a JSON string in a ViewModel, with JSON names that already match the model | JsonToObjects | It imports directly into matching attributes and associations. There is no mapping or transformation layer. |
| Use JSON property names that differ from model attribute names | TaJson | The ViewModel columns define the JSON field names and the expressions or attributes that receive their values. |
| Produce JSON from model objects | AsTaJson | The ViewModel defines the output hierarchy and fields. |
| Update an existing object hierarchy from JSON | MergeTaJson or ApplyTaJson | TaJson imports against a ViewModel template. Merge and Apply have different removal behavior for multi-associations. |
| Receive or expose a JSON contract through a REST ViewModel | TaJson | A ViewModel provides an explicit contract for both the JSON shape and the model mapping. |
JsonToObjects: direct creation from matching JSON
selfVM.JsonToObjects is available only in a ViewModel. It receives JSON from a string and creates an object hierarchy starting with the type supplied as its first argument.
JsonToObjects fills model attributes and associations when their names match the JSON properties. It does not provide a transformation layer between the incoming JSON and the model.
For example, if the JSON contains an Attribute1 property, the target model must expose the corresponding attribute or association with the matching name for direct import. If an external contract instead sends attribute_one while the model uses Attribute1, JsonToObjects does not provide a ViewModel mapping to bridge that difference.
Use JsonToObjects when all of the following are true:
- You are working in a ViewModel.
- You want to create a new object hierarchy from the incoming JSON.
- The JSON structure and property names already match the model.
- You do not need to rename fields, reshape the hierarchy, or update an existing hierarchy through a template.
If you need a model section that matches a known JSON or XML sample, you can create a starting model structure from that sample. See Documentation:Using JSON or XML as class template.
TaJson: a ViewModel-defined JSON contract
TaJson is a declarative JSON strategy. A ViewModel acts as the template for the JSON hierarchy when you send JSON and when you receive it. This separates the external JSON contract from the names and shape of the underlying model.
For example, a ViewModel template can define a column whose JSON name is author_name and whose target is self.author. JSON containing "author_name": "Buyondo" can then populate the model attribute author. This mapping is not available with JsonToObjects.
Use TaJson when you need to:
- Define which attributes and associations participate in a JSON message.
- Map an external JSON field name to a different model attribute.
- Generate JSON using a controlled hierarchy with AsTaJson.
- Import JSON into existing objects with MergeTaJson or ApplyTaJson.
- Handle JSON shapes that require dynamic properties, arrays of values, or embedded raw JSON. These are ViewModel-tagged-value options described in TaJson.
Import behavior: MergeTaJson and ApplyTaJson
Both TaJson import operations use the ViewModel as the field-mapping and hierarchy guide, and both return a log string describing the import.
| Operation | Intended behavior | Important consequence |
|---|---|---|
| MergeTaJson | Writes matching JSON values into a target object using the ViewModel mapping. | Suitable for a partial update. Fields not represented by the JSON can remain untouched. |
| ApplyTaJson | Applies the JSON hierarchy using the ViewModel template. | When it processes multi-associations, it removes objects not present in the JSON. Do not use it as a partial-list update unless that removal behavior is intended. |
Decision examples
Example: direct import of a model-shaped payload
You receive a JSON payload whose property and association names already match the model, and every request represents new objects. Use JsonToObjects from the ViewModel. No separate mapping ViewModel is required because the JSON and model already share names.
Example: external field names differ from the model
Your model has author, but the API contract requires author_name. Create a dedicated TaJson ViewModel template with a column named author_name that targets self.author, then use MergeTaJson or ApplyTaJson according to the required update behavior.
Example: publish a controlled JSON response
You want a REST endpoint to return only selected fields in a specific hierarchy. Define that hierarchy in a TaJson ViewModel and call AsTaJson. When you need the generated JSON to be the complete REST response body, use a ViewModel column named exactly RawJson with the AsTaJson expression. See AsTaJson and Expose REST Service.
TaJson import checks
Before using MergeTaJson or ApplyTaJson, check the following:
- Create a ViewModel that represents the intended JSON hierarchy. Keep a dedicated mapping ViewModel small and limited to the fields that the contract needs.
- Verify that each ViewModel column has the intended JSON name and target expression or attribute.
- Review the
ReadOnlysetting on columns in multi-nestings. The framework can setReadOnlytotruewhen attributes are added to multi-nestings. For TaJson import,ReadOnly=truemeans that the field is read-only for import as well. - Choose MergeTaJson for a merge-style or partial update. Choose ApplyTaJson only when removing objects absent from JSON multi-associations is correct.
- Inspect the returned Merge/Apply log, especially while establishing a new mapping.
Large and deeply nested JSON
Do not process an extremely large, deeply nested hierarchy as one TaJson Apply or Merge operation. A payload with 1,000 detail objects, each containing 1,000 child objects, each containing 1,000 further child objects, can require processing 1,000 Ă 1,000 Ă 1,000 objects at once.
Instead, place a case-sensitive string ViewModel column named RawJSon at a boundary where later levels should be deferred. During TaJson import, the JSON for the current level and below is stored as text in that column. You can then process smaller groups of stored JSON in separate passes with another ViewModel. This keeps each import unit bounded and is suitable for background processing such as MDrivenServer ServerSideJobs.
When producing JSON with AsTaJson, the RawJSon=true tagged value can inject an already formatted JSON snippet without serializing it as a quoted string. Ensure that the stored value is valid JSON.