diff --git a/ipa/general/0130.md b/ipa/general/0130.md new file mode 100644 index 0000000..13b30fd --- /dev/null +++ b/ipa/general/0130.md @@ -0,0 +1,23 @@ +--- +id: 130 +state: experimental +--- + +# IPA-130: Dynamic Content Fields + +Resource properties sometimes hold a JSON value — configuration objects, +filters, metadata, templated payloads. Modeling such a property as a string +containing the serialized JSON pushes serialization concerns onto clients and +invites round-trip drift, because servers routinely normalize the JSON +(whitespace, key ordering, reformatting of nested structures). Declarative +clients then interpret the representation-level difference as state drift. + +## Guidance + +- Properties whose value is JSON **must** be modeled as a JSON object in + requests and responses — never as a string holding the serialized form. +- When the JSON has a well-defined schema, the API **must** model that schema in + the resource definition. Clients, documentation, and tooling benefit from + knowing the shape of the content. +- When the JSON is genuinely dynamic (arbitrary client-provided keys and + values), the property can be modeled as an object with dynamic keys.