uuid: Flow PT field type reference

Data type uuid, probed on Icon.uuid (98 rows, every one filled and distinct) and EventLogEntry.session_uuid (filled on a minority of rows, and repeated across them). On the probed site a sweep of /schema/<Type>/fields over all 114 types in /schema found four uuid fields and no others. Every one reports editable: false, mandatory: false, unique: false and ui_value_displayable: false; properties holds only a null default_value and summary_default: "none".

field	on an entity a client can create	filled on the probed site
`Icon.uuid`	no; `Icon` has no editable field	98 of 98, all distinct
`LocalStorage.uuid`	the entity is creatable, but it is site configuration, not project data	1 of 1
`WorkDayRule.uuid`	no; the entity itself is read only	8 of 8, all distinct
`EventLogEntry.session_uuid`	no; the server writes these rows	13 of 500 sampled, all 13 the same value

Read A 36-character canonical lowercase hyphenated string under attributes, never under relationships. It is in the default field set, so it is returned even with no fields param. Absent means null. On the probed site every value is version 1 (...-11df-..., ...-11f0-...).

GET /entity/icons/<id>?fields=uuid -> 200
{"type":"Icon","attributes":{"uuid":"11111111-2222-11df-8888-999999999999"},
 "relationships":{},"id":<id>,"links":{"self":"/api/v1/entity/icons/<id>"}}

Write There is nothing to write. Every value shape gets the same rejection at the same layer, before the value is looked at.

sent to `PUT /entity/event_log_entries/<id>` as `session_uuid`	status
`"3f2504e0-4f89-11d3-9a0c-0305e82c3301"` (canonical)	400 code 103 `API update() EventLogEntry.session_uuid is read only.`
`"3f2504e04f8911d39a0c0305e82c3301"` (hyphens stripped)	400, the same title
`"3F2504E0-4F89-11D3-9A0C-0305E82C3301"` (uppercase)	400, the same title
`"not-a-uuid"`	400, the same title
a uuid already held by another row	400, the same title
`12345`	400, the same title
the value the field already holds	400, the same title

source is {} and detail is null on all of them; Icon.uuid and LocalStorage.uuid answer identically. WorkDayRule rejects one step earlier, on the entity, update and create alike:

PUT  /entity/work_day_rules/<id>  {"uuid": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"} -> 400
POST /entity/work_day_rules       {"uuid": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"} -> 400
 {"status": 400, "code": 103, "title": "Action not allowed", "source": null,
  "detail": "Cannot edit read only entity 'work_day_rules'"}

Whether the server rejects a duplicate is unanswerable from the API: no write reaches the column. The schema declares unique: false, and EventLogEntry.session_uuid holds one value on 13 rows, so duplicates exist by design.

Clear

sent	result
`null`	400 `... is read only.`
`""`	400 `... is read only.`
key omitted from the PUT	unchanged; the field is never touched

A value is generated once when the row is created and never reissued.

Filter POST /entity/<slug>/_search, Content-Type application/vnd+shotgun.api3_array+json (probe 004). A bogus relation names the vocabulary; all four fields answer with the same list:

[["uuid", "definitely_not_an_operator", null]] -> 400 code 103
title:  "API read() Icon.uuid's 'uuid' data type doesn't support
         'definitely_not_an_operator' 'relation'"
source: {"Icon.uuid": " ... Valid relations: [\"is\", \"is_not\", \"in\", \"not_in\"]"}

Value shapes is takes, against 98 Icon rows holding 98 distinct uuids:

value	returns
the value as read	1
uppercase, mixed case, hyphens stripped, or both	1; normalised before matching
`"{11111111-2222-11df-8888-999999999999}"` (brace wrapped)	1
`"00000000-0000-0000-0000-000000000000"`, any unused uuid	0
`""`	0 here; matches exactly the rows where the field is `null`
a prefix, a `urn:uuid:` form, a padded value, `"not-a-uuid"`	400 code 104 `Please check your filters for possible invalid value, invalid input syntax for type uuid: "11111111". -- Read failed for entity type [Icon]`
`null`	400 code 103 `API read() Icon.uuid expected [String] data type(s) but got NilClass: nil`
`12345`	400 code 103 `... but got Integer: 12345`

Each operator, over 98 rows where the field is filled and over 5 rows where it is null:

operator	value	matches	filled rows returned	null rows returned
`is`	`"11111111-2222-11df-8888-999999999999"`	the one row holding it	1 of 98	0 of 5
`is`	`""`	the rows where the field is `null`	0 of 98	5 of 5
`is_not`	`"11111111-2222-11df-8888-999999999999"`	every other row, `null` rows included	97 of 98	5 of 5
`is_not`	`""`	every row holding a uuid	98 of 98	0 of 5
`in`	`["11111111-2222-11df-8888-999999999999", "22222222-3333-11DF-8888-999999999999"]`	the rows holding either, mixed case and hyphenation	2 of 98 for two values	0 of 5
`in`	`"11111111-2222-11df-8888-999999999999"` (bare, not a list)	one row; a scalar where a list is expected	1 of 98	0 of 5
`in`	`[]`	400 code 103 `API read() 'in' 'relation' expects at least a 1-element array: []`
`in`	`[""]`	400 code 104, `invalid input syntax for type uuid: ""`
`in`	`[null]`	400 code 103, `expected [String] data type(s) but got NilClass: nil`
`not_in`	`["11111111-2222-11df-8888-999999999999", "22222222-3333-11DF-8888-999999999999"]`	every other row, `null` rows included	96 of 98 for two values	5 of 5
`contains`	any	400, the `Valid relations` list again
`not_contains`	any	400, the same body
`starts_with`	any	400, the same body
`ends_with`	any	400, the same body
`greater_than`	any	400, the same body

_summarize (probe 020) takes the field: grouping exact gives one group per distinct value, and a count summary gives the filled count.

Traps

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.