Option to return rows as objects and accept object-shape writes to API/2 #3096

Is your feature request related to a problem? Please describe.

Frontend components expect flat objects keyed by technical name with readable values when connecting to the API results. Also, most APIs prefer this form of returning data.

Also, on write, invalid values are silently blanked without any feedback per field.

Describe the solution you'd like

We would like to add a query parameter ?shape=object to the API for both the listing and single-row routes. The mapping of this object format will remain mostly the same, but later on a decision might follow to format datetimes according to ISO 8601 or to format selection checks to real booleans.

The metadata fields will be returned in the @self block of the row.

This means that create and update routes need to accept this object format. Also, we would like to give a validation error per property instead of silent blanking. The OpenAPI spec will need to specify named object types and error types for this.

Acceptance criteria:

• every column type round-trips: what you read in object format can be written back
  unchanged;
• an invalid value gives a 400 with an error on that property, never a silently empty field;
• shape=cells and the existing integer-keyed input keep working unchanged;
• datetimes come out with an offset, according to the chosen rule;
• relations come out as uuids, and on write accept a uuid, row id or label;
• CI is green on all four databases.

Describe alternatives you've considered

We considered mapping in the frontend, but that is already rejected in P1.

Another consideration was to allow only reading in the object format, but that breaks consistency, so writing had to be included also.

Also recognising the format by its keys instead of a parameter was considered, but that does not work for reading unfiltered.

Finally, we considered using the original datetime format, but the limited format does not provide a solution for timezones, while the ISO8601 format survives cross-timezone communication.

Additional context

• Milestone M1, Sprint 1
• P1. The Tables API speaks objects, the frontend speaks Tables
• Rows API
• Types and formats

Notes

• Invalid values are currently not rejected: RowService::parseValueByColumnType logs a warning and stores null, and most parseValue implementations return an empty string for input they cannot parse.
• Rows keyed by technical name already exist as dataByAlias; the object shape builds on that.

Relevant files:

• lib/Db/RowCell*Mapper.php (formatRowData, the output per column type);
• lib/Service/ColumnTypes/*Business.php (parseValue, canBeParsed, validateValue, and the
  label-based parseDisplayValue);
• lib/Service/RowService.php (parseValueByColumnType and the write path);
• lib/Service/ImportService.php (the existing conversion from display values);
• lib/Controller/RowOCSController.php (the existing api/2 row routes);
• lib/Db/Row2.php and lib/ResponseDefinitions.php (dataByAlias, TablesRow).

Related issues

This depends on the UUIDs for rows issue (the uuid as id, and relations by uuid) and on the
rows v2 listing issue (the listing that gets the shape parameter). The value mapping per
column type overlaps with the JSON Schema issue; the mapping should be
defined once and used by both.