Repository navigation
feat(rows): return the object shape as XML on api/2 - #67
rjzondervan wants to merge 5 commits into
Conversation
The object shape of api/2 was refused for any response that is not JSON, because the OCS XML writer turns the @self key into an attribute and fails on its array. RowObjectXmlShaper now maps the JSON shape to data the OCS writer renders: <self/> with the metadata as attributes, an element per column named by its technical name, <element name="..."> for a name that is not an NCName (or is element or self), nil="true" for null, true/false for booleans and <element> items for lists. getRows, getRow, createRow and updateRow apply it for every response OCS renders as XML, as does the validation error of an object-shape write. JSON responses are unchanged. Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
Unit tests for RowObjectXmlShaper, rendering through the OCS V1 and V2 XML writers, the controller answering the object shape and its validation errors in XML, and a Behat scenario that reads a row and a refused write with format=xml. Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
XMLWriter refuses some names that Unicode counts as letters (µ, Dž, 𝒜),
so a row key or a validation-error key such as {"µ":1} threw a
ValueError while OCS rendered the XML, a 500 after the controller
returned. The direct element name is now ASCII only, anything else
takes the <element name="..."> fallback. The pattern also gets the D
modifier, so a trailing newline no longer slips past `$`.
The docblocks and the openapi parameter text describe the new rule; the
test renders µ, Dž, ᐁ, 𝒜 and größe as row and error keys through V1 and
V2 and fails without the fix.
Assisted-by: ClaudeCode:claude-opus-5-5
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Robert Zondervan <robert@conduction.nl>
XMLWriter writes control characters and invalid UTF-8 as they are, so an unknown key such as "a\u0001" or "\xff" in <element name="..."> made a document that is not well-formed. The same held for text and for the @self attribute values, which go through text() as well. The fallback name and every string text() returns are now scrubbed: invalid UTF-8 and characters outside the XML 1.0 Char production become U+FFFD. The test renders such keys, a value and a @self member through V1 and V2, loads them with DOMDocument and fails without the fix. Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
…value":"x"} Under <element name="...">, a scalar is held in <value>, so it renders the same as an object whose only property is value. No column type gives such an object; the shaper's class docblock and the openapi text of the shape parameter now say so. Assisted-by: ClaudeCode:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Robert Zondervan <robert@conduction.nl>
rjzondervan
left a comment
There was a problem hiding this comment.
Verdict: APPROVE (Thorough)
The XML form of the object shape does what it says, on all four row routes and for the validation-error 400. The JSON output stays unchanged. The review found one blocker and two minors, and all three were fixed on the branch before this review was posted (b31cba6d, e8c2dcf3, 1125128a). Nothing is open.
Posted as a comment: GitHub does not allow approving your own PR.
✅ Fixed before posting (3)
- 🔴 The safe-name rule accepted names XMLWriter refuses, so rendering ended in a 500 —
lib/Service/RowObjectXmlShaper.php:47. Fixed inb31cba6d: only ASCII names (with/D) become elements, everything else goes to<element name>, and a test rendersµ,Dž,ᐁ,𝒜andgrößethrough V1 and V2. - 🟢 The fallback's
nameattribute could contain characters XML forbids ("a\u0001", invalid UTF-8), so the 400 was not well-formed XML (DOMDocument::loadXML→ false). Fixed ine8c2dcf3: the name and every string value and attribute go throughxmlString()(mb_scrub, and non-XML-1.0 characters become U+FFFD). Tab, newline, CR and astral characters stay. There is a DOM test for this. - 🟢 Under the fallback,
"x"and{"value":"x"}render the same. No column type produces the latter. Documented in1125128ain the class docblock and the openapi text.
✅ Verified clean
- Format detection:
getFormat() !== 'json'matches what OCS renders. With no format or an unknown one, OCS falls back to XML; JSON requested through theAcceptheader is left untouched. - Value types: int, float (written as
json_encodewrites it), bool astrue/false, nested and listed null asnil="true", usergroup and link objects as child elements, relations as uuid or id. @selfand special keys:@selfattributes are cast to strings and null ones are left out. The OCS special keys@attributes,@…,$commentandelementgo to the fallback.- Unchanged: the JSON object shape (tested), the cells shape in XML, and the federated refusal.
RowShape::fromRequestis still called at all four call sites, and no "only available as JSON" text is left. - Spec:
openapi.jsonandopenapi.tsmatch the docblocks word for word. - Tests: they render through the real V1 and V2 responses and parse the result back. The Behat scenario covers
format=xml, a uuid relation, a link,niland a refused write.
Mode: Thorough · L (8 files, 727 lines, about 145 of them production code).
Gates: not run. This fork has no Hydra Gates job.
CI: still queued at submission.
Local checks: RowObjectXmlShaperTest 24/24 and RowOCSControllerTest 46/46 at 1125128a, run in the dev container. psalm, cs and rector are clean, and openapi regenerates without a diff. The author's run at 71dbe210 passed the full phpunit suite (901) and Behat @rows 18/19; the one failure is a PHP 8.5 fputcsv deprecation in FeatureContext.php:523, which this PR does not touch.
Follow-ups (predate this PR): control characters in text values also produce invalid XML in the cells shape, and ColumnService::importColumn does not validate technical names.
Internal review draft. This PR exists only to run the review skills on the fork before the upstream PR is opened. Its base is
feat/3096/2-object-writeat e69d7ef (the head of #66), so the diff shows only this branch's own commits. The upstream PR description will be written separately.Part 3 of nextcloud#3096: the XML form of the object shape that #65 and #66 left JSON-only. Depends on #66, #65, nextcloud#3095 (#63) and nextcloud#3093.
Changes
?shape=objectnow works in XML onGET /api/2/{tables|views}/{nodeId}/rows,GET …/rows/{rowId},POST …/rowsandPUT …/rows/{rowId}. The "object shape is only available as JSON" 400 is gone, and so isrowShapeFromRequest(), which only wrappedRowShape::fromRequest()once the refusal was removed.RowObjectXmlShapermaps the JSON object shape to data that the OCS XML writer can render:<self/>, with each@selfmember as an attribute. An attribute whose value is null is left out.<element name="…">, with a scalar value in<value>. That covers a numeric technical name from an unvalidated import, and the reservedelementandself. OCS cannot write attributes and text on one element.nil="true". Plainnil, notxsi:nil, because an undeclared namespace prefix is not well-formed. An empty string and an empty list are empty elements withoutnil.true/false, lists are<element>items, nested objects (a link'stitle/url/providerId) are child elements, and floats are written asjson_encodewrites them.json: without a format, OCS answers in XML too. The 400 validation error of an object-shape write is shaped the same way.Example row:
Checks run locally
@rows18/19, including the new "Read and write rows via v2 in the object shape as XML". The one failure is APIv1 "Import a document file that updates existing rows": a PHP 8.5fputcsv()deprecation inFeatureContext.php:523, untouched here.🤖 Generated with Claude Code