SG Ground Truth

field settings create update

A create takes description, unique, valid_values, default_value and valid_types. unique and a multi_entity's valid_types never change afterwards; an entity's valid_types and list values do.

  • schema
  • custom-field
  • create
  • write
  • list-field
  • status-list
  • entity-field
  • multi-entity
  • error-handling
  • trap
  • Markdown
  • Source
API

Q Which settings does a custom field take at creation, where does each read back, and which can be changed afterwards?

Endpoint POST /schema/<Type>/fields ; PUT /schema/<Type>/fields/<field>

Docs claim /spec.json types every property value as a string and lists no property names.

Actual

POST list  name, description, valid_values ["alpha","beta","gamma"], default_value "beta" -> 201
POST text  name, description, unique true -> 201     unique reads {"value": true, "editable": false}
POST checkbox  name, default_value true -> 201
POST status_list  name alone -> 400 code 103
  "API schema_field_create() missing required 'properties' [\"valid_values\"]"
POST status_list  name, valid_values ["na","rev","vwd"], default_value "rev" -> 201
POST entity  name, valid_types ["Shot","Asset"] -> 201   valid_types {"value": ["Shot","Asset"], "editable": true}
POST multi_entity  name, valid_types ["Shot","Asset"] -> 400 code 103
  "API schema_field_create() 'valid_types' value expected Array with one element: ..."
POST multi_entity  name, valid_types ["Shot"] -> 201     valid_types {"value": ["Shot"], "editable": false}

PUT list  default_value "zzz" -> 400 "API schema_field_update() 'default_value' not in valid_values : ..."
PUT list  valid_values ["beta"] while default_value is "alpha" -> 200, default_value still "alpha"
PUT status_list  valid_values ["rev"] while default_value is "na" -> 400
  "API schema_field_update() 'valid_values' [\"rev\"] must include the 'default_value' 'na'"
PUT any  default_value null, or "" -> 400 "Request Parameters invalid."
  source {"properties": {"0": {"value": ["value must be filled"]}}}
PUT list  unique true -> 400 "API schema_field_update() invalid property 'unique': ... Valid property
  names: [\"name\", \"visible\", \"description\", \"summary_default\", \"valid_values\",
  \"default_value\", \"custom_metadata\"]"
PUT text (created unique)  unique false -> 500 code 105
  "API schema_field_update() does not support updating 'unique'."
PUT list  {"unique": true, "properties": [description]} -> 200, description changed, unique unchanged
PUT multi_entity  valid_types, any value, the one it holds included -> 400
  "API schema_field_update() can't update 'valid_types' on this field: ..."
PUT checkbox  default_value "false" -> 200, reads back the string "false"

Where each setting reads back, in GET /schema/<Type>/fields/<field> under data

setting path sent at creation as
data type data_type.value top-level data_type
display name name.value property name
description description.value property description
unique unique.value property unique
default value properties.default_value.value property default_value
valid values properties.valid_values.value property valid_values
valid types properties.valid_types.value property valid_types

A status_list also has properties.display_values and properties.hidden_values.

At creation

type sent result
list valid_values, default_value, description 201, all three read back
text unique: true, description 201, unique.value true
checkbox default_value: true 201
status_list name alone 400, valid_values required
status_list valid_values, default_value 201, both read back
entity two valid_types 201. The event log shows a field made on each valid type, sg_versions_<n> (probe 121)
multi_entity two valid_types 400, exactly one
multi_entity one 201. The event log shows a second field retired with it, version_sg_zzprobe_116_multi_entity_versions, the reverse side of the link (probe 056)

After creation, every request a PUT with {"properties": [{"property_name": ..., "value": ...}]}

setting on result
name any applied. The programmatic name and the path do not change
description, custom_metadata, summary_default any applied
valid_values, added or removed list, status_list applied
valid_values without the current default list applied, and the default stays, outside the list
valid_values without the current default status_list refused, 400 must include the 'default_value'
valid_values as [] or a string list refused, 400
valid_values or default_value with a status code the site does not have status_list refused, 400 invalid/missing 'status_list' string (probe 121)
default_value, a valid value list, status_list, checkbox applied
default_value, not a valid value list, status_list refused, 400
default_value null or "" list, status_list, checkbox refused, 400 value must be filled. No request sent cleared a default
default_value currency (probe 117) refused, 400 default value is read-only for all data types except status_list, list, checkbox
default_value as the string "false" checkbox applied as the string: 200 and it reads back "false", not false
valid_types, added, removed or replaced entity applied. Each type added creates a field on that type and each removed retires it (probe 121)
valid_types, a type name in the wrong case entity 500, and the field is retired (probe 121)
valid_types, any value multi_entity refused, 400 can't update 'valid_types' on this field
unique as a property list, currency refused, 400 invalid property 'unique'
unique as a property text created unique refused, 500 does not support updating 'unique'
unique at the top level beside properties list ignored: 200, unchanged
properties: [] any refused, 400 can't create/update with no 'properties'

Teaches

do why
Send every setting in the create all of them are accepted there, and unique and a multi_entity's valid_types are accepted nowhere else
Read <setting>.editable before planning an update unique reads false on every field and valid_types reads false on a multi_entity: both are the refused ones
Give a status_list its valid_values a bare create is a 400
Send booleans as booleans a checkbox default of "false" is stored as a string
Remove a list's default before removing its value a list keeps a default that is no longer a valid value
Do not plan to clear a default null and "" are both refused
Send valid_values and default_value in one PUT when both change one request is checked as a whole and applied as a whole (probe 121)

Probe 019 recorded "two types refused" without the link type. It was multi_entity: an entity field takes several.

Every entry on this site is the output of a probe in probes/. The corpus is generated by running those probes against a live Flow Production Tracking site, not written from memory.

Not affiliated with or endorsed by Autodesk. Flow Production Tracking is their product; this is an independent record of how its REST API answers.