Page MenuHomePhabricator
Create Task
Maniphest T328605

Export TOCData in the action API
Closed, ResolvedPublic
Actions

Description

Using prop=sections returns the "legacy" sections array. But this has some historical artifacts (T319141) and doesn't include top-level extension data for the TOC.

We should add a new prop=tocdata which returns the JSON-serialized form of the TOCData, with the modernized property names and extension data, etc, so we can eventually deprecate the sections property (and uses of SectionMetadata::toLegacyArray()).

$result_array['tocdata'] = JsonCodec::serializeOne( $p_result->getTOCData() )

would be the logical way to write this, but serializeOne is currently private in JsonCodec. But we want a way to get the "array form" of a serializable object, recursively expanding its values as needed, so that we can then give it to the Api framework to encode as JSON or XML or whatever.

Details

Related Changes in Gerrit:
SubjectRepoBranchLines +/-
ApiParse: Introduce prop=tocdata as replacement for prop=sectionsmediawiki/coremaster+19 -2
ApiParse: Introduce prop=tocdata as replacement for prop=sectionsmediawiki/coreREL1_43+19 -2
ApiParse: Introduce prop=tocdata as replacement for prop=sectionsmediawiki/coreREL1_45+19 -2
ApiParse: Introduce prop=tocdata as replacement for prop=sectionsmediawiki/coreREL1_44+19 -2
Customize query in gerrit

Related Objects
Search...

StatusSubtypeAssignedTask
 OpenBUG REPORTNoneT319141 Deprecate prop=sections in action=parse
 ResolvedcscottT328605 Export TOCData in the action API

Event Timeline

cscott created this task.Feb 1 2023, 9:44 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptFeb 1 2023, 9:44 PM
cscott added a parent task: T319141: Deprecate prop=sections in action=parse.Feb 1 2023, 9:44 PM
cscott mentioned this in T319141: Deprecate prop=sections in action=parse.
cscott claimed this task.Oct 30 2025, 2:20 PM
cscott added projects: Content-Transform-Team (Work In Progress), Essential-Work.
cscott edited projects, added MediaWiki-Action-API; removed MediaWiki-Parser.Oct 30 2025, 2:24 PM
cscott moved this task from Unsorted to In Dev on the MediaWiki-Action-API board.
cscott moved this task from Backlog to In Progress on the Content-Transform-Team (Work In Progress) board.
Maintenance_bot added a project: MW-Interfaces-Team.Oct 30 2025, 2:30 PM
BPirkle removed a project: MW-Interfaces-Team.Oct 30 2025, 4:04 PM
gerritbot added a comment.Nov 4 2025, 3:33 AM

Change #1201328 had a related patch set uploaded (by C. Scott Ananian; author: C. Scott Ananian):

[mediawiki/core@master] Deprecate action=parse&prop=sections; introduce prop=tocdata as replacement

https://gerrit.wikimedia.org/r/1201328

gerritbot added a project: Patch-For-Review.Nov 4 2025, 3:33 AM
gerritbot added a comment.Fri, Nov 7, 10:25 PM

Change #1201328 merged by jenkins-bot:

[mediawiki/core@master] ApiParse: Introduce prop=tocdata as replacement for prop=sections

https://gerrit.wikimedia.org/r/1201328

gerritbot added a comment.Fri, Nov 7, 10:30 PM

Change #1203159 had a related patch set uploaded (by Jforrester; author: C. Scott Ananian):

[mediawiki/core@REL1_45] ApiParse: Introduce prop=tocdata as replacement for prop=sections

https://gerrit.wikimedia.org/r/1203159

gerritbot added a comment.Fri, Nov 7, 10:37 PM

Change #1203163 had a related patch set uploaded (by Jforrester; author: Jforrester):

[mediawiki/core@REL1_44] ApiParse: Introduce prop=tocdata as replacement for prop=sections

https://gerrit.wikimedia.org/r/1203163

gerritbot added a comment.Fri, Nov 7, 10:37 PM

Change #1203164 had a related patch set uploaded (by Jforrester; author: Jforrester):

[mediawiki/core@REL1_43] ApiParse: Introduce prop=tocdata as replacement for prop=sections

https://gerrit.wikimedia.org/r/1203164

ReleaseTaggerBot added a project: MW-1.46-notes (1.46.0-wmf.2; 2025-11-12).Fri, Nov 7, 11:00 PM
gerritbot added a comment.Mon, Nov 10, 1:20 PM

Change #1203163 merged by jenkins-bot:

[mediawiki/core@REL1_44] ApiParse: Introduce prop=tocdata as replacement for prop=sections

https://gerrit.wikimedia.org/r/1203163

gerritbot added a comment.Mon, Nov 10, 1:20 PM

Change #1203164 merged by jenkins-bot:

[mediawiki/core@REL1_43] ApiParse: Introduce prop=tocdata as replacement for prop=sections

https://gerrit.wikimedia.org/r/1203164

gerritbot added a comment.Mon, Nov 10, 1:21 PM

Change #1203159 merged by jenkins-bot:

[mediawiki/core@REL1_45] ApiParse: Introduce prop=tocdata as replacement for prop=sections

https://gerrit.wikimedia.org/r/1203159

Maintenance_bot removed a project: Patch-For-Review.Mon, Nov 10, 1:30 PM
ReleaseTaggerBot added projects: MW-1.45-notes, MW-1.44-notes, MW-1.43-notes.Mon, Nov 10, 2:00 PM
cscott moved this task from In Progress to To Deploy on the Content-Transform-Team (Work In Progress) board.Mon, Nov 17, 4:40 PM
MSantos triaged this task as Medium priority.Fri, Nov 21, 10:26 AM
Anomie subscribed.Sat, Nov 22, 7:57 PM

You have a bug. In this API query, parsing a page with a whitespace-only section heading, the output from prop=sections correctly has line and anchor set to the empty string while the output from prop=tocdata incorrectly omits these properties entirely.

"sections": [
    {
        "toclevel": 1,
        "level": "2",
        "line": "",
        "number": "1",
        "index": "1",
        "fromtitle": "API",
        "byteoffset": 0,
        "anchor": "",
        "linkAnchor": ""
    }
],
"tocdata": {
    "sections": [
        {
            "tocLevel": 1,
            "hLevel": 2,
            "number": "1",
            "index": "1",
            "fromTitle": "API",
            "codepointOffset": 0
        }
    ],
    "extensionData": []
}

The linkAnchor also seems to be omitted in general, but that's defensible as a removal of redundancy in the new format since it's generally the same as anchor (unless % characters are involved).

cscott mentioned this in T410979: Document (and/or tweak) TOCData API representation.Tue, Nov 25, 3:59 AM
cscott added a comment.Tue, Nov 25, 4:03 AM

Each field in the TOCData representation has a default value if it is not present; the default value for 'line' and 'anchor' is the empty string. The default value for 'linkAnchor' is 'anchor'. https://github.com/wikimedia/mediawiki-services-parsoid/blob/08d22d0c01e135ddc850fcbeb50def29904cfe4d/src/Core/SectionMetadata.php#L340

This output is correct, but this behavior needs to be documented: T410979: Document (and/or tweak) TOCData API representation.

cscott closed this task as Resolved.Tue, Nov 25, 4:03 AM

resolving this bug; follow ups in T410979: Document (and/or tweak) TOCData API representation.

Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL · Credits