FormAnswer.adf schema in JSM Cloud OpenAPI spec models Jackson JsonNode internals instead of a generic JSON object — causes silent ADF data loss in generated clients

JSM Development JSM Cloud
,
1

Summary

The adf property on FormAnswer (used in POST /rest/servicedeskapi/request when isAdfRequest: true) references a component schema named JsonNode in the official OpenAPI spec:

https://developer.atlassian.com/cloud/jira/service-desk/swagger.v3.json

"FormAnswer": {
  "properties": {
    "adf": {
      "allOf": [{ "$ref": "#/components/schemas/JsonNode" }],
      "description": "Answer in Atlassian Document Format (ADF)"
    }
  }
}

This JsonNode schema is not a generic “any JSON value” schema — it appears to be generated by reflecting over the Java class com.fasterxml.jackson.databind.JsonNode, since its properties are exactly that class’s introspection/accessor methods:

"JsonNode": {
  "additionalProperties": false,
  "properties": {
    "array": { "type": "boolean" },
    "bigDecimal": { "type": "boolean" },
    "bigInteger": { "type": "boolean" },
    "binaryValue": { "items": {...}, "type": "array" },
    "booleanValue": { "type": "boolean" },
    "textValue": { "type": "string" },
    "valueAsText": { "type": "string" },
    ...
  }
}

None of these fields correspond to an actual ADF document’s structure (type, version, content, marks, etc.).

Impact

Any OpenAPI client generated directly from this spec produces a model for adf with these meaningless fields instead of a generic object/map. Confirmed independently in three unrelated generated clients:

  • A Java client (openapi-generator, useJackson3: true, webclient library)
  • The atlassian_apis Dart package (pub.dev)
  • The jirav2 Rust crate (docs.rs)

All three type FormAnswer.adf as a JsonNode struct/class mirroring the same broken property list, confirming this originates in the shared upstream spec, not in any individual generator’s quirks.

Consequence: when a real ADF document is deserialized into this generated model, none of its fields match, so the resulting object is empty. On round-trip serialization, adf becomes {} instead of the original document. Submitting a request with an empty adf for a rich-text form field is rejected with:

{"errorMessage": "Invalid form format. Refer to the REST API documentation and try again."}

This is a silent failure — nothing raises a compile-time or obvious runtime error, and the resulting 400 gives no indication the cause is an empty adf object. This made it very difficult to diagnose in our case (took an extensive debugging session to isolate, spanning process orchestration, DTO serialization, and auth, before landing on the spec itself).

Steps to reproduce

  1. Generate a client from the current spec using openapi-generator (Java, library: webclient), or use any client generated from the spec that types FormAnswer.adf as the JsonNode schema above.
  2. Deserialize a JSON payload containing a real ADF document into FormAnswer.adf, e.g.:
   {"93": {"adf": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "example"}]}]}}}
  1. Re-serialize the resulting object.
  2. adf now serializes as {} — all content is lost.
  3. Submit this payload to POST /rest/servicedeskapi/request with isAdfRequest: true against a request type with a rich-text form field.
  4. Observe 400 Bad Request with the “Invalid form format” message.

Expected behavior

FormAnswer.adf should be modeled as a generic JSON object:

"adf": {
  "type": "object",
  "additionalProperties": true,
  "description": "Answer in Atlassian Document Format (ADF)"
}

This lets generated clients produce a Map<String, Object> (or equivalent) that preserves arbitrary ADF content through (de)serialization, consistent with how other “any JSON value” fields are modeled elsewhere in the same spec (plain {}/type: object schemas, not $ref’d to JsonNode).

Workaround

We patched our locally generated copy of the spec to retype adf as type: object, additionalProperties: true before code generation. Not a solution for anyone consuming the spec directly from the published URL.

Related but distinct issue

Worth noting for context: there’s a separate, previously-closed report about text-typed answers not rendering on paragraph-type form fields (the suggested workaround there is to use adf instead of text) — that one was correctly closed as expected behavior. This report is about a different, genuine bug: the adf path itself, when consumed through a generated client from the official spec, silently loses its content due to the schema issue described above.

Searched the community forum and jira.atlassian.com for existing reports (FormAnswer, adf, JsonNode, isAdfRequest) and found none — apologies if this turns out to be a duplicate.