Field types: a door into the Flow PT corpus

calculated

A calculated field refuses every write with "is read only" and every filter with "cannot be used in a filter", yet it sorts and summarizes fine, and the formula is exposed as calculated_function.

Filter it by rewriting the formula. ["workload", "is", 600] 400s; ["duration", "is", 600] gets the same rows for {duration}. There is no equivalent for CONCAT({code}, {id}): page and match client-side.
Sort is the one query verb that survives: top-N by a computed column is one call, on all four fields.
A float renderer returns a string, so sorted(rows, key=...) on the raw value sorts lexicographically and puts "0.9" after "0.625". Cast before comparing (field_types/float).
A text renderer formats numeric operands for display: CONCAT({code}, {id}) on id 1226 gives "charA1,226", a thousands separator inside a string a client might parse back.
Division by null yields null, not an error: workload_per_day_per_assignee is null on 21 of 40 rows where {workload_assignee_count} is 0. Fill rate measures the operands, so drop the type from fill ranking (probe 007).
default_value is present in properties and always null. Nothing sets it; do not read it as the value of an unpopulated row.

corpus/findings/field_types/calculated.md

checkbox

A checkbox is two-state, never null - an untouched row already reads false, null is unwritable and unfilterable, and the only relations are is/is_not, so fill rate reads 100% on every checkbox.

Fill rate is meaningless on this type. Every checkbox on every row is non-null, so a fill-rate scan reports 100% for all four Version checkboxes while every row holds the same value (probe 007). Drop data_type == "checkbox" from fill ranking before scoring; no threshold separates an informative checkbox from a dead one.
The is_not None fill-rate filter that works on every other type 400s here, in both _search and _summarize (probe 020). Special-case the type; do not catch the 400 and score 0.
_summarize returns the UI glyph, not the value, so the empty-group trick that yields an empty count on a list field ([('<value>', 99), ('', 1)]) never sees '' here and reports the field fully populated.
A checkbox can be refused on both paths. Note.client_note is editable: false and answers 400 API create() Client Notes can not be created through the API to a create sending true and 400 API update() Note.client_note is editable on create only. to every update, false included, so there is no value a caller can put in it (probe 069).
Strings coerce on read and write ("true" -> True), so a checkbox set from a CSV or a form post works until someone sends "1". That 400s with a different error shape (Invalid data for 'checkbox' data type, under source) than a bare 1 (expected [String, FalseClass, TrueClass] ... got Integer). Match on the status, not the title.

corpus/findings/field_types/checkbox.md

color

Task.color holds the token pipeline_step rather than a colour: read step.Step.color in the same dotted call and keep a client default. A real value is decimal r,g,b, never hex.

Never treat Task.color as a colour. A swatch renderer parsing it as r,g,b gets pipeline_step on every row this site has and must follow step.Step.color instead.
Decimal r,g,b, no spaces and no #, matching Status.bg_color (probe 010). Hex is rejected on write and on filter. Build it with "%d,%d,%d" % rgb, split on , to read.
No Task.color row on this site is empty and a written null is refused, so a fill-rate count over it reads 100% and measures nothing (probe 007).
A bad filter value is a 400 on Step and Project but a silent 0 rows on Task.
Writing a legacy name is lossy: "Red" stores 253,1,0 and never reads back as "Red", so filtering on the name it was written with returns 0.

corpus/findings/field_types/color.md

date

A date is the string "YYYY-MM-DD" and nothing else: any timestamp 400s on write and as a filter value. Every negating operator (is_not, not_in, not_in_last) also matches rows that are null.

Every negating operator also returns null rows. is_not "2026-09-02", not_in [...] and not_in_last [1,"MONTH"] each matched the row with no date. Use is_not null for "has a value"; it is the only filter that means that.
A date never accepts a timestamp, on write or as a filter value; date_time accepts both "2026-09-02" and "2026-09-02T00:00:00Z". That and the read shape are the only differences: the operator list and the relative-value shapes are identical between the two types.
between with a null endpoint returns 0 rows and no error. Use greater_than / less_than for an open-ended range; they are strict, not inclusive.
HOUR is a legal unit but the value has no time part, so anything under 24h collapses to today: a date 5 days back missed in_last [1,"HOUR"] and matched in_last [200,"HOUR"].
"" is not a distinct empty state: it is written, filtered and read back as null.

