As a developer I want to be able to edit an entire Wikidata item in one go.
PATCH /entities/items/{item_id}
Request payload
{
"patch": [
{
"op": "",
"path": "",
"value": ""
}
],
"tags": (optional),
"bot": (optional),
"comment": (optional)
}Response to be same as POST /items
Acceptance criteria
- Request includes a JSON Patch document describing wanted changes
- client can provide additional edit metadata: mediawiki tags, edit summary text to append to the automated summary, and a bot edit flag, like in PATCH /entities/items/{item_id}/statements/{statement_id}
- Response to a success request will include the new item data, including the ETag (revision ID) and modification timestamp
- "Automated edit summary":
- if only sitelinks and/or statements were modified, use /* wbeditentity-update:0| */
- if only labels, descriptions and/or aliases were modified, use the same edit summaries as for patching labels, descriptions or aliases, but combining the modified languages across all three fields (see e.g. T332739), i.e. /* wbeditentity-update-languages-short:0||LANGS */ if labels/descriptions/aliases in 50 or fewer languages were modified, and /* wbeditentity-update-languages:0||LANG_COUNT */ if more than 50.
- if both labels/descriptions and/or aliases and also statements and/or sitelinks were modified, use wbeditentity-update-languages-and-other-short instead of wbeditentity-update-languages-short, and wbeditentity-update-languages-and-other instead of wbeditentity-update-languages
- Handle HTTP conditional request headers as in PATCH /entities/items/{item_id}/statements/{statement_id}
- Handle user authentication/authorization like in PATCH /entities/items/{item_id}/statements/{statement_id}
Error cases to consider
| HTTP response code | response payload | |
|---|---|---|
| Item does not exist | 404 | "code": "item-not-found" "message": "Could not find an item with the ID: {item_id}" |
| Invalid item ID | 400 | "code": "invalid-item-id" "message": "Not a valid item ID: {item_id}" |
| Invalid edit tag | 400 | "code": "invalid-edit-tag" "message": "Invalid MediaWiki tag: {tag}" |
| Edit comment/summary too long | 400 | "code": "comment-too-long" "message": "Comment must not be longer than {limit} characters" |
| Request would change the ID of the item | 422 | "code": "patched-item-invalid-operation-change-item-id" "message": "Cannot change the ID of the existing item" |
| Missing a mandatory field in JSON Patch (e.g. "path", "op") | 400 | "code": "missing-json-patch-field" "message": "Missing '{field}' in JSON patch" "context": { "operation": { <PATCH_OBJECT> }, "field": <MISSING_FIELD> } |
| Operation in the JSON Patch is not valid | 400 | "code": "invalid-patch-operation" "message": "Incorrect JSON patch operation: '{op}'" "context": { "op": "{op}", path": "/some/path" } |
| Value provided in the JSON Patch operation is of incorrect type | 400 | "code": "invalid-patch-field-type" "message": "The value of '{field}' must be of type string" "context": { "operation": { <PATCH_OBJECT> }, "field": <FIELD> } |
| Provided JSON Patch document is not valid (generic error) | 400 | "code": "invalid-patch" "message": "The provided patch is invalid" |
| Cannot apply JSON Patch as target path not found | 409 | "code": "patch-target-not-found" "message": "Target '{target}' not found on the resource" "context": { "operation": { <PATCH_OBJECT> }, "field": <PATH> } |
| Test operation of JSON Patch failed | 409 | "code": "patch-test-failed" "message": "Test operation in the provided patch failed. At path '{path}' expected '{expected}', actual: '{actual}'" "context": { "operation": { <PATCH_OBJECT> }, "actual-value": <ACTUAL> } |
| Request payload is not JSON | 415 | "code": "unsupported-content-type" "message": "Unsupported Content-Type: '{content_type}'" |
| Value in the item data after changes is invalid | 422 | "code": "patched-item-invalid-field" "message": "Invalid input for '{field}' in the patched item" "context": { "path": "{field}", "value": "{value}"} |
| Unexpected field for item in patch request | 422 | "code": " patched-item-unexpected-field" "message": "The patched item contains an unexpected field: {"field"}" |
| Statement id cannot be added or changed | 422 | "code": "statement-id-not-modifiable" "message": "Statement IDs cannot be created or modified" |
| Redirected item | 409 | "code": "redirected-item" "message": "Item {item_id} has been merged into {other_id}" |
| Invalid statement group object | 422 | "code": "patched-invalid-statement-group-type" "message": "Not a valid statement group" "context": { "path": "{property_id}" } |
| Invalid statement object | 422 | "code": "patched-invalid-statement-type" "message": "Not a valid statement type" "context": { "path": "{property_id}/{index}" } |
| Statement's Property ID value does not match the key of the statement group | 422 | "code": "patched-statement-group-property-id-mismatch" "message": "Statement's Property ID does not match the statement group key" "context": { "path": "{property_id_key}/{index}/property/id", "statement-group-property-id": "{property_id_key}", "statement-property-id": "{property_id_value}" } |
PATCH sitelink specific errors: https://doc.wikimedia.org/Wikibase/master/js/rest-api/#/sitelinks/patchSitelinks (everything under 422)
PATCH labels specific errors: https://doc.wikimedia.org/Wikibase/master/js/rest-api/#/labels/patchItemLabels (everything under 422, follow the context similar to POST /item).
PATCH description specific errors: https://doc.wikimedia.org/Wikibase/master/js/rest-api/#/descriptions/patchItemDescriptions (everything under 422, follow the context similar to POST /item).
PATCH aliases specific errors: https://doc.wikimedia.org/Wikibase/master/js/rest-api/#/aliases/patchItemAliases (everything under 422, follow the context similar to POST /item)
PATCH statements specific errors: https://doc.wikimedia.org/Wikibase/master/js/rest-api/#/statements/patchItemStatement (under 400: change id and change property, under 422, under 409)
Possibly relevant pointers:
- How Wikibase Action API handles this: https://www.wikidata.org/w/api.php?action=help&modules=wbeditentity
