Skip to content

Latest commit

 

History

History
2141 lines (1797 loc) · 123 KB

AGENTS.md

File metadata and controls

2141 lines (1797 loc) · 123 KB

AGENTS.md

Single source of truth for agents working on abap2UI5 Samples — a collection of demo apps for the abap2UI5 framework. This file owns everything: the folder scheme, the compatibility model, the overview generation rules, and the ABAP code style / app-structure conventions.

These instructions OVERRIDE any default behavior and must be followed exactly.

Language

This entire project is in English. All code, comments, commit messages, PR titles, PR descriptions, and any other text must be written in English.

Pull requests

  • The PR title becomes the squash-merge commit subject — make it describe the change. Before merging, replace any auto-generated title (e.g. a branch name like Claude/...-abc123) with a short descriptive English title that states what actually changed.
  • One topic per PR. A structural change (a generator, a gate, a workflow, this file) must not ride along in a PR titled for an unrelated sample — split it into its own PR so the history stays searchable.

1. Repository layout

Everything lives in one flat package (abapGit FOLDER_LOGIC=PREFIX, STARTING_FOLDER=/src/): every sample is a class directly in src/, beside z2ui5_cl_smp_app_000, the overview app (§3), which is an index and not a sample. There are no subpackages, and no folders under src/ at all.

src/   "abap2UI5 - samples"   every sample, flat — one class per sample, nothing else

node scripts/check-agents-structure.mjs (npm run check:agents, and the agents_structure job on every pull request) holds the tree to that: it refuses a folder under src/, and compares the quoted name above against the <CTEXT> of src/package.devc.xml. A new package needs this section, scripts/lib/scan-samples.mjs and that gate changed in the same commit — otherwise the classes in it are in no catalogue and thirteen gates stay green (see check-orphan-samples.mjs, which is the other half of that lesson).

The subpackages are gone

src/01 ("samples") and src/00 ("system") were flattened away on 2026-09-22. src/01 held the portable samples and src/00/98 ("testing") the apps held back by their purpose; the samples moved up into src/ and the testing package went with its last app (§2). Two packages carrying one rule each — is this portable and is this a demo — and after the clean-out of 2026-09-22 the answer to both is yes for everything in the tree, so the split had nothing left to sort.

Nothing about a sample moved with it: class names never encoded the folder (FOLDER_LOGIC=PREFIX), so this was a move and not a rename.

src/00/02 ("restricted - release/version") and src/00/99 ("obsolet") had gone on 2026-08-12, 00/99 together with the samples it still held. Two categories, not two policies: what made a sample restricted or obsolete is unchanged, there is simply no package standing empty in the tree waiting for the next one.

So a sample that plain OpenUI5 1.71 cannot run — a SAPUI5-only control (sap.suite.*, sap.ui.comp.*, sap.viz.*, …), a control or property introduced after UI5 1.71, or native JavaScript / CSS the sample would have to ship — has no home in this repository today, and neither has a superseded one. Do not park it in src/: every sample there must survive the 702 downport (§2). Either it belongs in samples-stack or samples-controls (§2), or the category has to come back. Re-creating one is a deliberate, self-contained change: add the package, put it into the tree above and into the §2 build table in the same commit, or the checks below fail.

There is no on-premise-only package: main is installed on ABAP Cloud systems as it is, so every sample in the repository must be ABAP Cloud ready. A sample that needs on-premise-only ABAP does not belong in this repository.

The experimental package is gone too

src/00/97 ("experimental") was removed on 2026-09-14, and the fourteen samples it held were promoted into what was then src/01: Z2UI5_CL_SMP_APP_004, _052, _122, _381, _468, _498, _499 and _504 … _510. That is the maintainer decision §2 reserves for itself, taken by hand and recorded here — not a sample graduating because it lints clean.

The package emptied itself in the process, and an empty one does not stay: what it said — not finished yet — has no sample left to say it about. So "experimental" is a verdict, not a folder today. A work-in-progress sample has no package to park in: finish it and it goes into src/, or it stays out of the repository until it is finished.

They spent two commits one level too high on the way, in a folder that has no catalog at all — all fourteen were missing from the overview app and from SAMPLES.md while every gate stayed green.

That no longer goes unreported: node scripts/check-orphan-samples.mjs (npm run check:orphans, and the orphan_samples job on every pull request) refuses a z2ui5_cl_smp_app_* class that does not sit directly in src/. It is the one gate here that does not count tiles — which is why it is the only one that could have caught this: the other thirteen all read the same scan, and the scan never saw these fourteen. A ZZZ helper gets no tile either and is fine; being skipped by a RULE is not the same as being skipped by where the file happens to sit.

Sample numbers are per repository — the prefix is what qualifies them

Z2UI5_CL_SMP_APP_<no> is the name; <no> alone is not. Numbers are handed out inside this repository only, and the three sample repositories reuse each other's freely — 493 is Z2UI5_CL_SMP_APP_493, Hello World, here, and Z2UI5_CL_SMPS_APP_493, a classic FilterBar with variant management, in samples-stack. So are 489 and 490. There is no global number space and there was never going to be one: each repository numbers from its own sequence, and coordinating three of them would buy nothing a prefix does not already give.

What follows, in prose anywhere — this file, the README, a commit message, a comment: name a sample by its class, never by its number alone. Z2UI5_CL_SMP_APP_143 and "sample 143" read the same to somebody who already knows which repository they are in, and only the first one still reads correctly to everybody else. The tables in a generated catalogue are exempt: there the number is a link to the class file, which is the qualification.

There is no Control Library package any more

01/03 "Control Library" is gone (2026-08-12), with all 32 of its samples. 1:1 rebuilds of UI5 demo kit samples are collected in abap2UI5/samples-controls — which rebuilds every official sample against its original view and gates each port on that comparison — and keeping the same original rebuilt in both was pure redundancy: 14 of the 32 were already ported there under the same demo kit sample id, and 12 of the rest carried no sample id at all, only an entity URL, so there was no original to be faithful to. The whole set was imported into samples-controls' todo/ for triage before the packages were removed here and every imported class got its verdict the same day; that staging folder was deleted with the closed triage, so the per-sample verdicts are in samples-controls' git history (todo/README.md at commit 37e77b6), not in its tree.

Do not re-create a Control Library package, and do not add a demo kit rebuild to this repository. A sample that rebuilds one specific demo kit original belongs in samples-controls, full stop. What legitimately stays here is what cannot live there, and it goes into src/ as an ordinary sample:

  • a 1.71-safe variant of a sample whose samples-controls port keeps post-1.71 members for 1:1 fidelity (declared POST_171 there) — this repository is downported to 702, so the restriction matters here and does not there;
  • a sample in samples-controls' hold-out set (ui5/holdout.json), which is deliberately never ported there because it measures its generator;
  • a free-style control demo with no single demo kit original.

These exceptions are the Control Behaviour category (§4), and they are the whole of it: samples that drive a control from the backend — expand a Panel or switch a NavContainer page by ID, open the PDF viewer, step a Wizard — rather than showing what the control is. The catalogue lists them; this file does not count them, because the count goes stale the day a sample is added.

The category was called Control until 2026-08-18, which was the wrong name for exactly this reason: it is the noun samples-controls owns, and a reader who found a five-entry "Control" section in this repository's catalogue had no way to tell it apart from the 300-entry control reference next door except by reading all five. The entries were always legitimate; the heading claimed a scope they never had. Control Behaviour says what they are and keeps control as the search term. A new entry belongs here only if it passes one of the three tests above — otherwise it is a demo kit rebuild and belongs in samples-controls, full stop.

A test or scaffolding app is not written at all unless a unit test in abap2UI5 cannot make the same statement — which since the 2026-09-22 clean-out (§2) is nearly always the wrong way round: the testing package went from 41 apps to none. There is no experimental package any more either (§1).


2. Compatibility model — what belongs in this repository

main is the default branch and the only branch anyone commits to. It is installed both on standard on-premise systems and on ABAP Cloud, so it is checked against both releases on every pull request. 702 is the one derived branch, generated from main by publish-702.

Every build sees the same tree:

Build (workflow) What it does Sees src/
abap-standard abaplint ./abaplint.jsonc (syntax v750) ✅
abap-cloud abaplint abap_cloud.jsonc (syntax Cloud) ✅
abap-702 npm run downport → abaplint abap_702.jsonc ✅

Nothing is stripped any more. The 702 build used to delete src/00 before downporting, because the samples held back by their purpose had no business on a branch published for old systems. That package is gone (§1) and the downport is a pure transformation now: the 702 branch carries every class main carries. With it went scripts/check-strip-lists.mjs and its CI job, which existed to keep the removal spelled identically in package.json and in the table above — there is no list left for the two to disagree about.

The clean-out that made this possible is recorded below: src/00/98 went from 41 apps to none, and src/00/01 "context" had gone on 2026-08-20 with the two classes it held, z2ui5_cl_smp_context and z2ui5_cx_smp_error. What they offered was generic RTTI, message and conversion helpers, and a sample that reaches for one stops being a single readable snippet — the thing a sample is for. Every caller carries the few lines it actually used.

Nothing is suppressed either. abaplint.jsonc has no noIssues list: every class under src/ is really linted, by abap-standard, abap-cloud and abap-702 alike. Do not introduce one to make a sample pass — a path listed there stops being checked at all, silently.

The abap-702 transformation also produces the derived branch 702 (publish-702, on every push to main). There is no cloud branch: ABAP Cloud systems install main itself, and abap-cloud is a check on the pull request, not a publish step. The 702 branch carries the root abaplint.jsonc of main unchanged — the release-specific configs stay under .github/abaplint/ and are passed to abaplint explicitly. Copying abap_702.jsonc over the root config would make the abaplint GitHub App lint the derived branch at syntax v702: the app resolves a dependency from the installed repository's default branch and ignores the branch field, so it would check the downported samples against the un-downported framework in abap2UI5/abap2UI5@main and report every type declared there with WITH EMPTY KEY as unknown. The 7.02 check itself is not lost — it runs in abap-702 on every pull request, and again in publish-702 before the push.

Consequence of the rule: a class may only live in src/ if it is ABAP Cloud ready AND downportable to 7.02 and runs on plain OpenUI5 1.71 without any restriction. There is no second package to fall back on: a sample held back by its maturity lost its home on 2026-09-14 (src/00/97 "experimental", §1) and one held back by its purpose on 2026-09-22 (src/00/98 "testing", below).

The way out of src/00/98 was deletion, and it was taken on 2026-09-22. The package held 41 apps; all of them are gone. Not because they were wrong, and not to make room — because the framework's own unit tests now assert, headlessly and on every push, exactly what each of those apps asserted by hand in a browser. Every bare number below is a Z2UI5_CL_SMP_APP_<no> of this repository — the one place in this file where the numbers stand alone, because a list of forty class names says nothing forty numbers do not (§1). The framework wrote them in: z2ui5_cl_ui5_srv_model's test class names samples 118, 138, 184, 190, 194, 199, 212, 332, 334, 338, 339, 343, 344, 347 in its own fixture comments, z2ui5_cl_ui5_app_cont names 335 and 338, z2ui5_cl_ui5_handler names 340. The rest went with them by shape: the reference-identity family (328/329, 331, 333, 336, 337, 342, 345, 348, 349) against aliases_know_owner, shared_one_canonical, both_refs_back_on_table, alias_stays_on_struct, alias_repointed_survives and the app_cont draft roundtrips; the host/sub-app scaffolds (117/126, 131/132, 185, 191, 195, 211) against refresh_finds_late_obj, class_swap_* and load_by_app_after_swap; the binding shapes (094) against the z2ui5_cl_ui5_srv_bind tests structure_levels, reference_deref and helper_attribute; the frontend actions (353, 443, 446, 447) against test_follow_up_action_ctrl / test_ctrl_global_opt on the ABAP side and node/tests/frontendAction.spec.js, messages.spec.js, timer.spec.js, deviceModel.spec.js on the JavaScript side. 086 went as well: it renders a value an app 085 was supposed to set, and no 085 has existed here for a long time.

The last one went with the package: Z2UI5_CL_SMP_APP_324. It called POPUP_TO_CONFIRM dynamically to provoke "Sending of dynpro SAPLSPO1 0500 not possible" — a failure that needs a real dynpro runtime, which no unit test in either repository has. It was the one app the 2026-09-22 clean-out left standing, and it was deleted with src/00 on the same day the tree was flattened (§1): one app is not a package, and a testing app in the middle of the catalogue is a sample a reader would copy.

The rule it stood for is unchanged and is now the whole of it: if a unit test in abap2UI5 can make the statement, the unit test is the place to make it — and if it cannot, that is an argument for a unit test the framework does not have yet, not for an app here. This repository is demos.