corpus/findings/field_types/date.md

date_time

Stored and read as UTC YYYY-MM-DDTHH:MM:SSZ: a written offset is silently normalised, a zoneless string is taken as UTC, and a date-only filter value means midnight UTC, not the whole day.

A written offset is not preserved: 05:06:07+05:00 reads back as 00:06:07Z. Convert to UTC yourself and keep the original zone in your own field if a client must redisplay local wall-clock time.
A zoneless string is assumed UTC, not site-local: "2026-03-04T05:06:07" is not "5am here".
is is exact-second equality, so is "2026-03-04" finds only rows at 00:00:00Z. Match a day with between ["2026-03-04", "2026-03-05"] or in_calendar_day.
"" 400s where a text field accepts it; only null clears. There is no numeric form: epoch integers 400 with the [String, NilClass] type error, epoch strings with the format error.
editable: false on a timestamp means "not editable by a PUT", not "not settable". The 400 says so outright, is editable on create only, and a create body sets both (probe 070). Test the create path rather than reading the flag.

corpus/findings/field_types/date_time.md

duration

A duration is a bare integer of minutes and the unit is on the site: GET /preferences gives hours_per_day and duration_units. A Float truncates toward zero at 200, so round before writing.

The unit is on the site, not on the field. No /schema route names it. Read hours_per_day and duration_units once from GET /preferences, then render.
A Float truncates instead of failing. number 400s on 3.7 (field_types/number); duration takes 90.9 and stores 90. Round before writing an average, a ratio or total/2.
"2:30" is not a duration. The only string the API accepts is one that parses as a number.
Negation includes nulls; comparison excludes them. is_not 480 and not_in [999999] return the null rows too (3 and 4 of 4); greater_than -1 returns only the 2 rows holding a value. A row holding 0 is is_not None, so a field full of zeroes scans as fully populated (probe 007); rank by greater_than 0.

corpus/findings/field_types/duration.md

entity

An entity link is a {type,id} hash under relationships, cleared only by null. Enforce valid_types yourself: it binds on a few fields, is ignored on most, and nothing in the schema marks which.

Validate the type against valid_types client-side, on every field. A client cannot predict which field will protect it, and an unenforced write stores nonsense at 200: sg_task (['Task']) took a Shot and read it back as a Shot.
No project-consistency check. Pointing a sandbox Version at a Shot in another project returned 200 and read back linked, with nothing in the response flagging it. Compare projects before writing.
A wrong type for a real id 400s here only because ids come from one site-wide sequence (250 shots 862..1111 vs 250 assets 1226..3588, zero overlap), so the wrong table holds no such row. That is a lookup miss, not type validation.
Reading attributes alone makes every entity link look absent, and filter[] needs the full {type, id}: [{"id": N}] and bare ints both 400 (probe 017), while a bad ?fields name is silently dropped at 200 (probe 004).

corpus/findings/field_types/entity.md

entity_type

An entity_type field is a bare schema-name string in attributes, validated on write against 290 built-in type names but not against the site's enabled ones, and filtered only by is/is_not/in/not_in.

Not an entity field. entity stores a {type, id} link under relationships and takes the entity vocabulary (type_is, name_contains, nine operators); entity_type stores the type name alone under attributes and takes four. An {type, id} hash 400s on both read and write here.
Filters are case-sensitive, unlike a list, where 'type a' matches 'Type A'. "shot" returns 0 rows with no error, so a lowercased value reads as "nothing matches".
The 290-name legal set is the built-in type table, not the site's schema. Validate against /schema before writing, or store a type name that has no endpoint.
Existing rows hold values the validator rejects: PermissionRuleSet.entity_type reads PermissionRuleSet.HumanUser, and writing that back 400s. Never round-trip a read value into an update.
Four of the five are read-only, and a write to one 400s with is editable on create only.

