entity

Data type entity, probed on stock Version fields. On the probed site 10 of Version's 71 fields are entity: seven editable, plus created_by, updated_by and image_source_entity, which are not.

Read Under relationships, never attributes. ?fields=entity puts nothing in attributes, so a reader that only walks attributes sees every link as absent (probe 003, probe 004):

"relationships": {"entity": {
  "data":  {"id": 1230, "name": "charA", "type": "Asset"},
  "links": {"self":    "/api/v1/entity/versions/17055/relationships/entity",
            "related": "/api/v1/entity/assets/1230"}}}

data is null when unlinked. name is the target's cached_display_name, filled on every type measured, so a picker needs no second call. It matches the target's identity field only because cached_display_name copies it: Delivery reads #<id>: <title>, and a client wanting the raw code or content reads the target (probe 060). A dotted path reads back on a single link (unlike multi_entity, probe 016), but it is typed:

A middle segment outside this field's valid_types drops the key at 200 rather than reading null (probe 059).

Write PUT /entity/versions/<id> with a {"type": ..., "id": ...} hash; identical shape on create (probe 012).

Value is not legal is the only signal for both a wrong type and a missing id, and it has no source and no detail. Every failed write left the previous value intact: no partial update.

Whether valid_types binds is per field, and the schema does not mark which. Every entity field on Version, each sent a type its own list omits, and every other case the type cards measured:

No property in the schema separates the two groups, and the obvious guesses do not survive the table. The count of declared types does not predict it: Version.source_clip and TimeLog.entity each declare one type and are advisory, while Version.project and TimeLog.user each declare one and bind. The sg_ prefix does not predict it either: Version.source_clip has no prefix and is advisory. Two fields on one type can differ, as TimeLog.entity and TimeLog.user do.

A field that binds names the expected type, <Expected> expected, got <Sent>, at code: 104. The last two rows refuse for editability, not for type.

Clear

There is no "empty entity" value, and a cleared link is findable: ["entity", "is", None] matches the row.

Filter A bogus relation makes the API name the whole vocabulary (probe 017), here verbatim from errors[0].source["Version.entity"]:

Valid relations: ["is", "is_not", "name_contains", "name_not_contains", "name_is", "type_is", "type_is_not", "in", "not_in"]

Three value shapes across the nine. Row counts against a 100-Version baseline, where 862 stands in for the id of the Shot sh010_0010 names:

Every shape outside that column 400s: [{"id": N}] and bare ints throughout, a list for is/is_not, a hash for type_* and name_*, null for the name_* three.

Dotted paths work, and every negative control returns 0 rather than the baseline:

Traps

• 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).