A sample restricted by UI5 — a SAPUI5-only control (sap.suite.*, sap.ui.comp.*, sap.viz.*, sap.ui.vk/vbm, sap.ndc, sap.ui.richtexteditor, …), a control or property introduced after UI5 1.71, or a runtime it cannot ship (native JavaScript / CSS / HTML) — and one that is superseded or deprecated have no package here any more (§1), and there is no longer any folder to file one under to get it in.

A sample that needs something the system provides does not belong here at all. Those live in abap2UI5/samples-stack, one package per technology: an OData service, smart controls, a RAP business object, a stateful session, an APC channel, the MIME repository, and the Fiori Launchpad (src/09 there — the demos that read startup parameters, set the shell title and navigate cross-app, moved out of the restricted package on 2026-08-12).

One deliberate exception (maintainer decision, 2026-09-30): the clipboard samples Z2UI5_CL_SMP_APP_538 and Z2UI5_CL_SMP_APP_539. Copy and paste in a table is built on sap.m.plugins.CellSelector (@since 1.119), CopyProvider (@since 1.110) and PasteProvider (@since 1.91), which have no 1.71 equivalent, and on the CopyProvider's extractData callback that abap2UI5 ships as z2ui5/model/clipboard. They sit in src/ like every other sample and say what they need where a reader looks first: (UI5 1.119+) in the DESCRIPT, the @summary and the intro MessageStrip. The ABAP is held to all three builds like every other class; only the linter's two version rules are lifted for exactly these two classes (abap2ui5lint.jsonc). This is not a category — a further post-1.71 sample needs the same decision again.

A sample qualifies for src/ only if none of the above restrictions apply: OpenUI5-compatible, ABAP-Cloud-ready, standalone, every control and property available since UI5 1.71 (16 Jan 2020) and not deprecated, no native JS, not a test, finished and clean. "Old" is not enough and "non-deprecated" is not enough either — a deprecated control and a post-1.71 one both disqualify a sample from this repository, and neither has a package to fall back on any more (§1). ABAP Cloud readiness is not a sorting criterion at all — it is a precondition for every sample in the repository (§1).


3. The overview app

z2ui5_cl_smp_app_000 is the overview app — a generated index page that lists every sample in the repository. It is not a Fiori Launchpad app, despite the name of the generator that writes it (npm run launchpad, §4). The demos that run inside a real Fiori Launchpad are not in this repository at all — they live in abap2UI5/samples-stack under src/09 (§2).

