From acd1296b16ee9e9047b18eaeea77ff9c9a349c6b Mon Sep 17 00:00:00 2001 From: Agustin Bettati Date: Fri, 12 Jun 2026 15:57:50 +0200 Subject: [PATCH] feat(ipa): Add IPA-130 Dynamic Content Fields Adds IPA-130 requiring JSON-valued properties to be modeled as JSON objects rather than strings holding serialized JSON, which forces clients to serialize/parse at the edges and produces round-trip drift when servers normalize the content. CLOUDP-412577 --- ipa/general/0130.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 ipa/general/0130.md diff --git a/ipa/general/0130.md b/ipa/general/0130.md new file mode 100644 index 0000000..275fcd4 --- /dev/null +++ b/ipa/general/0130.md @@ -0,0 +1,25 @@ +--- +id: 130 +state: experimental +--- + +# IPA-130: Dynamic Content Fields + +Resource properties that hold a dynamic JSON value — configuration objects, +filters, metadata, templated payloads — should be modeled as a dynamic object +type, so that clients and tooling can work with the content natively rather than +as opaque text. Modeling such a property as a string containing the serialized +JSON instead 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 **should** be modeled as an object with dynamic keys.