corpus/findings/field_types/entity_type.md

float

A float reads back as a JSON string rounded to 6 decimals and rejects Integer on both write and filter: send 1.0 or "1.0", never 1; 0.0 and null stay distinct, and 1e-9 silently becomes 0.0.

Integer is rejected on both halves: PUT {"field": 1} and ["field", "is", 1]. A client that computed an aspect ratio as exactly 2 must send 2.0 or "2.0". number is the mirror image; it rejects Float.
The value is a string, so row["attributes"][f] > 1.0 raises and == 1.0 is False. Cast on read.
Precision is 6 decimal places, applied on write, at 200 and without warning. 1e-9 stores as 0.0 and then matches is 0.0, not is None.
not_in returns rows whose value is null, so it is not the complement of in. Intersect it with is_not None for "has a value, but not that one".

corpus/findings/field_types/float.md

image

Only the upload dance sets an image: every value but null 400s, and clearing it also clears filmstrip_image. The value is a presigned URL re-signed per read, so store the row id, never the string.

is_not None matches a row that is still transcoding, so a job that filters and then downloads fetches thumbnail_pending.png. Filter, then check the prefix on each row.
Transcoding took ~38 seconds for a 16x16 97-byte PNG. Poll the field every 5 seconds.
The REST upload never fills image_blur_hash: still null 102 seconds after the thumbnail settled and after a second upload to filmstrip_image. The one sample-project row holding one ('YXFZJ]4U-=ISt8oh…', 68 chars) was made outside REST. Do not wait on it.

corpus/findings/field_types/image.md

jsonb

jsonb filters, where serializable cannot: is, is_not, contains, not_contains, values always hashes. Note.meta stores what you send but is create-only, so nothing written there is ever editable.

The filter on EventLogEntry.audit_trail is a silent no-op. is null and is_not null each return the full unfiltered page, so the two together over-count every row. The field is filterable per the schema, absent from every response, and ignored in every WHERE.
Note.meta is a one-shot slot. A client can seed it at create and never revise it, and there is no update or clear. editable: false in the schema does not predict the create path; a create-time write succeeds where every later one 400s.
A one-element filter array is unwrapped. is [[]] reaches the field as [], which matches null rows, so a stored empty array cannot be selected. contains [{"x": 1}] is unwrapped to the hash and then fails to match an array-valued row.
contains reaches into objects only. A stored array is unmatchable by any containment value: a hash finds nothing and an array is unwrapped first.
Distinct from serializable on every axis but read. serializable has no Valid relations list and cannot be filtered; Task.splits accepts a write at 200 and stores null. jsonb filters with four operators and stores exactly what it is given. Both return a decoded value under attributes.

corpus/findings/field_types/jsonb.md

list

A list is one bare string in attributes; a write outside valid_values 400s and is case-sensitive, while filters are case-insensitive and only is/is_not/in/not_in exist.

Never round-trip a filter value into an update.
An invalid operator 400s (probe 017); an invalid value does not, so a dropdown typo reads as "no rows match".
"list" names the schema, not the value: it holds one string, and an array 400s with expected [String, NilClass].
viewed_by_current_user and Note.read_by_current_user are stored per person, not per row. A write under sudo_as_login reads back for that person alone; the script's own write answers 200 and stores nothing, which is what "writing 'read' reads back 'unread'" was (probe 007, corrected by probe 068).
A list field can name in and not_in in its own Valid relations and evaluate neither. On Note.read_by_current_user, in, not_in and an is value outside valid_values each answer 200 with the caller's unread rows rather than 0 (probe 068). Run a negative control per field.
default_value is applied on create when the field is omitted, so a fill-rate count over a list measures the default, not intent (probe 007).

corpus/findings/field_types/list.md

multi_entity

A bare list replaces the whole link set, but {"multi_entity_update_mode": "add"|"remove"|"set", "value": [...]} adds and removes in place; the field never reads null and null 400s.