App class Lives in Title Mirrors
z2ui5_cl_smp_app_000 src/ abap2UI5 - Samples src/**

It is the only one, and since the tree was flattened (§1) it mirrors all of it — there is no package left whose samples are reachable by class name only. An extended overview app existed once (z2ui5_cl_sample_app_g01, mirroring the restricted area, cross-linked with this one); it was removed when the extended samples were reorganised. Should a second one ever be needed, it comes back as a second target in scripts/generate-launchpad.mjs and a second row above.

Its shape: a get_catalog( ) method returning a flat table of tiles - one group per stage of the learning path (scripts/lib/learning-path.json, the same six stages catalogue.json publishes and the catalogue page draws), the stage's blurb on the first tile of each group (intro), rendered once under the group title - and a view_display( ) that loops the catalog, emitting one link (header + optional sub) per tile, followed by a sap-icon://source-code core:Icon that opens that sample's ABAP class on GitHub (source_url( ) over the tile's path, wired client-side through open_url( ) like the header buttons — a Button carries no href). It is deliberately an icon and not a transparent Button: a Button brings its own height (2rem even in compact density) and would set the line height of every row, while the icon is as tall as the text beside it — which is what keeps the list tight. Around that list it renders a fixed frame: two header rows (below) and an empty vbox( height = 4rem ) after the last tile so the list does not end glued to the page bottom.

The two header rows

The page carries no content header of its own — both rows are built by hand:

  1. render_header( ) puts a Bar into the page's customHeader, so the row can be split into a left and a right half:
    • contentLeft — the back button and the app title, i.e. what the stock header would render on its own. A Page renders either its own header or a custom one, so title / navbuttonpress / shownavbutton are gone from the page( ) call and the back Button (sap-icon://nav-back, visible = check_app_prev_stack( ), press = _event_nav_app_leave( )) is built here.
    • contentRight — the three sample repositories of the abap2UI5 family, then a gap, then the two entries that leave the system: documentation and GitHub. The gap is the point: the three open an app, the two open a site. It rides on the first icon of the second group (group_start of header_button( ), a wider begin margin), not on a ToolbarSeparator: a sap.m.Bar on 1.71 lays its children out in normal flow, so a block-level separator starts a new line that the bar's overflow: hidden cuts away — which is how the documentation and GitHub icons once vanished on 1.71.
  2. render_sub_header( ) puts an OverflowToolbar into subHeader and holds the SearchField (24rem).

There is no intro text on the page. It used to be a MessageStrip above the list — tile count, the source-code icon, the Ctrl+F12 developer tools, the (A) / (C) markers — which pushed the first samples off the screen; it then moved behind an info icon in the header, and on 2026-08-13 it was dropped altogether with that icon. The page explains itself through its tooltips.

The shared overview header

Every abap2UI5 overview app renders the same entries — here (render_header( ) / header_button( )), in samples-controls and in samples-stack. Five icons, always in this order. header_button( ) takes each entry's name and descr separately: the tooltip is <name> - <descr>, and the name alone titles the popover of an uninstalled repository. The names are the italic ones below. There used to be a sixth entry in front, sap-icon://home for the framework's start page (z2ui5_cl_app_startup) — dropped from all three overviews on 2026-08-13: they list samples, and the start page is not one.

Icon Target Repository
sap-icon://lightbulb z2ui5_cl_smp_app_000 abap2UI5/samples — Samples
sap-icon://palette z2ui5_cl_smpc_app_000 abap2UI5/samples-controls — Control Samples
sap-icon://database z2ui5_cl_smps_app_000 abap2UI5/samples-stack — Stack Samples
sap-icon://learning-assistant — https://abap2UI5.org
sap-icon://globe — the repository the app itself lives in

The repository entries lead to an app inside the system, the last two lead out of it, and every overview shows that split — this one by the gap on the first icon of the second group in its header Bar's contentRight (above), samples-controls and samples-stack by a ToolbarSpacer (width = 1rem) between the groups in their single-row headerContent. The GitHub entry is not sap-icon://source-code: in the shared header that icon is reserved for the per-sample source links an overview renders in its list.

Here the entries are core:Icons, not Buttons (header_button( )), and the reason is the colour: an icon carries one (color), a Button on 1.71 does not — the coloured sap.m.ButtonType values (Critical, Neutral, …) are 1.73+. There are two states, active and inactive, and nothing in between:

Entry Colour Press
the overview app is on this system default (active) cs_event-nav into it
it is not on this system default (active) cs_event-install → install_display( )
documentation / GitHub (no class) default (active) opens the site
the app you are in (here) Neutral (inactive) none

Grey therefore marks exactly one entry — the overview you are already in, which is the only one with nowhere to go. A repository that is not installed looks like any other: it is a destination, the press just explains what has to happen first. The tooltip says so before the click does.

A missing repository stays clickable. Instead of dropping the user on GitHub without a word, the press fires cs_event-install carrying the class, the GitHub URL and the repository name; install_display( ) opens a Popover on the pressed icon — hence every repository icon carries its class name as id — that says what is missing, that abapGit installs it, and links to the repository. Only entries without a class (documentation, GitHub) still open their site directly through open_url( ).

All three overviews carry this header, layout included (2026-08-13): the Bar in the page's customHeader, back button and title on the left, the five icons with their gap on the right, the two colour states and the install popover. samples-controls builds it in scripts/generate-overview.mjs (its overview class is generated — never edit the class), samples-stack in z2ui5_cl_smps_app_000. All three build it with z2ui5_cl_ui5_view_builder, which renders an empty attribute rather than skipping it (color="" is no valid IconColor), so the optional ones are added under an IF. What stays local to a repository is what sits around the family entries — this one's SearchField sub-header, samples-controls' filter toolbar, samples-stack's Regenerate Demo Data button (first in its contentRight, before a separator). A change to an icon, the order, the colours or the press behaviour belongs in all three repositories in the same change.

Each repository is installed on its own, so every icon decides for itself: class_installed( ) instantiates the target class, and on this system the press is cs_event-nav with the class name as its event argument — on_event hands it to app_call( ), which navigates with nav_app_call( ), and the back button returns to the overview. What happens when it is not on this system, and for the overview you are already in, is the table above.

A repository that renames its overview app is installed under both names in the wild for a while, so header_button( ) takes an optional class_old and falls back to it when the current name is not on the system — z2ui5_cl_smpc_app_overview for samples-controls (renamed again 2026-08), z2ui5_cl_demo_app_g00 for this repository. Add the old name there when an overview app is renamed; drop it again once the rename is old enough.

Keep the three headers in sync. A change to the order, the icons or the behaviour belongs in all three repositories in the same change.

The search field filters the tile list: its search event (Enter, or the clear button) fires SEARCH, which re-renders the view with catalog_filter( ) applied — a case-insensitive contains-match against each tile's header, sub, keywords (never rendered, §4) and app class name — and then replays the focus into the search field.

That focus wire is focus_search( ), a set_focus follow-up action with the cursor at the end of what is already typed, and it runs on every display of the page: the overview opens with the cursor in the filter, so the first key you press searches, and after a filter roundtrip typing simply continues. On the way back from a sample it is queued before scroll_restore( ) — focusing a control can scroll it into view, and the restored scroll position is the one that must survive. The info popover keeps naming the total tile count (the unfiltered catalog), an empty filter result renders a No sample matches the filter. text instead of tiles, and the filter value survives navigation into a sample and back (it is a serialized public attribute).

An H3 section title is emitted whenever the group changes — but only when there is more than one group to tell apart. group_titles_needed( ) decides that by comparing every tile's group against the first one; with the whole catalog in a single package the heading would only repeat the page title, so it is left out — and because nothing then separates the first block from the header rows above it, that first block opens with the same sapUiSmallMarginTop the other blocks carry. The title and the stage blurb under it go into one VBox, and that VBox carries the margins (sapUiSmallMarginBegin sapUiSmallMarginEnd sapUiSmallMarginTop sapUiTinyMarginBottom) — not the two controls themselves. Both sap.m.Title and sap.m.Text are display: inline-block, so as siblings of the page they shared a line whenever the blurb happened to fit beside the heading: a long blurb wrapped below its title, a short one sat next to it, and no two groups looked alike. The VBox is what stacks them, and its begin margin is what puts the heading in the same column as the rows, the blurb and the legend instead of one rem to the left of all three. Keep that check free of table expressions (t_catalog[ 1 ]): the 702 downport hoists them out of their guarding condition, so an IS NOT INITIAL guard around one does not survive the transformation.

Navigation is by class name: the tile press event is the app value, on_event (after handling SEARCH, see above) does to_upper( ) → CREATE OBJECT TYPE (classname) → nav_app_call( ), wrapped in a TRY/CATCH cx_root so a catalog entry whose class is missing from the system does not dump — a safety net, not a substitute for keeping the catalog correct. on_event also records the scroll position, which scroll_restore( ) replays via follow_up_action( cs_event-scroll_to ) on check_on_navigated( ), so returning from a sample lands where the user left.

Within a group, view_display( ) also inserts a blank line between blocks: consecutive tiles whose header shares the same base name form one block, and a new block (first row gets sapUiSmallMarginTop) starts when the base changes. The base is the header with a trailing Roman numeral removed (header_base( )) - the category - so Binding, Binding I … Binding VIII render as one block, then a gap, then the Event block, and so on. (A controls section that blocked by first letter existed while the Control Library package did; it went with that package, §1.) Under the list the app prints the legend of the capability markers some titles end in (c_legend, written by the generator from scripts/lib/markers.mjs - the same legend SAMPLES.md and catalogue.json carry, §12). All links of a block share the same width — the estimated render width of the widest header in the block plus roughly one space, precomputed by block_widths( ) / header_width( ) — so the sub descriptions of a block line up exactly underneath each other in one column, directly next to the links.

z2ui5_cl_smp_app_000_0, the old "classic" overview app, is gone with the 00/99 package it was retired to (§1). Do not bring it back — smp_app_000 is the only overview app, and it is generated.

SAMPLES.md — the same catalogue, readable on GitHub

Reaching the overview app costs an installed framework, an abapGit pull and an HTTP handler. Before that, the repository is a flat folder of classes whose names encode nothing, and the question a visitor arrives with — is there a sample for X? — has no answer here.

SAMPLES.md answers it. Every app, its description, its @keywords (the app keeps them for its search box; on a page the reader is the search box, so they are rendered), the @docs chapter that explains what it demonstrates, and a link to the source. Written by scripts/generate-samples-md.mjs from the same scan as the overview app — scripts/lib/scan-samples.mjs, which is the single place that knows what counts as a sample, where its title comes from and which classes are hidden helpers. Two copies of that would drift silently: the app and the page would simply disagree about what this repository contains, and nothing would fail.

Three things it shows that the app does not, on purpose:

Why
the ZZZ helper apps they must not get a tile — but a catalogue claiming to account for the tree has to say they exist
the @keywords never rendered in the app (§4); here they are what Ctrl+F finds
the @docs link the chapter that explains the pattern the sample demonstrates (§4) — the app has no room for it, and a page does

The 702 branch carries its own: npm run downport regenerates the file after the transformation, so the copy on that branch lists what that branch actually ships — which since the strip list went (§2) is everything.

Do not hand-edit it — it is regenerated by npm run launchpad along with the overview app and catalogue.json (below), and the catalogues job of check-docs.yaml checks the three together (§4).

It has readers outside this repository, and they parse the ROWS. Two of them today:

mcp-server lib/examples.mjs the examples MCP tool — an agent asking "has somebody already built X"
docs scripts/link-samples.mjs the Working Samples block under a cookbook page

Both read this file live rather than a generated index, so what they see is always what it says — and both match a row with a regex. Changing the shape of a row breaks them silently. Adding the @docs line as a second <br><sub> block did exactly that: a parser expecting one small-type block matched no rows at all, and the examples tool would have answered "no sample for that" to every query — no error, no log, just an agent taking it at face value and writing the app from scratch.

So a change to row( ) in generate-samples-md.mjs is a change to their input. Grep both repositories for the row regex before merging one, and give them a fixture with the new shape.

catalogue.json — the same catalogue, as data

The fourth view of the one catalogue, and the first one addressed to a machine. The two readers above parse SAMPLES.md rows with a regex because nothing better existed; an AI agent that has just cloned this repository was in the same position. catalogue.json at the repository root is the structured answer: one entry per sample — class, folder, category, learning-path stage, keywords, @summary, @docs links — plus a header naming the repository, its place in the three-repository family, and the number-collision caveat (§1, "Sample numbers are per repository") encoded as data rather than prose. Written by scripts/generate-catalogue.mjs from the same scan as the other three views (scripts/lib/scan-samples.mjs) and the learning-path file it also validates (scripts/lib/learning-path.json), so it cannot disagree with any of them.

It is committed, and it carries no linter pass — that is one decision, not two. Its reader is a clone or a raw fetch, which no deploy ever runs for, so a file that only exists after a build step does not exist for them at all; and staying offline and dependency-free is what lets it be generated anywhere, including in a plain-node CI job. The derived facts that would need the linter live beside it in catalogue-derived.json (see "The catalogue" below). What keeps the committed copy honest is the freshness gate: npm run check:catalogue (in npm run check, and in the catalogues job of check-docs.yaml) runs the generator with --check and fails when the file is stale.

Do not hand-edit it — npm run launchpad rewrites it (or npm run catalogue for this file alone); change the facts on the classes, as always (§4).

scripts/lib/exercises.json — the lessons' exercises

One exercise per sample of the learning path's first stage (Start here, Basics I–VII), for the playground's lesson bar: a task in a sentence or two, a hint, and a check — patterns the rebuilt view XML must match (view), patterns the ABAP must match (source) or no longer match (sourceNot), and the least number of unit tests that must run green (tests). The playground (abap2UI5/browser-playground, writeLessons( ) in tools/build-site.mjs) reads it from the commit it pins and shows the task under "Lesson n of 7", with Check and Hint beside it.

Editorial, like learning-path.json beside it, and kept out of catalogue.json on purpose: that file's shape is a published contract (check-catalogue-contract.mjs). npm run check:exercises (in npm run check) holds it to one exercise per Start-here class and none for any other, patterns that compile, and a sample that does not already pass its own source checks. A change to a Start-here sample can break its exercise — a renamed attribute or event in a pattern — and that gate is where it shows.


4. The overview is ALWAYS (re)generated — schema & rules

Treat the get_catalog( ) table as a generated mirror of the folder tree, never as free-form data. Whenever you add, remove, or move a sample — or change a class's description — regenerate the catalog in the same change.

Nothing regenerates it for you. The catalogues job of check-docs.yaml runs the generators with --check on every pull request and on main, and a stale catalog fails it with the command to run — so regenerate and commit the result with the change that made it stale. Read that diff before you commit it: it is a real change to what the overview offers (a class that stops matching the sample naming scheme shows up there as a deleted tile). Until 2026-09-27 a publish-overview-apps workflow committed the regenerated files onto the pull request branch itself; the runs that commit started waited for a maintainer's approval and left the pull request blocked, so it went.

Regenerate with the generator

Do not hand-edit the catalog. Run the generator, which scans the folders and class descriptions, rewrites the get_catalog( ) block and writes SAMPLES.md (§3) from the same scan:

npm run launchpad      # → generate-launchpad.mjs && generate-samples-md.mjs
npx abaplint           # must report 0 issues

Both outputs come from scripts/lib/scan-samples.mjs, which implements every rule below — that is the file to edit when a rule changes, never the generated ABAP or markdown. The two generators only render: how a tile is written as an ABAP literal (generate-launchpad.mjs, which also decides the groups: the stages of scripts/lib/learning-path.json, through scripts/lib/learning-path.mjs, the one reader generate-catalogue.mjs uses too) and how it is written as a table row (generate-samples-md.mjs).

Tile schema

One row per app, and every row names every field - intro is the stage's blurb on the first tile of a group and intro = `` on every other, keywords is written empty if a class ever lacks the comment line. A row that leaves a field out is initial there on 7.40+, but the 702 branch is the abaplint downport, which builds every row of a `VALUE` in one work area it never clears - a left-out `intro` repeated the first tile's blurb under every tile of its group (§10, VALUE #( ) formatting):

( group = `<stage title>` header = `<display title>` sub = `<short description>` keywords = `<extra search terms>` intro = `<stage blurb, first tile of the group only>` path = `<folder>` app = `<class name, lowercase>` )
Field Meaning / rule
group The title of the learning-path stage the tile's category belongs to (scripts/lib/learning-path.json; the category is the header without its Roman numeral). Becomes the H3 section title (rendered once, when the group changes). Generated - a category no stage names fails the generator rather than landing in a group of its own.
intro The stage's blurb, on the first tile of each group and empty on every other; the app renders it once under the group title. Generated from the same file.
header Link text shown to the user. Derived from the class short text (see below).
sub Short description shown next to the link. Derived from the class short text (see below). May be empty ( ``) → then only the link is rendered.
keywords Never rendered — search only. Extra terms so a sample is found by words that do not fit into the 60 characters of its DESCRIPT (see below). Required on every tile — npm run launchpad refuses an area's overview app if one of its tiles has no @keywords line. Three readers depend on them and all three fail the same silent way (the sample stays listed, stays correct, and never comes up): the overview app's search box, Ctrl+F on SAMPLES.md, and an agent asking whether a sample for X exists. ZZZ helpers are exempt — a helper is reached BY another sample, never looked up.
path The class's folder relative to the repository root (src, for every sample since §1 flattened the tree). Generated, because the class name does not encode the folder — source_url( ) builds the GitHub link of the sample from it.
app The app's class name in lowercase (folder-independent). Drives navigation.

keywords comes from a plain comment line on the class, the first line of the *.clas.abap (above an ABAP Doc block, if the class has one), lowercase and space-separated:

" @keywords f4 search help suggestion input dialog select
CLASS z2ui5_cl_smp_app_009 DEFINITION PUBLIC.

It is a plain " comment on purpose — an unknown "! @tag is reported by the extended check (SLIN/ATC). Put there what a newcomer would type but the visible text cannot hold: synonyms (f4 for value help, alv for the grid table), control names the sample uses (combobox, facetfilter, progressindicator), and the abap2UI5 API it demonstrates (nav_app_call, binding_call, control_by_id) — every framework cs_event-* constant the code passes and every curated client method it calls must be among them, which npm run check:api-keywords holds (§5). Four to eight terms, no backticks. The line is optional — a sample without one is simply found by its header, sub and class name.

@summary is the sentence under the title, a second comment line directly under @keywords — one sentence saying what the sample SHOWS:

" @keywords f4 search help suggestion input dialog select
" @summary The value help, both halves: suggestions while typing and the F4 dialog behind the field, over the same data.
CLASS z2ui5_cl_smp_app_009 DEFINITION PUBLIC.

The two lines answer the two halves of one question. @keywords decides whether somebody finds the sample; @summary decides whether they can tell it is the one they want — which a 60-character DESCRIPT cannot ("Popup - change a popup control from the backend" names the thing and stops). It is rendered in SAMPLES.md directly under the row title, in normal type: everything else in the row is metadata, this is its content.

Required on every tile, and required together: npm run launchpad refuses an overview app whose tile has no @summary, and refuses any sample carrying one of the two lines without the other. ZZZ helpers are exempt, as with @keywords.

The gate is npm run check:keywords (scripts/check-keywords.mjs, and the check-keywords workflow on every pull request). The generator's refusal above is not one: npm run launchpad rewrites the tree, so it is not something a pull request or npm run check can call, and the one workflow that does run it regenerates and pushes — a missing line surfaces there as a job that failed after the catalogue was half rebuilt. The gate also holds three things the generator never sees, because it only ever looked at what becomes a tile: that the @keywords line is the first line of the file (one further down is one a reader scrolls past and a scanner reading the head of a file misses), that the terms are lowercase and at least three of them. 104 classes carried the two lines with nothing checking them; both sibling repositories gated theirs.

Who is held to it is decided from the tree, never from a list: every sample under src/, plus the overview app itself; not the ZZZ helpers (a helper is reached BY a sample, never looked up). The gate names only what it exempts, so a package that came or went needed no edit there — it survived src/00/97 being removed and the flattening of the tree (§1) untouched. A list would need maintaining and would rot; this cannot.

Write it, do not derive it. The sibling repositories can: samples-controls fetches the demo kit's own sentence (ui5/descriptions.json) and samples-stack derives half of its metadata from the package scheme. Here there is no upstream to quote — these apps were written for this repository — so the line is the author's, which is exactly why it needs a gate: nothing else fails when it is missing. Say what the sample demonstrates and what it is good for, not which controls it happens to contain.

@docs is the way back to the documentation, a third optional comment line under @summary, holding one or more full URLs into https://abap2ui5.github.io/docs/:

" @keywords f4 search help suggestion input dialog select
" @summary The value help, both halves: suggestions while typing and the F4 dialog behind the field, over the same data.
" @docs https://abap2ui5.github.io/docs/cookbook/expert_more/value_help
CLASS z2ui5_cl_smp_app_009 DEFINITION PUBLIC.

It is rendered in SAMPLES.md (never in the app — the tile has no room, and a reader who is already inside the overview is not looking for a link out). Full URLs rather than paths, because the line has to be useful where somebody actually meets it: a search engine drops people into a class, and the code was all they got.

Do not add one by hand. The pairing is declared on the documentation side — a cookbook page lists its samples in frontmatter, and scripts/link-samples.mjs in abap2UI5/docs generates the block of sample links on the page and fails when a class it links to does not point back. Adding a line here that no page declares makes that check red. Add the page's samples: entry first; this line follows from it.

The gate is npm run check:docs-links (scripts/check-docs-links.mjs, and the check-docs-links workflow on every pull request). It verifies both halves of a line: that the page exists — docs/<path>.md in abap2UI5/docs, and the #anchor when there is one — and that the page names the class back in its samples: frontmatter.

That second half is the check quoted above, run from this side. It existed only over there, which meant a pull request HERE could add a stale or invented link and stay green until somebody regenerated the documentation; and the first half existed nowhere at all. The scan refuses a URL that is not on the documentation site, which catches a typo in the host and nothing whatsoever about the path — and 95 classes carry one of these lines. Nothing fails when a page is renamed: the class compiles, SAMPLES.md renders the link, and it 404s for every reader who follows it.

It reads the documentation the way check-app-rules reads the shared rule set, and degrades the same way: an abap2UI5/docs checkout next to this one first ($DOCS_HOME, .docs, ../docs) so a developer with the ecosystem cloned is checked offline and in a second; otherwise raw.githubusercontent.com, one request per page; otherwise it says so and passes. A gate must not go red because github.com is unreachable, and must not claim to have verified what it did not.

header and sub come from the class, not from hand-written labels. The source of truth is the app class's abapGit short text <DESCRIPT> in its *.clas.xml, written in the format header - sub:

  • Split the DESCRIPT on the first ` - ` (space-hyphen-space): the part before is header, the part after is sub (which may itself contain -).
  • No - at all → header = the whole DESCRIPT, sub = empty.
  • Unescape XML entities (&amp; → &, etc.) when copying into the ABAP literal.

When regenerating, re-read every class's <DESCRIPT> — the descriptions are maintained on the classes and change there, so never carry header/sub over from the old catalog.

The header is the category — pick one from this list

With the whole catalog in a single package there is no group heading (§3), so the header is the category a reader sees, repeated down the page as the link text. It is also the cheapest search term: typing popup filters the list to the popup samples. Keep the set small, and keep every entry a word a newcomer would actually type:

Header What belongs in it
AI an assistant inside the app — a chat, an explanation of the data on screen — answered by a provider method a real LLM replaces. Samples here run without one; the ones calling a real model need an endpoint and live in samples-stack
Basics I … VII the entry point — first app, lifecycle, the minimum loop, and what you reach for around it (the developer tools, a unit test on the app's own logic, the translation of its texts). The only numbered series: the Roman numeral orders them as a learning path (rule 5 sorts by header), and header_base( ) still renders them as one block
Binding _bind( ), binding syntax, UI5 model types, the model itself
Browser the browser page and tab: URL, title, favicon, reload, clipboard, storage, logout
Control Behaviour one UI5 control is the topic — how it behaves and how the backend drives it, typically by calling its methods by ID. Not a control reference: that is samples-controls, and the header says so (§1)
CSS own styles shipped with the view
Device camera, geolocation, device model, frontend info
Event _event( ), t_arg, keyboard shortcuts, event defaults
File upload and download
Focus / Scroll cursor and scroll position
Formatter the curated JS formatters abap2UI5 ships
Grid Table sap.ui.table.Table — never ui.Table
Hash the URL hash and the app state: hash_set / hash_replace / hash_back, the routing modes (FRESH restarts the app, KEEP returns to its state), app_state_set_active / app_state_get_href — what Back, a bookmark, a reload and a shared link restore
List / Table / Tree sap.m.List / sap.m.Table / sap.m.Tree
Menu / Popover / Popup menus, popovers, dialogs
Message MessageBox, MessageToast, MessageView, message model
Navigation nav_app_call( ) / nav_app_leave( ) between apps
Nested View nest_view_display( ), FlexibleColumnLayout
Templating views generated at runtime (template:repeat)
Timer client timers driving the backend

Do not invent a catch-all (More, Function, Misc, Other) — those existed and were dissolved on 2026-08-13 because nobody searches for them. A new header is justified when at least two samples share a topic none of the above covers; add it to the table in the same change.

Rules for the sub:

  • Title Case, a short noun phrase, max 60 characters for the whole DESCRIPT — that is the hard limit of the ABAP class short text.
  • Name the control or the API the sample is about (FlexibleColumnLayout, SearchField, CustomTreeItem, setSizeLimit, nav_app_call, template:repeat). This is what makes the sample findable — the search matches header, sub and the class name, nothing else.
  • Do not echo the header (Control Behaviour - Wizard Control, Popup - Value Help with Popups).
  • Describe what the sample shows, not the mechanism it happens to use, when the two differ — a Menu demo is Menu - …, even if its point is core:require.

Generation rules

  1. One catalog, and everything is in it. src/ is one flat package (§1), so every app in the tree belongs in smp_app_000 — there is no second overview and no package whose apps are counted and listed nowhere.
  2. Each app appears exactly once, and every demo app physically present is listed (no missing tiles) — except hidden helper apps: a class whose <DESCRIPT> header is ZZZ (e.g. ZZZ - called by SubApp I) is only ever called by another app and must not get a tile. It stays in the folder (and is checked by abaplint), just not shown in the overview.
  3. group == the learning-path stage of the tile's category. The stage comes from scripts/lib/learning-path.json through the tile's category (its header without the Roman numeral); a category that no stage names fails the generator, the same rule catalogue.json is held to. Renaming a stage's title there renames the group everywhere.
  4. Groups follow the learning path. Emit the stages in the order the file lists them - the order somebody learns them in, which is a teaching decision and not the alphabet - and put the stage's blurb on the first tile of each group (intro). With only one group the overview leaves the heading out entirely (§3).
  5. Within a group, sort tiles alphabetically (case-insensitive) by header, then by sub. Sorting by header first keeps numbered series together and in order (Binding I, Binding II, Binding III, … underneath each other; likewise Popover I…IV, Popup I…III). The group order from rule 4 is untouched; only the tiles inside each group are ordered.
  6. Deleting a sample drops its tile, and nothing else moves — the groups come from the learning path (rule 3), not from the tree, so a category loses its heading only when its last sample goes.
  7. After every change, verify: get_catalog( ) and the tree agree — same apps, same grouping, none missing. The safest way to regenerate is to rebuild the catalog straight from the physical tree (one tile per class) and carry over the existing header/sub metadata.

Formatting

Keep the VALUE #( ... ) literal one tile per line, aligned as in the existing catalog. Follow all ABAP rules in §7 (backticks, 2-space indent, LF, final newline). Run abaplint — 0 issues — before committing.


5. Checklists

Adding a sample

  1. Create the class in src/ — §2 says what qualifies, and there is no other folder (§1).
  2. Regenerate the overview catalog and SAMPLES.md: npm run launchpad (§4).
  3. abaplint → 0 issues → commit (English message).

Removing or renaming a sample

  1. Delete or rename the two files (FOLDER_LOGIC=PREFIX — the file name is the class name, and there is no folder to move between, §1).
  2. Regenerate the overview catalog and SAMPLES.md: npm run launchpad (§4).
  3. Check the tree still holds to §1: npm run check:agents refuses a folder under src/, and npm run check:orphans a sample class no catalogue reaches — a class in a subfolder, or one without its .clas.xml. Rule 2 of §4 says every sample is listed; this is what enforces it from the tree side.
  4. abaplint → 0 issues → commit.

Before every commit

npm run check

npm run check is the whole of CI, minus the one step that cannot be run on a tree you want to keep (below). Every workflow that can make a pull request red has a step here, and every step here has a workflow — so a green run locally means a green run there, which is the only reason to run it at all. It used to be six of eleven, and the three it was missing were the three nobody thought to run by hand.

In the order they fail fastest:

step workflow what it holds
npm run check:pin check-framework-pin every abaplint config resolves abap2UI5 from the same, explicitly named branch — no config quietly lints against a different framework than its neighbours
npm run lint abap-standard abaplint reports 0 issues (abaplint.jsonc, v750)
npm run check:cloud abap-cloud the same tree against the ABAP Cloud API — main is installed there as it is (§2)
npm run check:abap2ui5 check-abap2UI5 the abap2UI5-linter: the app class and the view it builds, plus a headless render of every view. New findings fail; abap2ui5lint-baseline.json holds the debt frozen at adoption, and an entry whose finding is gone fails too
npm run check:agents check-docs no drift between the §1 layout and the tree: one flat package, no subfolders, the documented CTEXT
npm run check:orphans check-docs every z2ui5_cl_smp_app_* class sits where a catalogue reads it (§1)
npm run check:keywords check-keywords every sample carries @keywords and @summary, first line, lowercase (§4)
npm run check:api-keywords check-api-keywords every framework cs_event-* constant a sample passes, and every call of a curated client method (popup_display, popover_display, nest_view_display, nav_app_call, the hash and app-state calls, …), stands in its @keywords (§4) — the script's header says what is left out and why
npm run check:markers check-docs every (A) / (C) / (A,C) on a DESCRIPT is backed by the code, and every frontend action or custom control is marked (§12)
npm run check:titles check-docs every sample's page title is abap2UI5 - + its DESCRIPT without the marker (§12)
npm run check:launchpad check-docs the overview catalog and SAMPLES.md still mirror the folder tree (§3, §4)
npm run check:catalogue check-docs the committed catalogue.json still mirrors the folder tree, and keeps the shape its consumers parse (§3)
npm run check:derived check-docs the committed catalogue-derived.json — the linter's half of the catalogue — still matches what the linter derives from the tree ("The catalogue", below)
npm run check:atc check-atc four extended-check (SLIN/ATC) findings abaplint does not model: a SELECT without WHERE and without "#EC CI_NOWHERE, sy-subrc after a dynamic ASSIGN, a text symbol passed to a parameter, an ABAP Doc @raising the method's RAISING clause does not declare
npm run check:patterns check-app-patterns three app-code shapes that build, lint and run and are still wrong: a sibling chained after a statement's head element (§10, one statement per sibling; a leading x->end( ) is fine), nav_app_leave( ) handed get_app( …id_prev_app_stack ) directly or through a variable (§9), and an Input bound untyped to a numeric attribute the class computes with, in a class that never reads get( )-t_model_skipped
npm run check:selftest check-selftest check:atc, check:patterns and check:api-keywords against fixtures (scripts/test/): every rule fires on its shape and stays silent on its look-alikes — a rule that stopped matching would otherwise read as a clean tree
npm run check:prose check-docs every class name written in prose exists, here and in the sibling repositories
npm run check:docs-links check-docs-links every " @docs URL resolves, and its page names the class back (§4)
npm run check:app-rules check-app-rules the abaplint rule block still matches its source in abap2UI5 (§6)
npm run rename check-rename the samples still rename out of the z2ui5 namespace; writes to the gitignored output/, never to src/
npm run e2e (not in check) e2e every sample boots in a headless browser on the transpiled backend and survives its first input, its first row and six button presses: no fatal overlay, no page or console error, no backend 4xx/5xx - E2E.md

check:launchpad, check:catalogue and check:derived run the generators with --check: same render, compared instead of written (one tail for all of them, scripts/lib/emit.mjs). The generators are the source of truth either way, because a check that regenerated differently from the generator would be worse than none. The catalogues job of check-docs.yaml is where the three run, on every pull request and on main; nothing in CI regenerates them (§4).

The last three talk to the network — check:app-rules and check:docs-links prefer a sibling checkout and otherwise fetch, and both say so and pass when they can reach neither: a gate must not go red because github.com is (§6). That degradation is why check:app-rules is in the aggregate now; it was left out back when an unreachable source was a failure.

The one CI step that is not here: npm run downport (abap-702, publish-702). It is not a check, it is the 702 build: it runs abaplint --fix over the whole tree, so running it leaves you with a downported working copy rather than an answer. Run it deliberately, on a clean tree, and git checkout . afterwards.

Nor is npm run e2e (e2e, on pull requests that touch src/ or the harness). It needs npm run e2e:setup (abap2UI5 at A2UI5_PIN, cloned into the git-ignored .abap2UI5) and npm run e2e:build first, about twelve minutes in all. It is the only gate that RUNS a sample: every other step reads the source or a reconstructed view, and the first run (2026-10-09) found four defects in samples that had passed all of them - a view the XML parser refused, a binding to a PROTECTED attribute that answered HTTP 500, an icon drawn before its font was registered, a nested template UI5 called a future fatal error. What it expects to fail is e2e/expected.mjs, each entry with its reason; E2E.md says how to run one sample and why the harness looks the way it does.

By hand, because no script covers it:

  • abapGit file format for all file types: UTF-8, LF only, final newline, 2-space indent (§6).

6. Rules

abaplint

  • Run abaplint before every commit. It must report 0 issues.
  • Configuration: abaplint.jsonc
  • Install: npm install -g @abaplint/cli
  • Run: abaplint
  • The rule block below the marker is a CHECKED COPY of the shared app rule set, and its source is abap2UI5/abap2UI5 .github/abaplint/app-rules.json — the repository where the rest of "how to write an abap2UI5 app" already lives (the build-an-app and view-chain-layout skills, docs/agents/building-apps.md, abap-check, ui5-check), because a shared thing needs one owner. Change it THERE first, then copy it here; this repository, samples-controls and samples-stack are consumers of that file, not peers of each other.
    • This replaced a three-way peer comparison, deliberately: three peers have no answer to which of them is right, a repository without its own copy of the checker turned the other repositories' CI red when it drifted, and the peer checker compared rule NAMES only — so switching a rule to false to get a pull request through, precisely the drift it existed to catch, read to it as no change at all.
    • The gate is scripts/check-app-rules.mjs (npm run check:app-rules, and the check-app-rules workflow on every pull request and push to main). It compares PARSED SETTINGS against the source, preferring an abap2UI5 checkout next to this one and falling back to raw.githubusercontent.com. It is the one gate here that needs the network: when the source is unreachable it says so and passes, rather than going red because github.com is. abap2UI5 checks the same thing from its side (shared-file-gate.mjs) — that is the source noticing, this is the consumer noticing.
    • abaplint has no extends, so there is no shared file to include — the checked copy is the mechanism, and the block carries a header saying so.
    • Only global, dependencies and syntax are per repository (release floor, dependency set, suppressions) — plus exactly one rule: object_naming, which encodes the repository's token (SMP / SMPC / SMPS) and is the only rule check-app-rules excludes from the comparison. It sits last in the file behind a marker that says so. Everything above that marker must match the source.
  • Every rule abaplint ships is listed in the config — all 212 of them (2026-08-16; it was 17 here, 44 in samples-controls and 41 in samples-stack, the rest defaulting to off unnoticed; 212 since abaplint 2.120.75). 190 are on. A rule is never left out of the file. When an abaplint upgrade adds one, add the key to app-rules.json in abap2UI5 and copy the block into all three consumers: on if all three corpora pass, off with the reason in a comment above it if they do not. An unlisted rule reads as "nobody decided" rather than "decided against".
  • The 22 that are off carry their reason in the file. In short: four rules want Hungarian notation and no_public_attributes wants the model hidden, both against §7 and §9; abapdoc treats demos as a published API; seven rules read a view builder chain or a VALUE #( ) data table as a malformed parameter list, and that layout has its own gate (chain-house-layout in npm run check:abap2ui5, §10); prefer_inline / no_inline_in_optional_branches move declarations the samples place deliberately, and prefer_inline_cast folds the previous app a sample reads back into one chained cast; prefer_corresponding proposes a rewrite that does not activate on a generic field symbol; smim_consistency cannot resolve a MIME folder that lives on the system; prefer_string_template and prefer_insert_into_table would be style rewrites of 1,811 and 92 statements across the three corpora; no_dynamic_stuff flags the dynamic calls some samples exist to show; and generic_regex has no pattern to check.
  • Several rules run with flags off or an exclude rather than wholesale. The ones worth knowing here: check_subrc (selectSingle, selectTable — "no rows" is a legitimate state, and the SELECT either feeds a binding or is read back with OPTIONAL), dangerous_statement (dynamicSQL — it was the subject of the generic table browser samples in the testing package, gone since 2026-09-22 (§2) — the flag stays off, see the comment on it), double_space (keywords and endParen — both would strip deliberate column alignment), no_yoda_conditions (onlyConstants — unrestricted it demands lines( t ) < i instead of i > lines( t )) and empty_structure (when — an event that only needs the round-trip is a legitimate empty branch, with a comment where the code would be).
    • An exclude that names another repository's files is not noise here: it is what lets one block serve three corpora. z2ui5_cl_smps_bp_* matches nothing under this src/, and removing it would break samples-stack on the next copy.
  • Write the flag set out in full when configuring a rule. abaplint replaces the whole options object, so a partial one silently turns every flag it omits off — "check_subrc": { "selectTable": false } disables the rule entirely instead of narrowing it.

abap2UI5-linter

  • It is not a view checker. It validates a whole app class — the ABAP and the view it produces, together. Assuming it only inspects XML is the common mistake, and it misses the point: the group that catches what no other tool can is precisely the one that spans both sides.

    Rule group What it catches
    metadata controls and members resolved against the UI5 metadata snapshot
    structure defects in the shape of the document itself
    version controls, members and enum values newer than the target UI5 release
    data the view renders, but not with the data — or not for the user — the author meant
    abap2ui5 defects living in the relationship between the ABAP class and the view it builds; silent at runtime, invisible to any UI5 tooling
  • Configuration: abap2ui5lint.jsonc (UI5 floor 1.71, distribution openui5, failOn: warning, baseline, badges)

  • Run: npm run check:abap2ui5

  • CI: abap2UI5 — as opposed to abap-standard / abap-cloud / abap-702, which lint ABAP itself against three target releases

  • The gate is effective: every app class, every reconstructed view, and an abap2ui5lint-baseline.json that froze the adoption-time debt (#753) until every entry was fixed — empty since 0.6.1, kept so the next adoption has its shape. It was not always: while the linter still looked for the view builder's former name it found no checkable file at all, and a green check-abap2UI5 badge then meant "nothing was checkable", not "the apps are clean".

  • That is why a run reports what it LOOKED at, not only what it found. The gates log every file into a collapsed group while they run, and the run closes with a summary — classes, views reconstructed (and how many classes produced none), controls, bindings and icons judged, the control histogram, what the baseline swallowed and per rule, the phase times:

    sources    <n> app classes (<n> building a view)
    views      <n> documents reconstructed, nested <n> deep, <n> class produced none
    judged     <n> controls of <n> types, <n> bindings, <n> icons, <n> attributes
    gates      properties <n> files, render <n> documents
    

    (The numbers are the run's, not this file's: the two README badges below carry the last ones, and the job summary of every check-abap2UI5 run prints them.)

    (No baselined line any more: abap2ui5lint-baseline.json has been empty since 0.6.1 — the one frozen finding was fixed rather than carried.)

    A judged line of zeroes, or a produced none count that is the whole corpus, is the earlier failure repeating itself — and now it says so instead of printing "Success! No findings detected."

    Since 2026-09-22 the count is ZERO, and the line is absent from the summary altogether. Every class in this repository produces at least one reconstructed view. That is the state to hold: a classes produced none line reappearing in a run is a sample that lost its view, which is the failure the count exists to catch — look at the named class before accepting it.

    Since linter 0.8.0 the sources line counts two classes more and says why: (<n> building a view, 2 building none here - the view comes from another class). Those two are z2ui5_cl_smp_app_105 and z2ui5_cl_smp_app_112, the sub-apps of the Nested View sample z2ui5_cl_smp_app_104 (the accepted exception below): they build into the view reference 104 hands them and display nothing themselves. That is the only acceptable content of that bracket; a third class in it is a sample that lost its view.

    The shape that used to produce none was the "main app calling subapps" scaffold: the class builds a page, keeps the handle in an instance attribute, creates the sub-app with CREATE OBJECT mo_app TYPE (class) and hands the handle over through CALL METHOD mo_app->(`SET_APP_DATA`); the sub-app builds into it and a dynamic ASSIGN mo_app->(`MV_VIEW_DISPLAY`) decides when to display. The linter resolves each builder statement against the handle it is written on, so a handle that leaves the class through a dynamic call is unfollowable — by design, not by oversight. There were eight classes of that shape: seven in the testing package (117, 131, 185, 191, 195, 211, 338, measured 2026-09-04) and the 500a of the binding-error series, which had reached the catalogue shortly before. All eight are gone (§2) — what each of them asserted is a unit test in abap2UI5 now, the last one's in z2ui5_cl_ui5_srv_model's ltcl_07_view_host. Do not write another one here. A view that only exists once a second class has been called by name is a view no gate in this repository can judge. The one accepted exception is z2ui5_cl_smp_app_104, the Nested View sample that embeds another app's view: it instantiates the sub-app over RTTI (CREATE OBJECT app_sub TYPE (classname)) and hands it the container through a dynamic ASSIGN app_sub->(VIEW_PARENT), because embedding a class named at runtime is what it demonstrates. Its own master view is judged like any other; the embedded one is not, and the sample says so.

  • The two README badges (.github/badges/abap2ui5.json and .github/badges/check-abap2ui5.json, shields.io endpoint files) carry the same statement, split along what they mean: abap2UI5 | n apps · n views · n controls is what is here, blue, a fact; check-abap2UI5 | n rules passed is what the gate made of it, green (or n problems, n errors, red). A run that finds nothing checkable turns both grey and says so. Every run rewrites them locally, and they are not committed (.gitignore): check-abap2UI5 publishes them from main to the badges branch, which the README reads, so the counts are what the last run on main actually checked. A sample added or removed moves them with the first run after its merge — nothing to commit, and no bot commit on the pull request.

The scripts under scripts/

Every script is an ES module and is named .mjs. No CommonJS, no require( ), no __dirname — resolve the repository root from fileURLToPath(import.meta.url), the way every script here already does.

The repository ran two module systems side by side until 2026-08-18: five CommonJS .js files and three ESM .mjs ones, with no rule saying which a new script should be. That is not a style preference. A .js file cannot import the .mjs scan, so a check written the ESM way could not reuse lib/scan-samples, and one written the CommonJS way could not await a fetch( ) at the top level — which is exactly what the two network-aware gates do. The split decided what a new check was allowed to reuse, silently, by the extension somebody picked. Both sibling repositories are ESM throughout; so is this one now.

Everything else about a script follows from that:

  • No dependencies. Plain node, so a gate is a few seconds and needs no npm ci — check-docs, check-keywords, check-api-keywords, check-docs-links, check-atc, check-app-patterns, check-selftest, check-framework-pin and check-app-rules run their npm run check:* script without an install. package.json is the one spelling of every gate: a workflow calls the npm script, never node scripts/x.mjs or npx <tool> on its own, so what CI runs and what npm run check runs cannot diverge. The one step that calls the linter directly is the markdown job summary in check-abap2UI5.yaml, and the comment beside it says why (its flags make it a report, not the gate).
  • One scan, two renderers. Anything that reads the sample tree goes through scripts/lib/scan-samples.mjs (§4). A second scan drifts silently.
  • A scan that cannot place a class says so. scanSamples( ) returns orphans next to areas and hidden, and check-orphan-samples.mjs refuses them (§1). The two skips that produce one — a class in the src/ root, a class in a top-level package that is not an area — were bare continues until 2026-09-14, which is how fourteen samples went missing from both catalogues at once. Never add a silent continue to that loop: a class the scan drops has to come back out of it somewhere.
  • A gate that needs the network says so and passes when it cannot reach it (check-app-rules, check-docs-links) — see §6 below and the header of scripts/check-app-rules.mjs. Prefer a sibling checkout over a fetch, so a developer with the whole ecosystem cloned is checked offline.

abapGit file consistency

All serialized files (.abap, .xml, and any other abapGit-managed file types) must conform to the abapGit file format:

  • Encoding: UTF-8 (with optional BOM: xEF BB BF)
  • Line endings: LF (x0A) only — never CRLF
  • abapGit *.clas.xml sidecars start with the UTF-8 BOM (EF BB BF before <?xml) — abapGit writes them that way, and a BOM-less sidecar produces a spurious diff on the next push from a system (human fixes 2026-07-18). Copy an existing sidecar as template.
  • Final newline: every file must end with a single newline character after the last line
  • Indentation: 2 spaces — never tabs
  • Line length: max 255 characters per .abap source line (hard ABAP limit — longer lines break the abapGit import with "Literals across more than one line are not allowed"; enforced via the abaplint line_length rule). Split long string literals into && chunks.

Always verify consistency for all file types before committing, not just .abap files. abaplint covers .abap files; for .xml and other files, check manually or via editor tooling that the above rules are met.


7. Code Conventions

No dictionary objects — a sample is ABAP source and nothing else

This repository ships CLAS and DEVC. Never add a TABL, DTEL, DOMA, DDLS, BDEF or any other dictionary object, and never make a sample depend on one it would have to bring along. A sample a reader can run is a sample that is one class: they pull the repository, start the class, and it works. A dictionary object turns that into an activation order, a transport and a SELECT against a table nobody filled.

abap2UI5 holds the same rule for itself (No new dictionary objects in its AGENTS.md) and acted on it: the released structure z2ui5_t_02, added purely so a sample could point a dynamic type at something, was removed on 2026-09-22 — nothing here ever named it.

Where a sample genuinely needs a type name computed at runtime (CREATE DATA … TYPE STANDARD TABLE OF (name)), it names a table that is already on every system the sample runs on. Today that is Z2UI5_CL_SMP_APP_061, which names Z2UI5_T_01 — abap2UI5's own draft table, borrowed as a name that exists, not used as an API: the sample only reads its shape, never its rows, and if the framework ever changes the table the sample changes the string. Say that in the sample, as 061 does. Data a sample needs for its own sake is built in ABAP — VALUE #( ( … ) ( … ) ) in model_init( ) — never selected from the dictionary.

  • Follow the SAP ABAP Style Guide.
  • Never use an init flag attribute (check_initialized, mv_init, is_initialized, etc.). Always use client->check_on_init( ) instead.
  • An abap_bool is compared to abap_true / abap_false — never asked with IS INITIAL / IS NOT INITIAL, which is the question for a string that might be empty (IF mv_flag = abap_false., DELETE lt_x WHERE flag = abap_false.). The three check_on_*( ) methods return abap_bool as well, and there the corpus writes the predicative call itself: IF client->check_on_init( )., ELSEIF client->check_on_event( `LOCK` ).. Never IF client->check_on_init( ) OR client->check_on_navigated( ). — that OR is redundant, see the lifecycle section below. Only a NEGATIVE branch is spelled out, as = abap_false — there is no negated predicative form here. The rule and its reasons live in abap2UI5's build-an-app skill.
  • Use backticks for all string literals, not single quotes.
  • Use string templates (|...| with { } for embedded expressions) instead of && for string concatenation (e.g. |item { name }| not `item ` && name).
  • Prefer functional to procedural language constructs — use var = VALUE #( ). to reset a variable, never CLEAR var..
  • Use type prefixes only for tables and structures: prefix table variables/attributes with t_ (e.g. t_items) and structure variables/attributes with s_ (e.g. s_screen). Do not add prefixes to scalar variables or object references.
  • Name local types with a ty_s_ prefix for structure types (e.g. ty_s_row) and ty_t_ for table types (e.g. ty_t_rows). Only define a ty_t_ table type when it is used more than once — for a single-use table, declare it inline with STANDARD TABLE OF ty_s_xxx.
  • No blank line between a TYPES definition and the DATA declaration that directly uses it.
  • Class names are always written in lowercase in both DEFINITION and IMPLEMENTATION — never uppercase.
  • Classes are not FINAL — do not add the FINAL keyword to class definitions.
  • Use DEFINITION PUBLIC. — never DEFINITION PUBLIC CREATE PUBLIC. (CREATE PUBLIC is the default and adds unnecessary overhead).
  • Always include PROTECTED SECTION. and PRIVATE SECTION. in the class definition, even if empty.
  • Keep PRIVATE SECTION. always empty — declare everything at PROTECTED SECTION. level at most.
  • In every section (PUBLIC SECTION., PROTECTED SECTION.), always follow this declaration order: TYPES first, then DATA, then METHODS.
  • Blank lines — class definition (EMPTY_LINES_IN_CLASS_DEFINITION):
    • Add one blank line above each section keyword (PUBLIC SECTION., PROTECTED SECTION., PRIVATE SECTION.) — unless the preceding section is empty.
    • No blank line directly below a section keyword.
    • No blank line above ENDCLASS..
    • Max 1 consecutive blank line inside the definition block.
    • Add one blank line between groups of different declaration types (e.g. between INTERFACES and DATA, or DATA and METHODS).
  • Blank lines — outside methods (EMPTY_LINES_OUTSIDE_METHODS):
    • Exactly 2 blank lines between ENDCLASS. and the next CLASS … IMPLEMENTATION. (i.e. between the definition and the implementation block).
    • Exactly 2 blank lines between two METHOD … ENDMETHOD. blocks.
    • Exactly 2 blank lines between two top-level class blocks.
  • Blank lines — inside methods (EMPTY_LINES_WITHIN_METHODS):
    • Always add exactly 1 blank line at the very start of a method body (after METHOD).
    • Always add exactly 1 blank line at the very end of a method body (before ENDMETHOD).
    • Max 1 consecutive blank line inside a method body.
    • Always add 1 blank line before an IF block — except when the method is a pure dispatcher (its only purpose is to jump to other methods, with no own logic before the IF). In that case, omit the blank line between the opening assignment and the IF.
    • Always add 1 blank line before ELSEIF and ELSE.
    • In setup methods (model_init and similar), add 1 blank line between the last data assignment and the first non-assignment statement (e.g. before a data_read( )):
      METHOD model_init.
      
        price    = `1234`.
        currency = `EUR`.
      
        data_read( ).
      
      ENDMETHOD.
    • If a branch (IF, ELSEIF, ELSE) contains more than one statement, add 1 blank line directly after the condition line as well:
      me->client = client.
      
      IF client->check_on_init( ).
      
        product  = `products`.
        quantity = `500`.
        view_display( ).
      
      ELSEIF client->check_on_event( `SAVE` ).
        data_update( ).
      ENDIF.
  • ABAP Doc ("!) position — not caught by abaplint, but the extended check (SLIN/ATC) reports "ABAP Doc comment is in the wrong position": a "! block must sit directly before the one declaration it documents. Inside a chained statement (TYPES: BEGIN OF …) that means directly before the component, within the chain. It is never allowed inside a METHODS parameter list — document parameters in the method's own doc block above the METHODS keyword via "! @parameter <name> | <text>. A plain " comment (no !) is fine anywhere.
  • ABAP Doc is parsed as HTML: escape a literal <, > or & as &lt;, &gt;, &amp;.
  • A mock table is a table. In a VALUE #( ) of three or more rows with the same field list, pad every cell to the width of its column and leave the LAST cell of a row unpadded, so no spaces pile up before the closing ). Rows whose field lists differ have no column to align and stay as they are; a row that would break 255 characters once padded is wrapped at the same field boundaries in every row instead.
  • A call that fits on one line goes on one line (budget 120 characters) — stacking parameters is for calls that do not fit, not for calls that happen to have two. The view chain is the exception: it keeps one call per line (view-chain-layout), and a t_arg list wrapped over several lines stays wrapped, hanging under its first element.
  • Always run abaplint after every change. It must report 0 issues before committing.
  • Before starting app development, read all active rules in abaplint.jsonc and follow them throughout.
  • The rules that most often bite when writing a new sample (all of them enforced since 2026-08-16, see §6):
    • A table type is WITH EMPTY KEY, never WITH DEFAULT KEY.
    • A local type name starts with ty_ (ty_s_ / ty_t_, §7 above).
    • CASE needs two WHEN branches. One event is an IF — which is what §9 asks for anyway; CASE starts at four.
    • Every SELECT carries an ORDER BY (ORDER BY PRIMARY KEY if the order itself does not matter), and SELECT SINGLE needs the full key — without it, use ORDER BY PRIMARY KEY ... UP TO 1 ROWS and read row 1.
    • ASSIGN and READ TABLE are followed by an sy-subrc check. Reading an unassigned field symbol dumps; a missed READ TABLE leaves the previous work area in place, which is worse than a dump because it looks like data.
    • An explicit DATA belongs at the top of its method (definitions_top). An inline DATA( ) at the point of use is fine and is not affected.
    • No commented-out code, no unused variable, type or method, no empty WHEN, no end-of-line comment, no ! before a parameter name.
    • Two blank lines between methods — three is a finding.

8. Framework Reference

For deeper information about how the abap2UI5 framework works internally — architecture, roundtrip processing, data binding engine, session persistence, and core classes — refer to the abap2UI5 repository and its AGENTS.md.


9. How Apps Work

The mechanics — the main( ) roundtrip, the three check_on_*( ) flags, the client API of z2ui5_if_client (views, popups, _bind( ), _event( ), follow_up_action( ), navigation, the URL hash and the app state), messages and popups — are the framework's to describe, and it does, in docs/agents/building-apps.md of abap2UI5 (the build-an-app skill), a guide the framework's own gates hold to the interface. Read it before writing a sample, and do not copy it here: the copy this file used to carry drifted from it in three places within a month. What follows is only what this repository decides for itself.

The dispatcher

Always chain the lifecycle checks with ELSEIF — never separate IF blocks — in the order init, navigated, event:

IF client->check_on_init( ).
  " what must happen ONCE - seed the model, seed a control-state flag
  model_init( ).
  view_display( ).
ELSEIF client->check_on_navigated( ).
  view_display( ).
ELSEIF client->check_on_event( ).
  on_event( ).
ENDIF.

The init branch displays too. The chain runs exactly one branch per roundtrip, and on the first one that is the init branch - the ELSEIF check_on_navigated( ) below it is skipped, so an init branch that only seeds leaves the first start without a view.

check_on_init( ) true implies check_on_navigated( ) true (the guide says why), so an init branch whose only statement is view_display( ) has an ELSEIF twin doing exactly the same thing (the linter's redundant-init-display), and IF check_on_init( ) OR check_on_navigated( ). says the same redundancy in one line. An app with nothing to seed drops the init branch entirely and dispatches on check_on_navigated( ) and check_on_event( ) alone.

view_display( ) in the check_on_navigated( ) branch is always safe, and always there. A called sub-app that took the screen leaves its own view standing when it returns via nav_app_leave( ); the attributes survived the roundtrip, so nothing is re-read — the view is re-displayed, and data_read( ) is not called there. After a popup the same call simply re-renders the same view. The linter's missing-on-navigated-branch holds every class to it (§6), and the two shapes it exempts are the ones that never own the main view slot: a sub-app that renders into its parent's view (z2ui5_cl_smp_app_105 and _112, where check_on_init( ) is the only place the view is built) and an app that owns a popup instead of a view (z2ui5_cl_smp_app_501, excluded by name in abap2ui5lint.jsonc with the reason beside it).

Event checking — inline vs. CASE

check_on_event( ) takes an optional event name. Check the event inline in the ELSEIF chain when there are 2–3 events and no dispatch logic:

IF client->check_on_init( ).
  ...
ELSEIF client->check_on_event( `SAVE` ).
  data_update( ).
ELSEIF client->check_on_event( `DELETE` ).
  data_delete( ).
ENDIF.

A CASE client->get_event( ) (inside ELSEIF client->check_on_event( )) starts at 4 events, or when a dedicated on_event method is extracted (§11). The framework guide dispatches with CASE from the first event; here the abaplint rule that wants two WHEN branches decides (§7).

Navigation

  • The back button is wired in the view: press = client->_event_nav_app_leave( ) on the Page's navButtonPress, with showNavButton bound to client->check_app_prev_stack( ) (the §10 example) — no roundtrip. Handle BACK in on_event only when something has to happen with the app or the previous app instance before leaving:

    WHEN `BACK`.
      CAST z2ui5_cl_app_parent( client->get_app_prev( ) )->set_result( s_result ).
      client->nav_app_leave( ).
  • One browser step back is client->follow_up_action( client->cs_event-hash_back ); back to the previous app is nav_app_leave( ). follow_up_action( ) runs no raw JavaScript any more — a val that is not a cs_event-* name is not executed — so history.back() is not an option. z2ui5_cl_smp_app_499 shows the whole hash_* family.

  • Back to the caller is the bare nav_app_leave( ) — or nav_app_leave( event = … ) to hand it an event. Never load the caller by id first (nav_app_leave( client->get_app( client->get( )-s_draft-id_prev_app_stack ) ), directly or through a variable): the bare call goes to the same app, and unlike get_app( ) it survives a caller whose draft has expired. npm run check:patterns (nav_leave_get_app) refuses it.


10. Building Views

Views are XML strings passed to client->view_display( ), built with z2ui5_cl_ui5_view_builder — the released builder in the framework's src/02. It is generic: seven public methods build any UI5 view 1:1 — factory( ), ele( ), tag( ), a( ), end( ), stringify( ) and the static escape_literal( ) — so there is no list of supported controls and nothing to wait for when UI5 adds one. Element and property names come straight from the UI5 API Reference and are written exactly as documented there. What each verb does, and the whole of the builder's semantics, is section 3 of the framework guide (§9); three of its rules are repeated here because samples get them wrong:

  • a( ) takes exactly one of v, b, t. v is the form for a binding, an event, a {/path} template and constant text; b takes an ABAP boolean and renders true/false itself (a( n = `editable` b = mv_edit_mode ), never a conversion of your own); t takes text that carries data — user input, a value read from a table — and escapes it as a literal, because a { in a v is parsed as a binding. Where one attribute mixes text with a binding, escape the text part with z2ui5_cl_ui5_view_builder=>escape_literal( ) inside v.

  • Empty attributes are rendered. The builder writes every attribute you add, including an empty one — and type="" or color="" is not a valid UI5 enum value. An attribute whose value may be empty at runtime therefore goes under an IF, it is not simply passed:

    DATA(button) = toolbar->tag( `Button` )->a( n = `text` v = name ).
    IF icon IS NOT INITIAL.
      button->a( n = `icon` v = icon ).
    ENDIF.
  • There is no raw-text node, so an inline <style> body or any other raw markup goes into the content attribute of a core:HTML leaf. Write the decoded markup — the builder escapes it on stringify:

    page->tag( n = `HTML` ns = `core` )->a( n = `content` v = `<style>` && css && `</style>` ).

    And there is no way back up to a named ancestor: end( ) climbs exactly one level, so a view is built the way it nests. When a helper method needs a container the caller owns, the caller passes that reference — see the nest_view_display( ) samples of the Nested View category, which are handed the container they render into rather than searching for it.

View structure and layout

Always add 1 blank line before DATA(view) = z2ui5_cl_ui5_view_builder=>factory( ). to visually separate view construction from preceding logic.

Always build the view in view_display and call client->view_display( view->stringify( ) ) as a standalone statement at the end — never nested inside the chain.

The chain is the only picture of the view's tree there is, so its layout is load-bearing rather than cosmetic. Six rules, and they are identical in abap2UI5/samples-controls — the two corpora were unified in one pass after a survey found them following opposite conventions:

  1. One call per line. Every ele( ), tag( ), a( ) and end( ) opens its own line with )->. A control never shares its line with the container it opens, nor with its own attributes.
  2. Four spaces per level, everywhere. A child sits one level in from its container, a control's attributes one level in from the control. The same step throughout every file — a chain that steps by 2 and then by 4 and then stops moving is no longer describing the tree, it is decorating it.
  3. The closing paren rides with the arrow. Never a ) alone at a line end; carry it to the next segment so it always reads )->.
  4. end( ) stands alone in the column of the ele( ) it closes. That is what makes an ascent over several levels visible instead of hidden. What is forbidden is the run on one line — )->end( )->end( )->ele( `footer` )->ele( `OverflowToolbar` changes four levels where nobody can see them.
  5. Align the v = / b = column within one control's attribute block.
  6. stringify( ) is a standalone final statement — never nested in the chain.
METHOD view_display.

  DATA(view) = z2ui5_cl_ui5_view_builder=>factory(
      )->ele( n = `View` ns = `mvc`
          )->a( n = `displayBlock` v = `true`
          )->a( n = `height`       v = `100%`
          )->a( n = `xmlns`        v = `sap.m`
          )->a( n = `xmlns:mvc`    v = `sap.ui.core.mvc`
          )->a( n = `xmlns:form`   v = `sap.ui.layout.form` ).

  view->ele( `Shell`
      )->ele( `Page`
          )->a( n = `title`          v = `My App`
          )->a( n = `showNavButton`  b = client->check_app_prev_stack( )
          )->a( n = `navButtonPress` v = client->_event_nav_app_leave( )
          )->ele( n = `SimpleForm` ns = `form`
              )->a( n = `title`    v = `Form Title`
              )->a( n = `editable` b = abap_true
              )->ele( n = `content` ns = `form`
                  )->tag( `Label`
                      )->a( n = `text` v = `Quantity`
                  )->tag( `Input`
                      )->a( n = `value` v = client->_bind( quantity )
                  )->tag( `Button`
                      )->a( n = `text`  v = `Post`
                      )->a( n = `press` v = client->_event( `POST` ) ).

  client->view_display( view->stringify( ) ).

ENDMETHOD.

The hierarchy is mvc:View → Shell → Page → form:SimpleForm → form:content → leaves, and every one of those levels is four spaces. Label, Input and Button are siblings inside content, so they are added with tag( ) and stay at the same indent while their attributes step in.

One chain, or one statement per subtree

Both shapes are correct, and the choice is about the view, not about style:

  • One chain — the whole view in a single statement, ascending with end( ). The shape samples-controls uses throughout, because a 1:1 port mirrors one original XML file.
  • One statement per subtree — hold a container in a variable (DATA(page), DATA(cont), DATA(lo_columns)) and start a new statement from it. The shape most of this corpus uses, and the better one when a subtree is filled from a loop, when the same node is filled twice, or when a teaching sample reads better with the parts named. z2ui5_cl_smp_app_052 is the worked example.

The split shape reconstructs and renders fine — the linter reads every document in this corpus from it. What is not allowed is mixing them inside one subtree, and blank lines inside a chain: they belong to the long single-chain shape, where they separate an ele( ) block from its first child.

What checks this

The rules above are also the view-chain-layout skill (.claude/skills/view-chain-layout/), kept byte-identical in abap2UI5 and abap2UI5/samples-controls — read it before writing or reformatting a chain.

The linter's chain-house-layout rule (part of npm run check:abap2ui5, in check-abap2UI5.yaml) checks all six rules and npm run fmt:chains applies them. The fixer rewrites whitespace between chain segments only, and the layout survives because every fix is verified against the rule — a formatting change can never alter what the view builds.

What the layout rule cannot see is a sibling chained after the head element of a split-shape statement: page->tag( A )->…->tag( B ) builds two siblings, and the rule indents B one level deeper than the tree has it. npm run check:patterns (chain_sibling) refuses it — start a new statement per sibling from the container. A statement that opens with x->end( ) to reach the parent of a held container is fine.

Bindings — what this corpus calls things

Binding paths always come from a bind call — never hardcode them. Every model value a view references must be registered through client->_bind( ): a hand-written path ({/START_DATE}, or { path: '/START_DATE', ... } in a raw binding-info string) is NOT part of the serialized model — the frontend receives no data for it and typed/object properties crash on the missing value (human find 2026-07-18 in Z2UI5_CL_SMP_APP_456/_457). Compose raw binding-info strings with the bare path from client->_bind_path( x ).

Always _bind( ), never _bind_edit( ). Both bind into the same root model — the split between them disappeared with the XX/ view-model node — so _bind_edit is only an obsolete alias and is slated for removal. The single exception is a mapping that differs per direction, because _bind has no custom_mapper_back / custom_filter_back parameters; no sample in this repository currently needs that — one that does must say so in a comment at the call.

Call it "binding", never "one-way"/"two-way" binding — in sample titles, message strips, comments and @keywords alike. With only _bind( ) left, and the value always written back before the event handler runs, the qualifier distinguishes nothing and makes readers look for a second mode that does not exist. Say "bound attribute", "the value is written back before the event handler runs". "One-way" is correct only for a real UI5 one-way model that is not _bind( ) — the device> JSONModel in z2ui5_cl_smp_app_445, for example.

Retired in the framework, banned here

The former standalone XML builder z2ui5_cl_util_xml is no part of the framework any more: it left abap2UI5 with the other z2ui5_cl_util* classes on 2026-11-02 and ships in abap2UI5-obsolet. No sample uses it, and a sample must not depend on it — do not use it in new samples.

The z2ui5_cl_pop_* helper popups are obsolete. They live in the framework's obsolete package (src/99) and must not be used any more: never reference one from a sample, and never create a sample demonstrating one (human decision 2026-08-12; the last two usages — z2ui5_cl_pop_to_confirm in Z2UI5_CL_SMP_APP_279, z2ui5_cl_pop_image_editor in Z2UI5_CL_SMP_APP_306 — were removed the same day). A sample that needs a dialog builds it itself with z2ui5_cl_ui5_view_builder=>factory( ) with a core:FragmentDefinition root + client->popup_display( ).

VALUE #( ) formatting

In VALUE #( ) constructor expressions with named fields, use either entirely inline (all fields on one line) or each field on its own line — never mix both styles in the same expression:

" Wrong — mixed
t_products = VALUE #(
  ( name = `Notebook Basic 15`  product_id = `HT-1000` supplier_name = `Very Best Screens`
    dimensions = `30 x 18 x 3 cm` weight_measure = `4.2` weight_unit = `KG` ) ).

" Correct — one field per line, = signs aligned
t_products = VALUE #(
  ( name           = `Notebook Basic 15`
    product_id     = `HT-1000`
    supplier_name  = `Very Best Screens`
    dimensions     = `30 x 18 x 3 cm`
    weight_measure = `4.2`
    weight_unit    = `KG` ) ).

A later row names every component an earlier row set, with an empty value ( ``, 0, `abap_false`, `VALUE #( )`) where it has none - an empty row `( )` after a filled one included. On 7.40+ a left-out component is initial; on the `702` branch, which is the abaplint downport, every row of a `VALUE` is built in one work area that is never cleared, so the row inherits the previous row's value - silently, nothing reports it. The upstream fix is tracked in abap2UI5's backlog (`abaplint-downport-value-row-not-cleared`); until it ships and is pinned, spell the components out. `FOR` rows and rows that all assign the same components are not affected.


11. App Structure

Simple apps (< 50 lines in main)

Write everything directly in main — no method encapsulation needed. Count only the lines inside the main method, not the total class length.

Do not extract view_display or any other helper method just because the app has a view. A separate view_display method is only justified when the app is large enough to warrant the full canonical structure (≥ 50 lines in main). Extracting it in a simple app adds unnecessary indirection.

Larger apps — canonical template

When the logic no longer fits inside main, extract view_display, on_event and - where the app seeds data - model_init, under exactly these names. main then becomes a pure dispatcher. Only add further methods (data_read, etc.) when they are actually needed.

One order, in the declarations and in the implementation: main, view_display, on_event, the event handlers and helpers, and model_init last. A reader meets what the app shows first, then what it does, and the seed data - usually the longest and least interesting part - at the end. model_init only seeds: the check_on_init( ) branch of main calls it and then view_display( ). (Until 2026-11 the first extraction was called on_init and displayed the view itself; samples-controls always used model_init, and the three repositories read alike now. An on_init remains only where the init path does more than seed and display - apps 004, 081, 381, 382, 421, 501, 543.)

In the check_on_navigated( ) branch the dispatcher calls view_display( ) directly — the app state survived the serialization, only the view must be re-displayed. Extract a dedicated on_navigation method only when the app additionally needs to process results from the called sub-app (via get_app_prev( )) before re-displaying.

Never create a pass-through method with only one statement. If an extracted method (e.g. model_init) would contain only a single call, replace the method call in the dispatcher with that single call directly — and omit the pass-through method entirely. For example, if model_init would only call data_read( ), write data_read( ) directly in the IF client->check_on_init( ). branch instead.

Event handler sub-methods

When the body of a single WHEN branch in on_event grows too long, extract it into a dedicated method named on_event_<event> (e.g. on_event_save, on_event_delete). The on_event method then stays a thin dispatcher — one call per branch — and all the logic lives in the sub-method.

The following is the maximum structure. Only add methods that are actually needed.

CLASS z2ui5_cl_app_xxx DEFINITION PUBLIC.
  PUBLIC SECTION.
    INTERFACES z2ui5_if_app.
    " bound data (DATA attributes for _bind)...
  PROTECTED SECTION.
    DATA client TYPE REF TO z2ui5_if_client.

    METHODS view_display.   " build and render the view
    METHODS on_event.       " user triggered an event
    METHODS data_read.      " SELECT from database
    METHODS data_update.    " INSERT / UPDATE / DELETE
    METHODS model_init.     " first call: seed what the app starts with
  PRIVATE SECTION.
ENDCLASS.


CLASS z2ui5_cl_app_xxx IMPLEMENTATION.

  METHOD z2ui5_if_app~main.

    me->client = client.
    IF client->check_on_init( ).
      model_init( ).
      view_display( ).
    ELSEIF client->check_on_navigated( ).
      view_display( ).
    ELSEIF client->check_on_event( ).
      on_event( ).
    ENDIF.

  ENDMETHOD.


  METHOD view_display.

    DATA(view) = z2ui5_cl_ui5_view_builder=>factory( ).
    " ...
    client->view_display( view->stringify( ) ).

  ENDMETHOD.


  METHOD on_event.

    CASE client->get_event( ).
      WHEN `SAVE`.
        on_event_save( ).
      WHEN `BACK`.
        client->nav_app_leave( ).
    ENDCASE.

  ENDMETHOD.


  METHOD on_event_save.

    data_update( ).

  ENDMETHOD.


  METHOD data_read.

    " SELECT ...

  ENDMETHOD.


  METHOD data_update.

    " INSERT / UPDATE / DELETE ...

  ENDMETHOD.


  METHOD model_init.

    " the values the app starts with ...
    data_read( ).

  ENDMETHOD.

ENDCLASS.

11a. What the catalogue owes the framework — the coverage audit

Every non-obsolete part of z2ui5_if_client is demonstrated by a sample somewhere in the three sample repositories. Measured 2026-09-22 against the ABAP source of all three checkouts — this repository, samples-stack and samples-controls — not against a catalogue and not against this src/ alone. The surfaces counted are the constants of cs_event, the methods of the interface, the components of ty_s_event_control and the parameters of _bind( ).

Surface Total Without a sample anywhere
cs_event-* 34 0
z2ui5_if_client methods 40 7
ty_s_event_control components 5 0
_bind( ) parameters 10 2

(Totals re-counted 2026-09-25 against the framework's z2ui5_if_client; the coverage column is the 2026-09-22 measurement.)

All nine are obsolete, and that is the whole finding — there is no uncovered feature, only features nobody should be shown:

  • the five *_model_update( ) methods do nothing (the framework pushes the model itself since main_end compares before and after);
  • _bind_edit( ) is an alias of _bind( ), _event_client( ) a superseded spelling of follow_up_action( );
  • custom_mapper / custom_filter are marked obsolete at the declaration.

cs_event-z2ui5 stood in the table too, as the one constant without a sample: the legacy escape hatch in the interface's own "obsolet" block. abap2UI5 removed it on 2026-09-22 together with the z2ui5 frontend global whose functions it called, which is what took the row to 34 / 0. A function an app defines on window is not something a sample here demonstrates — follow_up_action( ) runs no raw expression any more, and what an app needs beyond the cs_event set is a custom control.

cs_event-image_editor_popup_close stood here too, as "belongs to a z2ui5_cl_pop_* popup this repository may not demonstrate". That reading was wrong and the audit is the reason it surfaced: the constant was not waiting on the frozen package, it was waiting on a capability the framework did not have — reading a value off a control in another view slot into an event argument. abap2UI5 added $controller.slotValue( ) and removed the constant on 2026-09-22. A symbol that has no sample because nothing can express it is a gap in the framework, not in this catalogue — worth saying which of the two it is before filing it under "obsolete".

Do not write a sample for any of them. A demonstration is a promise that the thing is the way to do it.

Not counted, because no sample repository can carry them: the two methods of z2ui5_if_ui5_exit (an exit is a class the installation writes — a sample shipping one would take the exit over for everybody who pulls the repository) and the ICF entry points of z2ui5_cl_ui5_http_handler (run, factory_cloud, _http_get / _http_post, …), which a customer wires into a handler class rather than an app.

Count against all THREE repositories, from source

This section was wrong twice in one day, the same way both times, and the rule is what came out of it:

  1. the first run grepped this src/ only and reported play_audio as demonstrated nowhere. Z2UI5_CL_SMPS_APP_487 had been playing sounds in samples-stack the whole time. A sample was written for it and withdrawn.
  2. the second run fell back on the published SAMPLES.md of the other two — keywords and summaries, not code — and reported popover_close as the one genuinely missing constant. It is in samples-controls, which simply does not put the constant in a keyword line.

A grep of one src/ answers "does this repository show it". The question that decides whether a sample is worth writing is "does the ecosystem show it", and only the source of all three answers that. Clone the other two (git clone --depth 1) rather than reading their catalogues.

Re-run the audit when the framework's API snapshot changes, not on a schedule: a new cs_event constant either gets a sample or gets a line above saying why not, and that decision is the thing worth recording.


12. Sample content conventions

Learned while curating the sample catalogue — follow these so new/edited samples stay consistent:

  • Every sample opens with an intro MessageStrip. As the first control in the page content (right after the Page, before the form or table), add a short, specific English explanation of what the sample demonstrates:

    page->tag( `MessageStrip`
        )->a( n = `text`     v = `<one or two sentences: what this sample shows / does>`
        )->a( n = `type`     v = `Information`
        )->a( n = `showIcon` b = abap_true
        )->a( n = `class`    v = `sapUiSmallMargin` ).

    Split a long text into `chunk ` && continuation lines (≤255 chars/line, aligned under the first backtick). Hold the page in a variable for it (DATA(page) = view->ele( Shell)->ele(Page … ), the split shape of §10) rather than threading the strip into one long chain.

  • DESCRIPTs of framework-action / custom-control samples carry a capability marker appended to the <DESCRIPT> (leading space), surfaced in the overview:

    • (C) — uses an abap2UI5 custom control (the z2ui5 cc namespace: ele( n = … ns = `z2ui5` ), z2ui5.cc, xmlns:z2ui5).
    • (A) — performs a frontend action. The list is closed — exactly these three, nothing "like" them:
      1. a client->follow_up_action( ) call (including the cs_event-control_by_id / cs_event-control_global / cs_event-binding_call events, which only ever travel through it);
      2. a client->_event_client( ) call, the obsolete spelling of the same;
      3. drag and drop — a control of the sap.ui.core.dnd namespace (ns = `dnd`) or a dragDropConfig aggregation. Any other client-side behaviour (an expression binding, a formatter, a liveChange wire, a core:require) is not (A); a new kind needs this list and the gate changed in the same commit. The ubiquitous back-button client->_event_nav_app_leave( ) does not count.
    • (A,C) — both. Regenerate the overviews after changing any DESCRIPT (§4). An option on an ordinary roundtrip _event( ) (s_ctrl, e.g. check_prevent_default) is not a frontend action: the event still goes to the backend and nothing else (Z2UI5_CL_SMP_APP_472 carried (A) for it until 2026-10-08). The gate is npm run check:markers (scripts/check-markers.mjs, the capability_markers job of check-docs): it reads every tile's code with comments stripped and refuses a marker the code does not back as well as a missing one — (A) for exactly the three items above (the two calls looked for outside string literals), (C) for a z2ui5-namespace element or an xmlns:z2ui5 declaration. The two definitions live in that script and here; change them together. The legend a reader sees - under the overview app's list, in the preamble of SAMPLES.md, as naming.markers in catalogue.json - is written once, in scripts/lib/markers.mjs, and rendered by all three generators; change the wording there, never in a rendered copy.
  • A read-only info form disables its inputs (a( n = `enabled` b = abap_false )) — do not leave display-only values in editable inputs (see z2ui5_cl_smp_app_122).

  • No redundant footer Back button. The Page already carries the nav-back button (showNavButton / navButtonPress, §9); do not add a second Back button in the page footer (removed from the MessageBox / MessageToast samples).

  • Must run on OpenUI5 1.71 — watch for "phantom control" 404s. An ele( ) that names an aggregation the parent does not have makes UI5 resolve it as a control class and 404 with failed to load sap/<lib>/<name>.js on 1.71, crashing the sample. Two real cases:

    • ele( n = `heading` ns = `uxap` ) under an ObjectPageSection — sap.uxap.ObjectPageSection has no heading aggregation. Put the section title in a( n = `title` v = … ) and go straight to subSections. (f:heading is valid under a sap.f DynamicPageTitle.)
    • footer on a popup Dialog — sap.m.Dialog only got a public footer aggregation ~1.110; a Page's footer is fine (sap.m.Page always had one). Every control/property here must exist since 1.71 (§2); when in doubt check "available since" in the demo kit.
  • sap.m.SimpleForm needs a( n = `editable` b = abap_true ) for its label/input pairs to line up on one row — without it the form renders in display mode and the first field is mislaid (fixed in Z2UI5_CL_SMP_APP_189; compare Z2UI5_CL_SMP_APP_133).

  • StandardListItem: info right-aligns to the far edge (a status/amount slot). For a secondary attribute that belongs with the title (e.g. a product's category) use description — a left-aligned subtitle — instead; the far-right float looks disconnected on wide screens (fixed in Z2UI5_CL_SMP_APP_454/_455).

  • The page title carries the <DESCRIPT> text, in the form `abap2UI5 - <DESCRIPT without the (A)/(C) marker>` — every sample follows it since 2026-08-13. A user clicks a tile in the overview (which shows the DESCRIPT) and the opened sample must name the same thing, so it is recognisably the right sample. Change the two together: renaming a DESCRIPT without the page title puts them out of sync again (they had drifted to "Focus II" and "Table Filters Reset after view Update"). The gate is npm run check:titles (scripts/check-page-titles.mjs, the page_titles job of check-docs). It reads the first Page built after the main view's Shell — in the same chain, off a variable, or as the first page of a NavContainer in the Shell — and wants the title as that literal. Not judged: a Dialog title, further NavContainer pages, nested-view pages, the overview app (abap2UI5 - Samples, §3) and the ZZZ helpers, which have no tile.

  • Every main view opens mvc:View → Shell → Page (the §10 example), never View → Page, so all samples share the same outer frame (fixed in Z2UI5_CL_SMP_APP_143).

  • Give a SearchField an explicit placeholder. Without one UI5 shows its locale default (German "Suchen" on a DE system), which clashes with the otherwise-English samples.


The catalogue — published from the playground

https://abap2ui5.github.io/browser-playground/samples/ — every sample of this repository, of samples-controls and of samples-stack, searchable, for somebody who has not installed anything yet. This repository used to publish its own page for that (web/, on its own GitHub Pages); it was retired 2026-09-03 together with the two sibling pages. Three pages that each had to explain that the other two existed were the reason for the shared family-nav block, its three copies and the check policing them; one page needs none of it.

What this repository owes that page is data, and it owes it twice:

catalogue.json what the tree holds — class, folder, category, learning-path stage, title, @summary, @keywords, @docs (§3)
catalogue-derived.json what the LINTER knows — minUi5, the needs that made it that release, and every control the sample BUILDS

The second answers the question the first cannot: "which sample shows sap.m.Table at all?" A category is what a sample is FILED under and @keywords are what somebody thought to write down; neither is the list of controls the view actually builds. scripts/generate-derived.mjs gets both out of an @abap2UI5/linter pass — stats.types and the *-too-new findings, which it computes anyway — and keys them by class so a consumer joins them onto catalogue.json.

Two files rather than more columns, for the reason §3 gives for catalogue.json being offline and dependency-free: that property is worth keeping, and the derived half needs the linter. They are generated from one scan of one tree, so they cannot disagree about which samples exist. Which UI5 library a control ships in is deliberately in neither: that is one taxonomy question, and three sample repositories each answering it would be three prefix tables that drift, so the playground's catalogue owns the mapping, beside the library list it decides "runs here" against. The identical file shape and the identical reasoning are in samples-controls and samples-stack.

The one thing that is not derived: the order

The categories are the header of a DESCRIPT and therefore sort alphabetically, which puts Browser between Binding and CSS — an order nobody learns in. So the catalogue groups the categories into stages, and that grouping is a teaching decision written in scripts/lib/learning-path.json and nowhere else:

{ "id": "rows", "title": "Show many rows", "blurb": "…", "categories": ["Table", "Grid Table", "List", "Tree"] }

Every category belongs to exactly one stage. npm run check:catalogue (scripts/generate-catalogue.mjs --check) fails when a category has no stage, when two stages claim one, or when a stage names a category no sample carries. A new category is therefore a decision somebody has to make — where in the path does this belong — rather than a section that silently nobody can reach. Adding a sample to an existing category needs nothing.

Those three rules used to be npm run check:overview, in the generator behind the page. They were never about a page — they are about the path staying attached to the tree — so they moved to the generator that publishes stage to every consumer. Moving them surfaced that generate-catalogue.mjs had no CI job at all: committed generated data watched only by npm run check on somebody's laptop. The catalogues job in check-docs.yaml watches both files now.

Everything in src/ is catalogued, which since the tree was flattened (§1) is every class in the repository: the testing package, which existed to be run by a check rather than learned from, is gone, so there is nothing left a catalogue that teaches would have to lead readers around. The ZZZ helpers are out for the reason they carry no tile (§4); they come back only as the extra files a playground link needs to actually run.

Thumbnails

One picture per sample used to be photographed on every deploy by scripts/generate-screenshots.mjs, with the abap2UI5-linter's render harness. The script went with the page; the playground's deploy takes them now (tools/build-thumbs.mjs over there, since 2026-09-12 — for a week the sentence before this one described a plan), from the same harness against the same main, so what a card shows is still what the render gate checks. They are served at /playground/samples/thumbs/<class>.png, cached by content between deploys, and a view the harness cannot render — the z2ui5.cc custom-control samples, mostly — has no picture, which is normal rather than broken.

Metadata: what goes on the class, and what goes beside it

Shared across abap2UI5/samples, abap2UI5/samples-controls and abap2UI5/samples-stack. Decided once, so nobody has to decide it again per repository.

A class says what it IS. A sidecar records what HAPPENED to it.

where why
DESCRIPT — Titel - Kurzbeschreibung .clas.xml 60 characters, hard. What ADT's object list shows
" @summary — one sentence first lines of .clas.abap no limit. The line a catalogue puts under the title
" @keywords — search terms first lines of .clas.abap what somebody would type who does not know the sample exists
upstream sample, port batch, audit findings, verification date, deviations a sidecar (meta/<class>.json) not properties of the class; written by machinery; long-form; changes on a different schedule

Why the first three are not in a sidecar

A sidecar does not travel. abapGit pulls src/; a meta/ folder never reaches the SAP system. Three places that costs:

  1. In the system it is simply absent — which is why an overview app that needs the data has to have it baked in by a generator.
  2. A search engine drops somebody into the .clas.abap on GitHub and the code is all they get. This is the same argument @docs is a full URL for.
  3. An AI reading the class file gets no metadata unless its tooling happens to know about meta/.

A " comment costs the ABAP nothing — it is not "!, so SLIN/ATC does not report an unknown tag — and it cannot desync from the class, because it is in the class.

Why the rest is not on the class

A deviation note with three paragraphs and a verification date is not a property of the class; it is a log entry about a process, usually written by a test run rather than by an author. Putting it in a " comment would bloat the source and would still be worse structured than JSON. That belongs beside the class, and the sidecar is right for it.

The test, when a new field turns up

Ask: would this still be true if nobody ever ran a check again? If yes it describes the sample and belongs on the class. If it only became true because somebody did something, it belongs in the sidecar.