As a tool builder I want to be able to change labels of an item so that work in my tool can be saved back to Wikidata.
PATCH /entities/items/{item_id}/labels
The request contains a json body with a mandatory patch key containing a JSON Patch document plus optional metadata: tags, bot, comment.
Response of a successful request:
- 200 HTTP response
- response body containing the updated labels data, using the similar structure as GET /entities/items/{item_id}/labels.
- Should also include ETag and Last-Modified headers of the latest revision ID of the relevant item.
"Autocomments":
- should mimic the wbeditentity behavior when editing labels/descriptions/aliases:
- If the change results in changing labels in not more than 50 languages: /* wbeditentity-update-languages-short:0||LANGS */
- If the change results in changing labels in 51 or more languages: /* wbeditentity-update-languages:0||LANG_COUNT */
- where LANGS is a comma separated list of alphabeticall-sorted language codes of relevant languages (e.g. de, en, es, fi, fr, it). LANG_COUNT is a number of languages with changed labels
- the boundary number of 50 languages is defined in ChangedLanguagesCounter::SHORTENED_SUMMARY_MAX_EDIT constant (not configurable)
Error cases considered:
| error type | HTTP Response code | Response content |
|---|---|---|
| item with the given ID does not exist | 404 | "code": "item-not-found", "message": "Could not find an item with the ID: '{item_id}'" |
| ID provided is not a valid item ID | 400 | "code": "invalid-item-id", "message": "Not a valid item ID: '{item_id}'" |
| Item with the provided ID has been redirected to another item | 409 | "code": "redirected-item" "message": "Item {item_id} has been merged into {other_id}." |
| Invalid JSON patch (general error) | 400 | "code": "invalid-patch" "message": "The provided patch is invalid" |
| incorrect JSON patch operation | 400 | "code": "invalid-patch-operation" "message": "Incorrect JSON patch operation: '<op>'" "context": { "operation": <operation_object> } |
| invalid field type in JSON patch (either of op, path, from is not a string) | 400 | "code": "invalid-patch-field-type" "message": "The value of '<field>' must be of type string" "context": { "operation": <operation_object>, "field": <field> } |
| missing mandatory field in JSON patch (op, path, value, also from on copy/move patches) | 400 | "code": "missing-json-patch-field" "message": "Missing '<field>' in JSON patch" "context": { "operation": <operation_object>, "field": <field> } |
| Target of JSON Patch not found on the object | 409 | "code": "patch-target-not-found", "message": "Target '<target>' not found on the resource", "context": { "operation": <operation_object>, "field": <path> } |
| JSON Patch test operation failed | 409 | "code": "patch-test-failed", "message": "Test operation in the provided patch failed. At path '{path}' expected '{expected}', actual: '{actual}'", "context": { "operation": <operation_object>, "actual-value": <actual> } |
| After changes an invalid language code is used | 422 | "code": "patched-labels-invalid-language-code" "message": "Not a valid language code '{language_code}' in changed labels" "context": { "language": <language_code> } |
| After changes a label is invalid (empty, too long) | 422 | "code": "patched-label-empty"/"patched-label-too-long" "message": "Changed label for '{lang_code}' cannot be empty" / "Changed label for '{lang_code}' must not be more than '{limit}' characters long" "context": { "language": <language_code> "value": <label> (too long label case only) "character-limit": <limit> (too long label case only) } |
| After changes a label is invalid (not allowed characters used) | 422 | "code": "patched-label-invalid" "message": "Changed label for '{lang_code}' is not valid; '{label-text}'" "context": { "language": <language_code> "value": <label> } |
| After changes the item has the exact same label and description in a given language | 422 | "code": "patched-item-label-description-same-value" "message": "Label and description for language code {language} can not have the same value. "context": { "language": <language> } |
| After changes the item has the same label and description in a given language as an existing item | 422 | "code": "patched-item-label-description-duplicate" "message": "Item {dupe_id} already has label "{label}" associated with language code {language}, using the same description text." "context": { "language": <language> "label": <label> "description": <description> "matching-item-id": <dupe_item_id> } |
Note:
- leading and trailing whitespace in changed labels to be trimmed "silently" (i.e. accept the label with leading/trailing whitespace but remove it before saving)
- we allow all patch operations (including "move", "copy", etc) even if they likely are not useful
- Handling content-type: accept both application/json and application/json-patch+json, assume json patch input format - anything else yields a 415 http status code
- Conditional HTTP headers are to be handled as in other PATCH endpoints
Examples:
Add a label in French and Bavarian:
{
{ "op": "add", "path": "/fr", "value": "pomme de terre" },
{ "op": "add", "path": "/bar", "value": "Erdapfel" }
}Remove the German label
{
{ "op": "remove", "path": "/de" }
}Replace English label if it is "tater":
{
{ "op": "test", "path": "/en", "value": "tater" },
{ "op": "replace", "path": "/en", "value": "potato" }
}