Both incremental spellings that live in the query string return 200 having silently replaced the list. The loss is a success response, not an error; send the mode in the body.
A bare list replaces, so an append coded as read-then-PUT loses any link a concurrent writer added between the two calls. Use the multi_entity_update_mode wrapper, not read-modify-write.
in [X] means "links any of X" and not_in [X] means "links none of X", so it matches empty rows, as does is_not. "Links all of X" has no operator: repeat is once per entity, as separate filter rows.
in with only unresolvable ids is field-dependent, so a negative control built that way must be checked per field. On Version.sg_ai_generated_from it returns the rows linking nothing rather than zero rows; on Note.note_links it returns zero rows though rows with an empty list exist (recipes/009). Mixed, in [A, 99999999] returns A's rows. Which side varies, and why, is unprobed.
A dotted path through this field reads back nothing: 200, key absent from attributes, in GET ?fields and in _search alike, while the identical path filters correctly (probe 016). To read the far side, query the child entity filtered by the parent.
Read order is not insertion order (adding B then A read back A then B), so never treat it as a sequence.

corpus/findings/field_types/multi_entity.md

number

A number is a signed 32-bit integer: floats 400, 2**31 is "integer out of range", and 0 is not null, yet is_not and not_in match null rows while greater_than and less_than do not.

Signed 32-bit, not 64. A 64-bit id or seed reaches 2**64-1 and must be stored in a text field (probe 019 saw the same ceiling on a created field). The create path names the cause, PG::NumericValueOutOfRange; the update path says only Invalid statement.
A float is rejected, not coerced. int() anything computed (a mean, a ratio, n/2 in Python 3) before writing it. A numeric string coerces, so "42" works and 42.0 does not.
0 is a value, '' is not a clear. null is the only clear. Following probe 007: a row holding 0 is is_not None, so a number field full of zeroes scans as 100% filled, exactly like a checkbox full of False. Rank a number field by greater_than 0, or by _summarize grouping (probe 020), never by fill rate.
Negation includes nulls; comparison excludes them. is_not 1001 and not_in [999999] return the null rows too (3 and 4 of 4), while greater_than -1 returns only the 2 rows that hold a value. Any "everything except X" filter over a sparse number field silently sweeps in every unset row.

corpus/findings/field_types/number.md

password

A password field reads as a constant seven-asterisk mask on every row, including through a dotted path; it cannot be filtered, sort is accepted and ignored, and it must never be written.

The field passes every generic inspector test (visible: true, ui_value_displayable: true, present in /schema/<Type>/fields) and returns a value, so exclude data_type == "password" by name from field pickers, from row exports and from anything that echoes a read back into a write.
Fill-rate scanning reads 100%, and the is_not None correction 400s. Drop the type before ranking, the way probe 007 drops checkbox.
A sort on a password field is a silent no-op. Validate a user-supplied sort key against the schema rather than trusting a 200 to mean the rows came back ordered.
ClientUser.password_proxy reports editable: true. Treat that as a schema claim only: no probe writes a password field, and neither should a client.

corpus/findings/field_types/password.md

percent

A percent is a bare integer on a 0-100 scale (50% is 50, and 0.5 is rejected as Float), but nothing is clamped, so -1, 1000 and 2**31-1 all store at HTTP 200.

Integer or nothing, on both halves. PUT {"field": "50"} and ["field", "is", "50"] each 400 with expected [Integer, NilClass] ... but got String. int() a value out of a CSV or a form field before sending it.
The 0-100 range is a convention, not a constraint. -1, 101 and 1000000 all store at 200 and read back unchanged, and no properties key declares a bound. Validate before writing, and clamp on read; a percent field is not evidence that its value is a fraction of a whole.
0 is a value and "" is not a clear. Following probe 007, a row holding 0 is is_not None, so a percent field full of zeroes scans as 100% filled. Rank by greater_than 0, never by fill rate.
Negation includes nulls; comparison excludes them. is_not 50 and not_in [50] return the null rows too, 3 of 5; greater_than -1 returns only the 3 rows holding a value. A "not yet at 100%" filter written as is_not 100 sweeps in every unset row.

