From eac039c8f6dae7bd5bf767c213485091a19cdb81 Mon Sep 17 00:00:00 2001 From: HermanPeeren Date: Wed, 18 Nov 2026 23:22:23 +0100 Subject: [PATCH] Required fields: what a POST needs to save a new item Each minimal POST example was sent to a Joomla 6.2 site, and the causes were checked in joomla-cms 6.2-dev. A field whose database column has no default is required: without it, saving fails with "Field 'x' doesn't have a default value". - Banners: description, custombannercode and params are required. The minimal example used catid 1, which creates a new banner category titled "1"; it now uses 3. - Content languages: image, description and metadesc are required; the example lang_code was invalid. - Menu items: alias is required (an empty string is accepted); without it the path is null and saving fails. Administrator items also need link. type lists the accepted types: an unknown type gives a 500. - Articles: introtext or articletext is required. - Required JSON objects (params, images, metadata) get minProperties 1: the form filter drops an empty object. Users: groups gets minItems 1. - Administrator menus and modules: client_id is not set by the route; without it a site menu or module is saved. - Media files: the mediatypes query parameter is described; the minimal example uploads a PNG. - Redirects: the minimal example no longer uses the same old and new URL. - Messages: POST saves the message but answers 404. --- CHANGELOG.md | 27 +++++++ src/joomla-ws-api.json | 164 ++++++++++++++++++++++++++++++----------- 2 files changed, 148 insertions(+), 43 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fe2d414..02f1dac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,33 @@ Each release describes the core Web Services API of one Joomla minor version: release 6.2.x is for Joomla 6.2. A patch release (6.2.1, 6.2.2, ...) improves the description of the same API. +## Unreleased + +The `required` lists and minimal examples of POST request bodies now match what Joomla needs to save a new +item (each minimal example was sent to a Joomla 6.2 site; the causes were checked in joomla-cms `6.2-dev`). A +field whose database column has no default is required: without it, saving fails with "Field 'x' doesn't have +a default value". + +- Banners: `description`, `custombannercode` and `params` are required. The minimal example used `catid` 1, + which is not a banner category: Joomla then creates a new banner category titled "1". It now uses 3. +- Content languages: `image`, `description` and `metadesc` are required. The minimal example had an invalid + `lang_code`. +- Menu items (site and administrator): `alias` is required, an empty string is accepted. Without it, saving fails + with "Field 'path' doesn't have a default value", as the path is copied from the alias before Joomla makes the + alias from the title. `link` is required for administrator menu items as well. `type` lists the accepted + types: an unknown type, as in the old minimal example, gives an internal server error. +- Articles: `introtext` or `articletext` is required. +- Required JSON objects (`params` of banners, fields, modules and template styles; `images`, `metadata` and + `params` of newsfeeds) need at least one property that the form knows (`minProperties: 1`): the form filter + drops an empty object, and saving fails. +- Users: `groups` needs at least one group (`minItems: 1`). +- Administrator menus and modules: `client_id` is not set by the route, as was described. Without it, Joomla saves + a site menu or site module. +- Media files: the `mediatypes` query parameter is described. Without it, only image extensions are accepted, so + the minimal example now uploads a PNG instead of a `.txt` file. +- Redirects: the minimal example had the same old and new URL, which Joomla rejects. +- Messages: POST saves the message, but Joomla 6.2 answers 404. + ## 6.2.2 Response attributes now match what the API views of Joomla render (checked against joomla-cms 6.2.0 and diff --git a/src/joomla-ws-api.json b/src/joomla-ws-api.json index d89d53a..8d55263 100644 --- a/src/joomla-ws-api.json +++ b/src/joomla-ws-api.json @@ -611,7 +611,12 @@ "summary": "Minimal request", "value": { "name": "Example", - "catid": 1 + "catid": 3, + "description": "", + "custombannercode": "", + "params": { + "width": "" + } } }, "joomlaSite": { @@ -11737,10 +11742,13 @@ "$ref": "#/components/schemas/com_languages_post_v1_languages_contentRequest" }, "example": { - "lang_code": "Example", + "lang_code": "xx-XX", "title": "Example", "title_native": "Example", - "sef": "Example" + "sef": "xx", + "image": "", + "description": "", + "metadesc": "" } } } @@ -13219,7 +13227,20 @@ "api/components/com_media/src/Controller/MediaController.php" ], "x-support": "source-derived", - "parameters": [], + "parameters": [ + { + "name": "mediatypes", + "in": "query", + "required": false, + "description": "The media types whose file extensions may be uploaded, comma-separated: 0 images, 1 audio, 2 video, 3 documents. Default 0: only image extensions (Media Manager option image_extensions). A .txt file needs mediatypes=3.", + "schema": { + "type": "string", + "pattern": "^[0-3](,[0-3])*$", + "default": "0" + }, + "example": "0,3" + } + ], "responses": { "200": { "description": "The created Media File.", @@ -13270,8 +13291,8 @@ "$ref": "#/components/schemas/com_media_post_v1_media_filesRequest" }, "example": { - "path": "local-images:/example.txt", - "content": "RXhhbXBsZQ==", + "path": "local-images:/example.png", + "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "override": false } } @@ -14972,8 +14993,10 @@ }, "example": { "title": "Example", - "menutype": "Example", - "type": "Example" + "alias": "", + "menutype": "example-admin", + "type": "url", + "link": "https://example.org" } } } @@ -15610,7 +15633,7 @@ } } }, - "description": "Add a Message to the Joomla site.\n\nSee the operation form and response schema. The base edit check requires core.manage and record core.edit, or core.edit.own with a matching owner; component overrides take precedence. Omitted SERVER_UTC/USER_UTC calendar values are restored from the stored UTC values after validation, avoiding a second timezone conversion." + "description": "Add a Message to the Joomla site.\n\nSee the operation form and response schema. The base edit check requires core.manage and record core.edit, or core.edit.own with a matching owner; component overrides take precedence. Omitted SERVER_UTC/USER_UTC calendar values are restored from the stored UTC values after validation, avoiding a second timezone conversion.\n\nIn Joomla 6.2 the message is saved, but the response is 404 Resource not found instead of the new message. List the messages to find it." } }, "/v1/messages/{id}": { @@ -20286,8 +20309,9 @@ "$ref": "#/components/schemas/com_redirect_post_v1_redirectsRequest" }, "example": { - "old_url": "Example", - "new_url": "Example" + "old_url": "old-page", + "new_url": "new-page", + "published": 1 } } } @@ -27381,7 +27405,7 @@ "pattern": "^-?[0-9]+$", "x-input-normalization": "Joomla form accepts integer or decimal integer string; optional empty string is form-filter dependent.", "title": "Category", - "description": "Joomla form field catid; input is validated and filtered according to x-joomla-form.", + "description": "Joomla form field catid; input is validated and filtered according to x-joomla-form. Must be the ID of a banner category (extension com_banners). Any other number creates a new banner category with that number as its title.", "x-joomla-form": { "name": "catid", "type": "categoryedit", @@ -27493,7 +27517,7 @@ "description": { "type": "string", "title": "Description", - "description": "Joomla form field description; input is validated and filtered according to x-joomla-form.", + "description": "Joomla form field description; input is validated and filtered according to x-joomla-form. Required on create: its database column has no default, so saving fails without it. An empty string is accepted.", "x-joomla-form": { "name": "description", "type": "editor", @@ -27542,7 +27566,7 @@ "custombannercode": { "type": "string", "title": "Custom Code", - "description": "Joomla form field custombannercode; input is validated and filtered according to x-joomla-form.", + "description": "Joomla form field custombannercode; input is validated and filtered according to x-joomla-form. Required on create: its database column has no default, so saving fails without it. An empty string is accepted.", "x-joomla-form": { "name": "custombannercode", "type": "textarea", @@ -28005,7 +28029,9 @@ "x-source": "administrator/components/com_banners/forms/banner.xml" } }, - "additionalProperties": false + "additionalProperties": false, + "minProperties": 1, + "description": "Required on create: its database column has no default. Send at least one property that the form knows: the form filter drops unknown properties, so an empty object (or one with only unknown properties) is not saved and saving fails. For example {\"width\": \"\"}." }, "bannercode": { "type": "string", @@ -28023,7 +28049,10 @@ "additionalProperties": false, "required": [ "name", - "catid" + "catid", + "description", + "custombannercode", + "params" ] }, "com_banners_post_v1_bannersResponse": { @@ -68673,7 +68702,7 @@ "introtext": { "type": "string", "title": "Intro Text", - "description": "Joomla form field introtext; input is validated and filtered according to x-joomla-form.", + "description": "Joomla form field introtext; input is validated and filtered according to x-joomla-form. Required on create unless articletext is sent: its database column has no default, so saving fails without both. An empty string is accepted.", "x-joomla-form": { "name": "introtext", "label": "COM_CONTENT_FIELD_INTROTEXT", @@ -68720,6 +68749,18 @@ "title", "catid", "language" + ], + "anyOf": [ + { + "required": [ + "introtext" + ] + }, + { + "required": [ + "articletext" + ] + } ] }, "com_content_post_v1_content_articlesResponse": { @@ -78125,7 +78166,9 @@ "x-source": "administrator/components/com_fields/forms/field.xml" } }, - "additionalProperties": false + "additionalProperties": false, + "minProperties": 1, + "description": "Required on create: its database column has no default. Send at least one property that the form knows: the form filter drops unknown properties, so an empty object (or one with only unknown properties) is not saved and saving fails." }, "fieldparams": { "type": "object", @@ -86589,7 +86632,7 @@ "image": { "type": "string", "title": "Image", - "description": "Joomla form field image; input is validated and filtered according to x-joomla-form.", + "description": "Joomla form field image; input is validated and filtered according to x-joomla-form. Required on create: its database column has no default, so saving fails without it. An empty string is accepted.", "x-joomla-form": { "name": "image", "type": "filelist", @@ -86613,7 +86656,7 @@ "description": { "type": "string", "title": "Description", - "description": "Joomla form field description; input is validated and filtered according to x-joomla-form.", + "description": "Joomla form field description; input is validated and filtered according to x-joomla-form. Required on create: its database column has no default, so saving fails without it. An empty string is accepted.", "x-joomla-form": { "name": "description", "type": "textarea", @@ -86684,7 +86727,7 @@ "type": "string", "maxLength": 300, "title": "Meta Description", - "description": "Joomla form field metadesc; input is validated and filtered according to x-joomla-form.", + "description": "Joomla form field metadesc; input is validated and filtered according to x-joomla-form. Required on create: its database column has no default, so saving fails without it. An empty string is accepted.", "x-joomla-form": { "name": "metadesc", "type": "textarea", @@ -86712,7 +86755,10 @@ "lang_code", "title", "title_native", - "sef" + "sef", + "image", + "description", + "metadesc" ] }, "com_languages_post_v1_languages_contentResponse": { @@ -116028,7 +116074,7 @@ 1, "1" ], - "description": "Fixed by the site/administrator route; cannot switch clients with the body." + "description": "Must be 1. The route does not set it: without it, Joomla saves a site menu (client_id 0)." }, "preset": { "type": "string", @@ -117109,7 +117155,7 @@ "alias": { "type": "string", "title": "Alias", - "description": "The Alias will be used as part of the URL.", + "description": "The Alias will be used as part of the URL. Required on create; an empty string is accepted, and Joomla then makes the alias from the title. Without it, saving fails with \"Field 'path' doesn't have a default value\": the path is copied from the alias before the alias is generated.", "x-joomla-form": { "name": "alias", "type": "alias", @@ -117134,7 +117180,7 @@ }, "link": { "type": "string", - "description": "Menu target URL; controller preprocesses it before form loading." + "description": "Menu target URL; controller preprocesses it before form loading. Required on create: its database column has no default, so saving fails without it. An empty string is accepted." }, "menutype": { "type": "string", @@ -117159,14 +117205,21 @@ "type": { "type": "string", "title": "Menu Item Type", - "description": "Joomla form field type; input is validated and filtered according to x-joomla-form.", + "description": "Joomla form field type; input is validated and filtered according to x-joomla-form. An unknown type gives an internal server error (500).", "x-joomla-form": { "name": "type", "type": "menutype", "label": "COM_MENUS_ITEM_FIELD_TYPE_LABEL", "required": "true" }, - "x-source": "administrator/components/com_menus/forms/item.xml" + "x-source": "administrator/components/com_menus/forms/item.xml", + "enum": [ + "component", + "url", + "alias", + "separator", + "heading" + ] }, "published": { "type": [ @@ -118944,7 +118997,7 @@ "alias": { "type": "string", "title": "Alias", - "description": "The Alias will be used as part of the URL.", + "description": "The Alias will be used as part of the URL. Required on create; an empty string is accepted, and Joomla then makes the alias from the title. Without it, saving fails with \"Field 'path' doesn't have a default value\": the path is copied from the alias before the alias is generated.", "x-joomla-form": { "name": "alias", "type": "alias", @@ -118969,12 +119022,12 @@ }, "link": { "type": "string", - "description": "Menu target URL; controller preprocesses it before form loading." + "description": "Menu target URL; controller preprocesses it before form loading. Required on create: its database column has no default, so saving fails without it. An empty string is accepted." }, "menutype": { "type": "string", "title": "Menu", - "description": "Joomla form field menutype; input is validated and filtered according to x-joomla-form.", + "description": "Joomla form field menutype; input is validated and filtered according to x-joomla-form. Not checked against the existing menus: an unknown menutype saves an item that belongs to no administrator menu (client_id 0).", "x-joomla-form": { "name": "menutype", "type": "menu", @@ -118994,14 +119047,22 @@ "type": { "type": "string", "title": "Menu Item Type", - "description": "Joomla form field type; input is validated and filtered according to x-joomla-form.", + "description": "Joomla form field type; input is validated and filtered according to x-joomla-form. An unknown type gives an internal server error (500).", "x-joomla-form": { "name": "type", "type": "menutype", "label": "COM_MENUS_ITEM_FIELD_TYPE_LABEL", "required": "true" }, - "x-source": "administrator/components/com_menus/forms/itemadmin.xml" + "x-source": "administrator/components/com_menus/forms/itemadmin.xml", + "enum": [ + "component", + "url", + "alias", + "separator", + "heading", + "container" + ] }, "published": { "type": [ @@ -119199,7 +119260,9 @@ "required": [ "title", "menutype", - "type" + "type", + "alias", + "link" ] }, "com_menus_post_v1_menus_administrator_itemsResponse": { @@ -138386,7 +138449,9 @@ "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, - "x-selector": "module/client_id or folder/element selects bundled parameter schema" + "x-selector": "module/client_id or folder/element selects bundled parameter schema", + "minProperties": 1, + "description": "Required on create: its database column has no default. Send at least one property that the form knows: the form filter drops unknown properties, so an empty object (or one with only unknown properties) is not saved and saving fails." }, "client_id": { "type": [ @@ -140308,7 +140373,9 @@ "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, - "x-selector": "module/client_id or folder/element selects bundled parameter schema" + "x-selector": "module/client_id or folder/element selects bundled parameter schema", + "minProperties": 1, + "description": "Required on create: its database column has no default. Send at least one property that the form knows: the form filter drops unknown properties, so an empty object (or one with only unknown properties) is not saved and saving fails." }, "client_id": { "type": [ @@ -140321,7 +140388,7 @@ 1, "1" ], - "description": "Fixed by the site/administrator route; cannot switch clients with the body." + "description": "Must be 1. The route does not set it: without it, Joomla saves a site module (client_id 0) and answers 404, as the module is not found as an administrator module." } }, "additionalProperties": false, @@ -144127,7 +144194,9 @@ "x-source": "administrator/components/com_newsfeeds/forms/newsfeed.xml" } }, - "additionalProperties": false + "additionalProperties": false, + "minProperties": 1, + "description": "Required on create: its database column has no default. Send at least one property that the form knows: the form filter drops unknown properties, so an empty object (or one with only unknown properties) is not saved and saving fails." }, "rtl": { "type": [ @@ -144370,7 +144439,9 @@ "x-source": "administrator/components/com_newsfeeds/forms/newsfeed.xml" } }, - "additionalProperties": false + "additionalProperties": false, + "minProperties": 1, + "description": "Required on create: its database column has no default. Send at least one property that the form knows: the form filter drops unknown properties, so an empty object (or one with only unknown properties) is not saved and saving fails." }, "metadata": { "type": "object", @@ -144429,7 +144500,9 @@ "x-source": "administrator/components/com_newsfeeds/forms/newsfeed.xml" } }, - "additionalProperties": false + "additionalProperties": false, + "minProperties": 1, + "description": "Required on create: its database column has no default. Send at least one property that the form knows: the form filter drops unknown properties, so an empty object (or one with only unknown properties) is not saved and saving fails." }, "associations": { "type": "object", @@ -163267,7 +163340,9 @@ "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, - "x-selector": "template + client select Params_* schema" + "x-selector": "template + client select Params_* schema", + "minProperties": 1, + "description": "Required on create: its database column has no default. Send at least one property that the form knows: the form filter drops unknown properties, so an empty object (or one with only unknown properties) is not saved and saving fails." }, "client_id": { "type": [ @@ -163707,7 +163782,9 @@ "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, - "x-selector": "template + client select Params_* schema" + "x-selector": "template + client select Params_* schema", + "minProperties": 1, + "description": "Required on create: its database column has no default. Send at least one property that the form knows: the form filter drops unknown properties, so an empty object (or one with only unknown properties) is not saved and saving fails." }, "client_id": { "type": [ @@ -166564,8 +166641,9 @@ "pattern": "^-?[0-9]+$", "x-input-normalization": "Joomla form accepts integer or decimal integer string; optional empty string is form-filter dependent." }, - "description": "User group IDs. UserModel consumes an array although the XML widget is hidden.", - "x-source-model": "administrator/components/com_users/src/Model/UserModel.php" + "description": "User group IDs. UserModel consumes an array although the XML widget is hidden. At least one group: Joomla does not save a user without a group.", + "x-source-model": "administrator/components/com_users/src/Model/UserModel.php", + "minItems": 1 }, "params": { "type": "object",