Skip to main content
Version: 4.0 preview

Json

Version
4.0 preview
Updated
View markdown

A column holding a JSON document, edited as raw text in a textarea and validated as JSON.

Storage kind: column · Column: text

Use it for a JSON column a human may reasonably inspect or edit: a snapshot, a settings bag, an override map. Two neighbouring choices are often better:

  • Declare no property at all when the column is engine-owned and an operator has no business editing it. #__cbx_party.custom_fields deliberately has none — it is LONGTEXT the engine reads and writes with hand SQL, and putting a form field on it only creates ways to corrupt it.
  • Use rule when the JSON has a known structure worth editing structurally. rule stores JSON too, but with a real editor and a schema behind it.

Never use string for a JSON column. The default request handler HTML-escapes the value, which turns {"a": "b & c"} into something that no longer parses, and check() validates nothing — so an operator can save a broken value and only find out when the engine reads it.

Settings​

SettingMeaning
rowsHeight of the textarea

What it does for you​

  • Reads raw. getDataFromRequest() takes the POSTed value without the string mangling, using the same path as ALLOW_RAW. Backslashes and quotes survive.
  • Normalises. Valid JSON is re-encoded to a canonical compact form (JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE), so the stored text does not vary with how the operator happened to type it. Invalid input is left exactly as typed, so the error message can be about what they actually wrote.
  • Validates. check() refuses a non-empty value that does not decode, quoting json_last_error_msg(). Empty is allowed unless required.
  • Pretty-prints in the list. getOutputValueFromRecordData() returns indented JSON, falling back to the raw string when it does not decode.

An empty or whitespace-only submission becomes null, not ''.

What it does not do​

There is no schema and no structural editor. The type guarantees the column holds parseable JSON, not JSON of the right shape. If the shape matters, validate it in the model's validateData() or in a custom type's check() — and consider whether rule is the better model.

text is 64 KB. A document that can outgrow that needs an explicit 'dataType' => 'longtext'.

@see rule.md — the counter-example, where a structured editor and a schema do exist @see string.md — what not to use, and why @see ../com_configbox_mcp_server.md — how an opaque column is described to an assistant

Last updated on