Skip to content

Required fields: what a POST needs to save a new item - #10

Open
HermanPeeren wants to merge 1 commit into
joomla-projects:mainfrom
HermanPeeren:fix/required-fields
Open

HermanPeeren wants to merge 1 commit into
joomla-projects:mainfrom
HermanPeeren:fix/required-fields

Conversation

@HermanPeeren

Copy link
Copy Markdown
Collaborator

The required lists and minimal examples of POST request bodies now match what Joomla needs to save a new item. I sent each minimal example to a Joomla 6.2 site, then left out each required field in turn, and checked the causes in joomla-cms 6.2-dev. Any 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, so Joomla created 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 (site and administrator): alias is required, and an empty string is accepted. MenuTable::check() copies the alias into path before store() makes an alias from the title, so with no alias path is null and the insert fails. Administrator items also need link. type now has an enum: an unknown type, as in the old example, gives a 500 because no itemadmin_<type>.xml form exists.
  • Articles: introtext or articletext is required (anyOf).
  • Required JSON objects (params of banners, fields, modules and template styles; images, metadata and params of newsfeeds): minProperties: 1. The form filter drops an empty object, or one that has only unknown keys, so the column stays null.
  • Users: groups gets minItems: 1.
  • Administrator menus and modules: client_id was described as "fixed by the route", but the route does not set it. Without it, Joomla saves a site menu or a site module, and for the module it answers 404.
  • Media files: the mediatypes query parameter is now described. Without it, only image extensions are accepted, so the old .txt example failed. The minimal example now uploads a 1×1 PNG.
  • Redirects: the minimal example used the same old and new URL, which Joomla rejects.
  • Messages: POST saves the message, but Joomla 6.2 answers 404.

Notes for the reviewer

  • This branch conflicts with Request defaults: what the webservices do with an omitted field #9 (fix/request-defaults) in two places: the ## Unreleased section of the CHANGELOG, and the minimal example of POST /v1/redirects. Both branches add published; this branch also changes the URLs. Whichever branch merges second needs a short rebase.
  • I did not test contacts/form/{id} (it sends mail) or the joomlaupdate POSTs (they start an update).
  • I removed the test items from the local site afterwards.

Not fixed here (possible follow-ups)

  • POST /v1/languages/overrides/site/{lang_code} wrote to administrator/language/overrides/en-GB.override.ini, and the response had an empty id. The spec's claim that POST takes app and lang_code from the route looks wrong. Not investigated further.
  • PATCH /v1/menus/site/items/{id} with only {"published": -2} gives a 500.
  • POST to a fields or field-groups route without context answers 404, but it still saves a field with an empty context.

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.
@HermanPeeren HermanPeeren added the accepted-breaking-change A breaking change that corrects the spec to match Joomla label Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

accepted-breaking-change A breaking change that corrects the spec to match Joomla

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant