docs(openapi): clarify dataType-per-field-class and host/pathToMove rules (#36321)

[fmontes]

Proposed Changes

Fixes two OpenAPI documentation gaps that caused the MCP server (which builds request payloads from openapi.yaml) to generate 400-failing requests. Both are spec/annotation changes — no behavior change to the endpoints, and the existing workflow guard is left intact.

Bug 1 — POST /api/v1/contenttype: image field dataType
Image fields fail with 400 — Field Type:...ImageField does not accept datatype system_field:cover when sent dataType: SYSTEM. ImageField.acceptedDataTypes() is [TEXT] only; the field schema in the @RequestBody documented the dataType enum but not the per-field-class restriction, so the client guessed SYSTEM.

• ContentTypeResource @RequestBody: documents the field-class -> dataType mapping (ImageField/BinaryField -> TEXT; TextArea/StoryBlock -> LONG_TEXT; Custom -> LONG_TEXT/TEXT; TextField -> TEXT/LONG_TEXT/INTEGER/FLOAT).

Bug 2 — PUT /api/v1/workflow/.../fire/{systemAction}: location fields
Setting host/hostId/hostname/folder on the contentlet is rejected with 400 — System fields [...] cannot be set via this endpoint. This guard is intentional (added in 526132bbf7 to surface silent-ignores — these fields are dropped by MapToContentletPopulator). The supported way to set/change location is the top-level pathToMove property (Move actionlet), which was documented in the body table but not surfaced where callers hit the error.

• WorkflowResource fire @Operation: adds a note that host/folder are rejected and pathToMove is the supported mechanism, with an example.
• validateFireActionForm() BadRequestException message: enriched with a concrete pathToMove example. The guard logic is unchanged.

openapi.yaml regenerated via ./mvnw compile -pl :dotcms-core -DskipTests.

Checklist

• Field-class -> dataType mapping documented (image = TEXT)
• Fire @Operation documents host/folder rejection + pathToMove
• openapi.yaml regenerated and committed
• Guard in validateFireActionForm() left intact
• MCP server generates valid payloads for Book create + contentlet publish (validate after merge)

This PR fixes #36321

[claude]

Claude finished @fmontes's task in 1m 19s —— View job

---

Rollback Safety Analysis

• Gathering context
• Reading rollback-unsafe categories reference
• Getting full PR diff
• Analyzing changes against unsafe categories
• Applying safety label

---

Result: Safe to Roll Back

The two commits in this PR touch only three files:

File	Change
ContentTypeResource.java	Added 4 lines to a @RequestBody Swagger annotation string (documentation only)
WorkflowResource.java	Added/modified 11 lines in a @Operation annotation string and enriched the text of a BadRequestException error message
openapi.yaml	Regenerated — reflects the annotation changes above

Analysis against all unsafe categories:

• C-1 (Structural Data Model) — No DB schema change, no runonce task, no column/table alteration. Not applicable.
• C-2 (ES Mapping) — No changes to ESMappingAPIImpl, ESMappingUtilHelper, or ES index mapping. Not applicable.
• C-3 (Content JSON model) — No CURRENT_MODEL_VERSION change, no ImmutableContentlet change. Not applicable.
• C-4 (DROP TABLE/COLUMN) — No DDL drop statements. Not applicable.
• H-1 through H-8 — No data migrations, no DB renames, no PK changes, no new field types, no storage provider changes, no VTL viewtool contract changes. Not applicable.
• M-1 (Column type change) — No DDL. Not applicable.
• M-2 (Push bundle format) — No bundle XML changes. Not applicable.
• M-3 (REST/GraphQL contract) — The error message text in BadRequestException was enriched (more detail added to an existing 400 response). The response shape (status code, field names) is unchanged; only the human-readable message string is more descriptive. This is additive and backward-compatible — callers testing on the status code or errorCode field are unaffected.
• M-4 (OSGi interface) — No public interface changes. Not applicable.

Conclusion: All changes are documentation-only (Swagger annotations + regenerated YAML) plus a minor enrichment of an error message string. No DB, ES, serialization, or API contract changes. Rolling back to N-1 is safe — no data transformation, no schema alteration, no client-breaking contract change.

Label applied: AI: Safe To Rollback

[github-actions]

🤖 Bedrock Review — qwen.qwen3-next-80b-a3b

New Issues

• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/contenttype/ContentTypeResource.java:522 — Added documentation warning about dataType restrictions, but no code enforces this validation; client may send invalid dataType values without rejection, leading to silent field creation failures or DB exceptions. Assumption: backend does not validate dataType per field class in createType(). What to verify: Is there a validateDataTypeForFieldClass() call in ContentTypeResource.createType() or its callees?
• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/WorkflowResource.java:3217 — Added documentation warning about rejecting system fields (host, hostId, etc.) in contentlet, but no code change shows enforcement of this rule. Assumption: validateFireActionForm() still allows these fields to be passed through to ContentletAPI without rejection. What to verify: Does validateFireActionForm() check for host, hostId, hostname, or folder keys in the contentlet JSON object?
• 🟡 Medium: dotCMS/src/main/webapp/WEB-INF/openapi/openapi.yaml:7768 — OpenAPI spec now documents dataType restrictions, but no schema validation is added to restrict dataType values per clazz. Assumption: OpenAPI spec is purely descriptive and not used for runtime validation. What to verify: Is there a schema-level oneOf or if/then constraint in the OpenAPI spec for dataType based on clazz?

Existing

• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/WorkflowResource.java:3134 — Prior finding: 400 error message for system fields lacks DotSecurityException or permission check — still unchanged. No code added to verify user has permission to modify contentlet location via pathToMove.

Resolved

• ✅ dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/WorkflowResource.java:3215 — Clarified pathToMove usage in error message; no longer ambiguous about sibling vs nested structure.

---

_{Run: #28194092499 · tokens: in: 3029 · out: 697 · total: 3726}

[github-actions]

🤖 Bedrock Review — qwen.qwen3-next-80b-a3b

New Issues

• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/contenttype/ContentTypeResource.java:522 — Documentation updated to warn about dataType restrictions, but no code enforces validation; still risks invalid field creation (same as prior finding)
• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/WorkflowResource.java:3134 — Error message for system fields improved, but still lacks DotSecurityException permission check before rejecting (same as prior finding)
• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/WorkflowResource.java:3217 — Documentation now clarifies pathToMove usage, but still no code validation to reject system fields in contentlet (same as prior finding)
• 🟡 Medium: dotCMS/src/main/webapp/WEB-INF/openapi/openapi.yaml:7768 — OpenAPI docs now include dataType restrictions, but schema still lacks enum or oneOf constraints to enforce them (same as prior finding)

Existing

• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/contenttype/ContentTypeResource.java:522 — Documentation warns of dataType restrictions but no code enforces validation, risking invalid field creation
• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/WorkflowResource.java:3217 — Documentation warns against system fields in contentlet but no validation code added to reject them
• 🟡 Medium: dotCMS/src/main/webapp/WEB-INF/openapi/openapi.yaml:7768 — OpenAPI spec documents dataType restrictions but lacks schema-level constraints to enforce them
• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/WorkflowResource.java:3134 — 400 error for system fields lacks permission check via DotSecurityException

Resolved

• ✅ dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/WorkflowResource.java:3134 — Error message now clarifies pathToMove usage (improved UX, but permission check still missing — so not resolved)
• ✅ dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/WorkflowResource.java:3217 — Documentation now includes pathToMove example and host requirement (improved clarity, but validation still missing — so not resolved)

---

_{Run: #28195007732 · tokens: in: 3422 · out: 981 · total: 4403}

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request