corpus/findings/field_types/percent.md

pivot_column

A pivot_column is a web-UI task rollup with no REST implementation - it reads null on every row, and write, filter, sort and _summarize each fail with a different error.

These pass every generic test an inspector applies (visible: true, ui_value_displayable: true, present in /schema/<Type>/fields) and then return null for every row.
Fill-rate scanning breaks twice: the is_not None probe 400s like a checkbox, and the _summarize fallback 500s rather than 400s. A scanner that retries on 5xx retries a permanent failure 45 times per site.
Only the write error names the field. A request that 400s with Read failed for entity type [Shot] gives no clue which sort key caused it; match on code 104 plus the sort you sent.
step_0 exists on types that have no Steps at all, so its presence says nothing about whether the type is task-tracked. Read Step.entity_type for that.

Exclude data_type == "pivot_column" from field pickers and from any payload built by iterating the schema. For the same information, query Task filtered on entity and step, and aggregate sg_status_list yourself.

corpus/findings/field_types/pivot_column.md

serializable

No operator works on a serializable field: every filter 400s as unfilterable. Task.splits answers a well-formed array of hashes with 200 while storing null, so REST cannot write it.

A client cannot query into a blob. No operator means no is None to rank fill rate by (probe 007) and no way to find the rows holding a marker; _summarize (probe 020) has nothing to group on. Fetch rows on some other filter and inspect the decoded value client-side.
Task.splits answers 200 and stores nothing. A client that writes state there and re-reads it cannot tell a discarded write from an empty field. Read back every serializable write.
Two failure layers, two error shapes. A wrong Ruby class gives code 103 with the accepted-class list and an empty source; a right class the setter chokes on gives code 104 with a raw Ruby message and source: null. Neither names the key at fault.
The column takes arbitrary JSON; the field refuses it. EventLogEntry.meta holds nested objects, lists, booleans and nulls, so the storage is a blob. Of the four editable fields three are outside a project: Project.tracking_settings is site configuration, SavedFilter.filters and RvLicense.meta have no project field. A project-scoped blob to write does not exist here.

corpus/findings/field_types/serializable.md

status_list

REST does not enforce hidden_values: a project-hidden status writes and reads back fine, so every client must subtract it itself. Only valid_values is enforced.

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.

corpus/findings/field_types/status_list.md

summary

A summary field is a live rollup: refused on write even where editable=true, unfilterable, unsortable, and null on every custom one here, so re-run the query /schema exposes to select on it.

Fill rate is meaningless on this type. open_notes_count is never null, so it scans as 100% filled while holding one value: 100 Versions all read 0 (probe 007). The other four read null on every row and scan as 0% filled while their queries match rows. Exclude data_type == "summary" from fill ranking; the is_not None probe 400s, as does _summarize grouping.
Sort fails silently. ?sort=code and ?sort=-code return different orders, ?sort=open_notes_count returns the unsorted order, and so does ?sort=definitely_not_a_field: an unsortable field and a typo are indistinguishable at 200.
editable: true describes the field-configuration form in the web interface, not the REST value, and the refusal cites the data type rather than the field. Three of the 42 summary fields on this site claim it, so a client building an update form from editable offers three that can never be saved.
38 of the 42 are open_notes_count, one per entity type, all counting Notes whose status is opn, ip or rdy. That set is the site's definition of "open", readable from properties.query and site configuration rather than an API constant: read it instead of hardcoding the three codes.

corpus/findings/field_types/summary.md

text

A text field has no empty string: writing "" stores null, so is "" and is None are one filter; matching is case-insensitive, whitespace is stripped, and a non-string 400s.

Writing "" returns 200 and stores null. A client round-tripping a form field cannot distinguish "user cleared it" from "never set"; encode that distinction in a sentinel string.
Every operator is case-insensitive, including is. There is no case-sensitive text match. Filter broadly and re-check the case client-side.
is_not and not_contains return the null rows, so is_not X is not the complement of is X. is '' matches exactly the rows contains '' skips.
Leading and trailing whitespace is stripped on write, silently, so ' ' is stored as null.
cached_display_name reports editable: True and accepts a write at 200, then discards it. It mirrors code, and re-reads as the new code after a rename. Never write it.
in [None] teaches nothing: code 104, source: null, detail: null. Use is None.

corpus/findings/field_types/text.md

timecode

A timecode stores milliseconds as a signed 32-bit integer. No schema or preference names its frame rate, but a _summarize group_name renders HH:MM:SS:FF and the rate solves out of that.

The rate is real but hidden. Solve it once per site from two _summarize writes and store it; a client that guesses 24 or 25 is wrong by a frame inside the first second.
A timecode field rejects timecode strings. "01:00:00:00" and the drop-frame "01:00:00;00" both 400 on write and again inside a filter, and a numeric string does not coerce the way it does for number and duration. Send int milliseconds.
Nothing is validated as a time. -3600000, 86400001 and 2147483647 all store, and render as -1:59:59:00, 24:00:00:00 and 596:31:23:16; -1 renders as -1:59:60:00, a 60th second. Range-check before writing. The API only enforces the 32-bit column.
Negation includes nulls; comparison excludes them. is_not 3600000 and not_in [999999999] return the null rows too (3 and 4 of 4), while greater_than -1 returns only the 2 rows holding a value. A row holding 0 is is_not None, so a field full of zeroes scans as fully populated (probe 007); rank by greater_than 0.
A new field belongs in text, not here. Every stock field a cut or a source clip uses for timecode is text plus a number rate, which round-trips HH:MM:SS:FF and survives drop frame.

corpus/findings/field_types/timecode.md

url

The value is a presigned link re-minted on every read and expiring on X-Amz-Expires, so persist the Attachment id and re-read. No filter relation exists at all, and sort is a 200 no-op.

"Has media" is not a query. Page the rows with fields=sg_uploaded_movie and test the value client-side. _summarize refuses with the same message under API summarize() (probe 021), so a fill-rate scan must special-case data_type == "url".
The filterable neighbours are proxies, not answers. image is_not None and sg_uploaded_movie_transcoding_status is_not None both matched exactly the media-holding rows on the sample project, and on two Versions uploaded and then cleared both still matched the row after sg_uploaded_movie had gone null. A picker built on either offers Versions with no media.
The url is regenerated per read and signed with an expiry. Anything that caches it (a database column, a rendered page, a message to a chat client) serves a dead link once it lapses.
Read link_type before anything else. upload and web are indistinguishable by keys, and a local value has no url key at all, so indexing value["url"] raises on the shape a published file uses.

corpus/findings/field_types/url.md

uuid

A uuid field is server-generated and rejects every write with "is read only", so it cannot hold your key; it filters on is/is_not/in/not_in only, and a malformed value 400s.

is null is a 400, not a filter. Use is "" for "unset" and is_not "" for "set". The empty string is legal only with is and is_not: in [""] fails as a malformed uuid.
A malformed filter value 400s the whole read. Code 104 invalid input syntax for type uuid surfaces the database. A prefix, a urn:uuid: form, surrounding whitespace and any non-uuid string all fail. Validate client-side; there is no partial match to fall back on, since contains is unsupported.
is_not and not_in return the rows where the field is null, so is_not X is not the complement of is X. Add is_not "" to exclude them.
Sorting on a uuid field fails, on both spellings: GET /entity/icons?sort=uuid and _search with "sort": "uuid" return 400 code 104 Read failed for entity type [Icon], with source and detail null. sort=id on the same endpoint returns 200. Page by id and sort client-side.
It cannot be your correlation key. A uuid field is generated by the server, is not unique, and refuses every write. To tie a Flow PT row to a record in another system, put your identifier in a text field, which is writable and supports is, in and contains.

corpus/findings/field_types/uuid.md