status_list

Data type status_list. Probed on Version.sg_status_list (stock, editable). Properties are always the same five keys: default_value, display_values, hidden_values, summary_default, valid_values.

Read A bare code string under attributes, never an object and never a relationship. No entity stands behind it, so a dotted path is dropped at 200 (probe 004); the label comes only from display_values (probe 009).

one row: {"type": "Version", "attributes": {"code": "sh010_comp_v001", "sg_status_list": "fin"}, "relationships": {}, "id": <id>}
  attributes keys ['code', 'sg_status_list']   relationships keys []
  distinct over 100 versions: {"rev": 29, "na": 28, "vwd": 21, "apr": 20, "fin": 2}
  'rev' has no label inline; display_values -> 'Pending Review'
  ?fields=sg_status_list.Status.name -> 200 {"sg_status_list": "fin"}    (the dotted key is absent)

Write A raw code, on POST and on PUT.

400 {"status": 400, "code": 104, "source": null, "detail": null, "meta": null,
     "title": "Update failed for [Version.sg_status_list]: 'Final' is not a valid status. Valid statuses:
               'na', 'rev', 'vwd', 'apr', 'custom', 'fin', 'ip', 'clsd', 'cmpt', 'cfrm', 'pndad', 'pndl',
               'pndvs', 'part', 'pass', 'pndng'."}
'zznope' -> same shape: "'zznope' is not a valid status. Valid statuses: <the same 16>"

The 400 enumerates site-wide valid_values, hidden codes included; the write path never consults hidden_values.

Clear

default_value is applied only when the key is absent on create, never on a clear. Cleared rows stay filterable: [["sg_status_list", "is", null]] returned 1 over the sandbox rows after the clears.

Filter Four operators only, no substring family at all:

  sg_status_list definitely_not_an_operator 'x' -> 400
  title:  "API read() Version.sg_status_list's 'status_list' data type doesn't support
           'definitely_not_an_operator' 'relation'"
  source: {"Version.sg_status_list": " data type doesn't support 'definitely_not_an_operator' 'relation'.
       Value: {"path" => "sg_status_list", "relation" => "definitely_not_an_operator", "values" => ["x"]}
       Valid relations: ["is", "is_not", "in", "not_in"]"}

Value format is the raw code, or a list of raw codes for in/not_in, counted over the 100-Version baseline project where nothing is cleared:

Write and filter disagree on the same value:

Byte-identical to a plain list field (Version.sg_version_type): the two types filter the same and differ only in that status_list adds hidden_values and an Icon (probe 010). Both are a strict subset of text's eight (probe 017): contains, not_contains, starts_with, ends_with are 400s here.

Traps

• hidden_values is not a subset of valid_values. On the probed sandbox project Task hides blk and rdy, neither of which valid_values contains, so writing one is 400 while the hidden-but-valid hld writes at 200 and reads back. Subtracting one set from the other is right for offering a choice and wrong for testing a row: a row may hold a code outside the usable set (recipes/005).

• hidden_values is not enforced by the API. REST 201s and 200s on a status the project's UI refuses to offer, so every client must subtract hidden_values itself (probe 009). The API will not do it. Conversely, do not treat a hidden code read back off an entity as corrupt: it is a legal stored value.

• Permitted is not safe. An operator reports that a hidden status set this way can break the web UI for that entity. Unverified: it is not observable through the API (see docs/quirks.md). Until someone checks it in a browser, treat writing a hidden status as something to avoid, not merely as something the server allows.

• A wrong code in a filter is a silent 0 rows, indistinguishable from a status nothing holds.

• Display labels are accepted nowhere. Round-trip through display_values in both directions, and fall back to the raw code when a key is missing.

• No substring operator, so there is no server-side type-ahead over statuses. Fetch valid_values once and filter the list client-side. Sorting and filtering is on the code, which is not alphabetical by label.

• Codes are per entity type: Version has 16, Shot 10, Shot.sg_latest_vendor_status 6. Never reuse a code across types, and read the schema per field, not per entity.

Python equivalent

# usable statuses for a project, then set one
f = sg.schema_field_read("Version", "sg_status_list", project_entity={"type": "Project", "id": pid})
p = f["sg_status_list"]["properties"]
usable = [v for v in p["valid_values"]["value"] if v not in p["hidden_values"]["value"]]
sg.update("Version", vid, {"sg_status_list": "fin"})   # code, not "Final"
sg.update("Version", vid, {"sg_status_list": None})    # clear; "" works too
sg.find("Version", [["sg_status_list", "in", ["rev", "fin"]]])