PUT /schema/<Type>/fields/<field>
put_schema_type_fields_field
Changes a field's properties. A body changing data_type is a 200 that does nothing, so read the field back rather than trusting the status code.
API
Params
| part | value |
|---|---|
properties |
a list of {property_name, value}, the same shape the create takes. Required and not empty. Several are applied together or not at all (probe 121) |
project_id |
in the JSON body or the query. Required when visible is among the properties, and scopes only visible (probe 115) |
Sample requests
A rename, which works:
r = c.put("/schema/Version/fields/sg_my_field",
json={"properties": [{"property_name": "name", "value": "Renamed"}]})
A type change, which does not:
r = c.put("/schema/Version/fields/sg_zzprobe_040_revive", json={"data_type": "number"})
print(r.status_code)
# 200
c.get("/schema/Version/fields/sg_zzprobe_040_revive").json()["data"]["data_type"]["value"]
# 'text', unchanged
Response codes
| status | when |
|---|---|
| 200 | accepted, which is not the same as applied. The body is the whole field |
| 400 | code 104 The 'visible' property requires a project to be updated. |
| 400 | code 105 The Project with the given project_id does not exist. |
| 400 | invalid property '<name>', followed by the valid property names for that field |
| 400 | Request Parameters invalid. with value must be filled for a null, "" or [] value, on description and name as on the rest |
| 400 | invalid/missing '<property>' value string for a description or name of spaces alone |
| 400 | 'default_value' not in valid_values on a list or status_list |
| 400 | invalid/missing 'status_list' string for a status code the site does not have, the valid codes in source.status |
| 400 | invalid/missing entity for a valid_types name that is no entity type, every type in source.entity_type |
| 404 | Field '<Type>.<field>' does not exist., for a retired field and an unused name alike (probe 119) |
| 500 | code 105 does not support updating 'unique'. on a text field |
| 500 | code 105 API schema_field_update() RuntimeError: User doesn't have permission to configure Field properties. for an Artist (probe 132) |
| 500 | code 100 Shotgun Server Error for a valid_types name in the wrong case, "shot". The field is retired by it (probe 121) |
Edge cases
data_typeis immutable and the API does not say so. The write answers 200 and the value is unchanged. This is the sharpest case of the general rule that a 200 from this API proves the request parsed, not that it happened.- A property the update does not take is a 400 that lists the ones it does. For
hidden_valueson a status field the list wasname,visible,description,summary_default,default_value,valid_values,custom_metadata, with or withoutproject_id(probe 114).hidden_valuescannot be written over REST. - A top-level key the call does not take is ignored when
propertiesis present:{"unique": true, "properties": [...]}is a 200 that applies the properties and leavesuniquealone (probe 116). - Which properties a field takes depends on its
data_type, and the field says so: each one readseditable: trueinGET /schema/<Type>/fields/<field>. Probe 116 has the table. - One refused property refuses the request: the others are not applied.
valid_valuesanddefault_valuesent together are checked against each other, in either order (probe 121). - Changing an
entityfield'svalid_typescreates a field on each type added and retires the one on each type removed. A retired name stays taken (probe 121). - Renaming changes the display name only. The programmatic name is fixed at creation, and a rename does not free the old one for reuse.