Skip to content

feat(rows): return the object shape as XML on api/2 - #67

Draft
rjzondervan wants to merge 5 commits into
feat/3096/2-object-writefrom
feat/3096/3-object-xml
Draft

rjzondervan wants to merge 5 commits into
feat/3096/2-object-writefrom
feat/3096/3-object-xml

Conversation

@rjzondervan

Copy link
Copy Markdown
Member

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-write at 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=object now works in XML on GET /api/2/{tables|views}/{nodeId}/rows, GET …/rows/{rowId}, POST …/rows and PUT …/rows/{rowId}. The "object shape is only available as JSON" 400 is gone, and so is rowShapeFromRequest(), which only wrapped RowShape::fromRequest() once the refusal was removed.
  • New RowObjectXmlShaper maps the JSON object shape to data that the OCS XML writer can render:
    • The metadata becomes <self/>, with each @self member as an attribute. An attribute whose value is null is left out.
    • Each column is an element named by its technical name.
    • A key that is not a safe element name falls back to <element name="…">, with a scalar value in <value>. That covers a numeric technical name from an unvalidated import, and the reserved element and self. OCS cannot write attributes and text on one element.
    • null is nil="true". Plain nil, not xsi:nil, because an undeclared namespace prefix is not well-formed. An empty string and an empty list are empty elements without nil.
    • Booleans are true/false, lists are <element> items, nested objects (a link's title/url/providerId) are child elements, and floats are written as json_encode writes them.
  • The shaper runs whenever the format is not json: without a format, OCS answers in XML too. The 400 validation error of an object-shape write is shaped the same way.
  • JSON responses are unchanged. openapi.json and openapi.ts are regenerated with the updated parameter docs.

Example row:

<element>
  <self id="0199e3a0-…" rowId="7" tableId="3" createdBy="alice" createdAt="2026-10-16T14:30:00+00:00"/>
  <name>Alice</name>
  <amount nil="true"/>
  <done>true</done>
  <options><element>2</element><element>5</element></options>
  <website><title>Nextcloud</title><url>https://nextcloud.com</url><providerId>url</providerId></website>
  <element name="12"><value>imported</value></element>
</element>

Checks run locally

  • phpunit 901/901 (including rendering through the OCS V1 and V2 XML writers, parsed back with DOM), psalm, cs and rector clean, openapi.json and openapi.ts regenerate without a diff.
  • Behat @rows 18/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.5 fputcsv() deprecation in FeatureContext.php:523, untouched here.

🤖 Generated with Claude Code

rjzondervan and others added 5 commits November 19, 2026 14:32
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>
Comment thread lib/Service/RowObjectXmlShaper.php Resolved

@rjzondervan rjzondervan left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 in b31cba6d: only ASCII names (with /D) become elements, everything else goes to <element name>, and a test renders µ, Dž, ᐁ, 𝒜 and größe through V1 and V2.
  • 🟢 The fallback's name attribute could contain characters XML forbids ("a\u0001", invalid UTF-8), so the 400 was not well-formed XML (DOMDocument::loadXML → false). Fixed in e8c2dcf3: the name and every string value and attribute go through xmlString() (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 in 1125128a in 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 the Accept header is left untouched.
  • Value types: int, float (written as json_encode writes it), bool as true/false, nested and listed null as nil="true", usergroup and link objects as child elements, relations as uuid or id.
  • @self and special keys: @self attributes are cast to strings and null ones are left out. The OCS special keys @attributes, @…, $comment and element go to the fallback.
  • Unchanged: the JSON object shape (tested), the cells shape in XML, and the federated refusal. RowShape::fromRequest is still called at all four call sites, and no "only available as JSON" text is left.
  • Spec: openapi.json and openapi.ts match 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, nil and 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant