> For AI agents: the complete documentation index is available at https://nhanbe.id.vn/llms.txt, the full documentation bundle is available at https://nhanbe.id.vn/llms-full.txt. # Resource Resolution and the Sling Resource Merger ## 23 – Resource Resolution and the Sling Resource Merger > **Target:** 3–4 years experienced AEM Developer **Companies:** Valtech, Publicis Sapient, Deloitte Digital, Cognizant, Accenture, TCS, Capgemini, Infosys, IBM, LTIMindtree **Project domain:** a global energy technology company's marketing site. *** ## Before we start — why this topic separates the developers from the support engineers File 01 gave you the headline version of resource resolution: URL → Resource → Resource Type → Script, and a one-line mention that `/apps` beats `/libs`. That was enough to survive the architecture round. This file is what happens when the interviewer doesn't stop there. Every mid-to-senior AEM interview eventually asks some version of _"how do you add one field to a component's dialog without copying the whole thing?"_ or _"why did our short URLs suddenly start rendering `/content` in every link?"_ Both questions live entirely inside the machinery this file covers: the `ResourceResolver` object itself, the exact difference between `resolve()` and `getResource()`, how overlay, inheritance and override are three genuinely different mechanisms and not three names for the same trick, how the Sling Resource Merger actually stitches two resource trees together, and how `/etc/map` and `resourceResolver.map()` work together — not separately — to give you clean URLs. Here is why this matters for you specifically. Coming from support, you have almost certainly _used_ the symptoms of this machinery without knowing the mechanism: a ticket where a page 404'd anonymously but worked for a logged-in author, a ticket where "the field doesn't save," a ticket where "links are broken after the URL shortening went live." Every one of those is this file. Learning the mechanism turns four separate memorised incidents into one understood system — and that is exactly the kind of answer that makes an interviewer sit up. *** ## 1. Introduction ### 1.1 What resource resolution actually is, and why it deserves its own file In file 01 you learned that Sling turns a URL into a resource, and a resource into a script. The object that does all of that work — every single step — is one Java object: the **`ResourceResolver`**. Almost everything you write in AEM eventually touches this object, directly or through something built on top of it. A Sling Model's `@ValueMapValue` reads from it. A servlet's `request.getResourceResolver()` is it. A scheduled job that needs to read content has to obtain one. HTL's `data-sly-resource` asks it for a resource to include. If you don't understand what this object is and whose permissions it carries, half of AEM's stranger behaviours — the field that "doesn't save," the page that 404s for one user and not another, the servlet that silently stops working — will look like bugs in the platform rather than what they actually are: this object behaving exactly as designed. ### 1.2 The one sentence to memorise before anything else > **A `ResourceResolver` is a session into the repository, and it always carries the permissions of whichever user it was opened for.** That is the entire idea, and everything in this file is a consequence of it. File 13 covers users, groups and ACLs in depth — this file is where those permissions actually get _enforced_, at the moment a path is turned into a resource. If the resolver belongs to an anonymous visitor, every `getResource()` call it makes is filtered by what anonymous can read. If it belongs to a service user with narrow grants, it is filtered by that. If it belongs to an admin, almost nothing is filtered — which is exactly why file 13 tells you never to reach for `getAdministrativeResourceResolver()` out of convenience. ### 1.3 When you reach for this API directly Most of the time you don't — Sling Models and HTL hide the `ResourceResolver` behind `@ValueMapValue` and `data-sly-resource`. You reach for it directly when: - You are writing a **servlet** and need to read a resource other than the one the request resolved to. - You need a **service user** resolver to read content the current visitor cannot see (file 13, and again in section 2.4 here). - You are generating a **link** in Java and need the short, public-facing form of an internal path — `map()`. - You are debugging _why_ a path didn't resolve the way you expected. ### 1.4 A real project example to adapt > "On our energy site, most of our resource resolution is invisible — Sling Models and HTL do it for us. Where we touch the `ResourceResolver` directly is in three places: our Load More servlet, which reads sibling product pages under the current listing; a scheduled job that reads pricing data through a service user because the page tree it walks is partially access-controlled; and a link-building utility that calls `map()` so PDFs generated for download always contain public, shortened URLs rather than internal `/content` paths. Getting the third one wrong — forgetting the outbound half of URL mapping — is exactly the incident I'd bring up if asked for a project story here." That paragraph does three things: shows you understand where the API is actually used, name-drops a service-user story (file 13's territory), and pre-loads the URL-shortening story from section 7. *** ## 2. Core Concepts ### 2.1 The ResourceResolver API — the methods you're actually asked about Let's go through the API surface method by method, because interviewers frequently hand you two of these side by side and ask you to explain the difference. **`getResource(String path)`** — the plain, honest lookup. Give it a path, it gives you back a `Resource` if one exists there, or **`null`** if it doesn't. No mapping is applied. No 404 page is generated. It is the JCR equivalent of asking "is anyone home at this exact address?" There is an overload, `getResource(Resource base, String relativePath)`, which resolves relative to a resource you already have — useful when walking a tree without rebuilding absolute paths by hand. **`resolve(...)`** — covered in full in 2.2, because this is the one that trips people up. **`map(...)`** — the outbound counterpart. Give it an internal repository path (and optionally the current request), and it gives you back the externally usable URL, applying whatever `/etc/map` rules or vanity paths apply. Section 2.10 onward covers this in depth. **`adaptTo(Class type)`** — not specific to `ResourceResolver`, but used constantly through it. Most commonly you'll see `resolver.adaptTo(Session.class)` to drop down to the raw JCR API when you need something the Sling Resource API doesn't expose, like a `Session` -level move or a workspace-level operation. **`listChildren(Resource resource)`** — returns an `Iterator` of the resource's direct children. This is what a Sling Model uses under the hood when you inject `List children` — but knowing you can call it directly matters when you're walking a tree in a servlet or a service. **`findResources(String query, String language)`** — runs a query (JCR-SQL2 or XPath) through the resolver and returns matching resources as an iterator. This is the lower-level cousin of QueryBuilder from file 01 — QueryBuilder is friendlier for building dynamic predicates, `findResources` is what you reach for when you already have a query string and don't want QueryBuilder's ceremony. The same indexing rules from file 01 apply: an unindexed query traverses and can hang the instance. **`getSearchPath()`** — returns the configured search path as a `String[]`, by default `{"/apps/", "/libs/"}`. This is the array Sling walks, in order, whenever it needs to turn a _relative_ resource type into an absolute script path. Knowing this method exists is what lets you answer "how would you check the search path on this instance without reading OSGi config by hand?" — you'd call this, or check it from a script console. **`getUserID()`** — returns the ID of the user this resolver is authenticated as. The fastest way to prove, in a debugging session, that you are looking at the resolver you think you are. **`close()`** — releases the underlying session. Section 2.4 covers the rule that decides everything about this method: close what you opened, never close what you were handed. ### 2.2 resolve() versus getResource() — the distinction almost everyone gets wrong This is the single most commonly mis-answered question in this whole file, so slow down here. Both methods take a path and give you back a `Resource`. That surface similarity is exactly why people assume they're interchangeable. They are not, and the difference matters in production. **`getResource(path)`** does a direct, literal lookup. No URL mapping. No selector or extension stripping. No search-path fallback for a relative resource type on the node itself. If nothing exists at that exact path, you get **`null`**. **`resolve(request, path)`** — usually called as `request.getResourceResolver().resolve(request)` inside Sling's own request-handling code, or as `resolver.resolve(path)` in your own code — is the _full_ pipeline. It: 1. Applies `/etc/map` inbound rewriting, so a public-facing path gets translated to its internal repository path first. 2. Strips selectors, extension and suffix from the incoming path before attempting to find the underlying resource. 3. If, after all of that, nothing exists — it does **not** return `null`. It returns a special object called a **`NonExistingResource`**. **Say that last part out loud, because it's the part that gets tested:** > `getResource()` on a missing path gives you `null`. `resolve()` on a missing path never gives you `null` — it gives you a `NonExistingResource`, which is a real, non-null `Resource` object whose resource type is set to a fixed marker value. **Why does Sling bother with this instead of just returning `null` in both cases?** Because `resolve()` is what runs at the very top of the request-processing pipeline — before Sling even knows whether this is going to be a 404. If `resolve()` returned `null`, every single piece of downstream code that expects a `Resource` object would need a null check just to handle "the page doesn't exist," and Sling's own script-resolution machinery (URL → Resource → Resource Type → Script from file 01) would break, because it needs a resource type to look up a script — even the 404 page is rendered _through_ the same resourceType-to-script pipeline as everything else. By giving you a `NonExistingResource` with resource type `sling:nonexisting`, Sling lets the _same_ machinery that finds `page.html` for a real page also find a custom 404 script — placed at `/apps/sling/nonexisting` — for a resource that doesn't exist. One pipeline handles both cases. **The practical consequence for your own code:** ```java // getResource -- direct, literal, can be null Resource r1 = resolver.getResource("/content/energy/us/en/products/does-not-exist"); if (r1 == null) { // this branch is reachable } // resolve -- full pipeline, NEVER null, but can be a NonExistingResource Resource r2 = resolver.resolve(request, "/content/energy/us/en/products/does-not-exist"); if (r2 == null) { // THIS BRANCH IS DEAD CODE. resolve() never returns null. } if (ResourceUtil.isNonExistingResource(r2)) { // this is the check you actually need } ``` **The interview answer:** > " `getResource()` is a direct lookup — you give it a path, and you get either the resource or `null`. It doesn't apply any URL mapping. `resolve()` is the full pipeline Sling uses to turn an incoming request path into a resource: it applies `/etc/map` inbound rewriting first, strips selectors and extension, and — this is the part people miss — it never returns `null`. If nothing matches, it gives you back a `NonExistingResource`, which is a real object with a fixed resource type, `sling:nonexisting`. Sling does that so the same URL-to-script pipeline that renders every other page can also render a custom 404 page, just by placing a script at that resource type. So if I write `if (resolver.resolve(path) == null)`, that branch is dead code — I need to check `ResourceUtil.isNonExistingResource()` instead." ### 2.3 NonExistingResource and SyntheticResource Two "fake" resource types come up in interviews together, and it's worth being precise about what each is for. **`NonExistingResource`** — already covered above. It exists specifically to represent "nothing is here" as a real `Resource` object, with resource type `sling:nonexisting`, so that 404 handling can go through the normal script-resolution pipeline instead of needing a special case. ```text /apps/sling/nonexisting/sling.html ← your custom 404 page, matched by resource type ``` **`SyntheticResource`** — a `Resource` object that is not backed by an actual repository node at all. You can construct one yourself with `new SyntheticResource(resolver, path, resourceType)` whenever you need to hand something through the Resource API that has no real content behind it — a computed row in an aggregated listing, a fixture in a unit test, or a placeholder Sling itself needs internally when a path exists conceptually (an intermediate segment on the way to a real resource) but has no corresponding node. **The one-line distinction:** a `NonExistingResource` specifically means _"resolution failed, here's a stand-in so the pipeline keeps working."_ A `SyntheticResource` more broadly means _"here's a Resource with no repository node behind it,"_ and you can create those yourself for your own purposes, whereas you would never construct a `NonExistingResource` by hand — Sling gives you one. ### 2.4 Closing rules — the one habit that prevents a production incident This continues directly from files 07 and 13, and it is worth restating here because this file is where the rule actually lives. **The rule, in one sentence:** _close a resolver only if you opened it yourself._ `request.getResourceResolver()` in a servlet, or the resolver backing a Sling Model's injected fields, belongs to Sling. Sling opened it when the request came in, and Sling will close it when the request finishes. If you call `.close()` on it yourself, you don't get an error immediately — you get everything _after_ that call in the same request failing, because the JCR session backing it is now gone. A resolver you obtain from `resourceResolverFactory.getServiceResourceResolver(...)` (file 13's service-user pattern) is different: **you** opened it, so **you** must close it — always in try-with-resources, never in a `finally` block you might forget to write correctly. ```java // You opened this one. You close it. Always try-with-resources. try (ResourceResolver serviceResolver = resolverFactory.getServiceResourceResolver(authInfo)) { Resource priced = serviceResolver.getResource("/content/energy/pricing/2026"); // ... use it while the resolver is open ... } // closed automatically, even if an exception was thrown above ``` ### 2.5 What a leaked resolver actually looks like in production This is worth walking through slowly, because "session leak" is an abstract phrase until you've seen what it does. Every `ResourceResolver` you open from a factory holds open a real JCR `Session` underneath it. A `Session` is not free — it holds memory, and in a clustered Oak setup it can hold onto resources that the garbage collector cannot reclaim, because something still technically has a reference to it: your unclosed resolver. If a piece of code — say, a scheduled job or a servlet that runs on every request — opens a service-user resolver and forgets to close it, here is the timeline you actually see: 1. **Day one:** nothing looks wrong. The instance has plenty of headroom. 2. **Over days or weeks:** heap usage on that instance creeps upward in a way that doesn't correlate with traffic. It goes up and never comes back down after a GC cycle, because live references are pinning those sessions. 3. **Eventually:** the instance starts throwing `OutOfMemoryError`, or session-related warnings appear in the logs about too many open sessions, and a restart "fixes" it — until the leak accumulates again. **Why this is hard to diagnose the first time you see it:** the symptom (an instance slowly dying) looks nothing like the cause (one missing `.close()` in one servlet). Nobody's first instinct is "check for unclosed resolvers" when heap usage is climbing — they look at traffic, at cache sizes, at the DAM. The diagnostic order that actually gets you there fast is in section 11. ### 2.6 The search path and how a resource type becomes a script — recap and one layer deeper File 01 gave you the eight-step script resolution order ending in " `/apps` before `/libs`." Here is the one thing worth adding on top of that, because it's what interviewers probe for when they think you've only memorised the list. **The search path is configuration, not a hardcoded constant.** It comes from the Sling Resource Resolver Factory's OSGi configuration — the same place service-user mappings live (file 13) — and while `/apps` then `/libs` is the standard order almost every project keeps, it is technically a list you _could_ reorder or extend. You will essentially never see a project that changes it, but knowing it's configuration rather than a law of physics is the difference between reciting a fact and understanding a mechanism. **`sling:resourceType` versus `sling:resourceSuperType` — the one-sentence distinction that matters here:** - `sling:resourceType` says **what this resource is**. It's the starting point of script resolution. - `sling:resourceSuperType` says **what to fall back to** if a script isn't found at the resource type's own path. It's how one component can inherit another's rendering and dialog without being a copy of it. This second one is the mechanism behind proxy components (file 02) and it is also, as you'll see in section 2.9, one of the two ways the Resource Merger stitches content together — not just the `/apps` -over- `/libs` search path, but _also_ the `resourceSuperType` chain. ### 2.7 Overlay, Inheritance, and Override — the comparison interviewers actually ask for These three words get used loosely in everyday project conversation, and that looseness is exactly what an interviewer is testing when they ask you to tell them apart. Treat this as three genuinely different mechanisms that happen to solve related problems. **Overlay.** You place a resource at the **same relative path** under `/apps` as one that exists under `/libs`. Because the search path checks `/apps` first, your version is found first and effectively hides Adobe's. Nothing about the original at `/libs` changes — it's still there, just never reached, because `/apps` won the race. This is a **path-based, global** mechanism. It has no concept of "just this one component" — if two completely unrelated things happen to resolve through the same relative path, overlaying it affects both. That's what makes it powerful and also the riskiest of the three. **Inheritance.** A resource declares `sling:resourceSuperType`, pointing at a different resource type entirely — usually a Core Component, or a shared base component within your own project. If a script or dialog isn't found at your resource's own path, resolution falls through to the resource type named in `resourceSuperType`, and keeps falling through the chain until something answers or the chain ends. This is a **scoped, deliberate** relationship — you are explicitly opting one component into another's behaviour. It has nothing to do with `/apps` versus `/libs`; you can inherit from a component that lives entirely under `/apps`, as proxy components do (file 02). **Override.** Complete replacement, with no fallback and nothing inherited. You aren't extending or shadowing something — you're saying "ignore whatever else exists at any lower-priority location; use exactly and only what I've provided here." Section 2.9 covers the concrete mechanism the Resource Merger gives you for this: the `/mnt/override` mount, as distinct from the merging behaviour of `/mnt/overlay`. **The comparison, side by side:** | | Overlay | Inheritance | Override | | ------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | | Mechanism | Same relative path, `/apps` before `/libs` | `sling:resourceSuperType` chain | Complete replacement, no merge | | Scope | **Global** — anything resolving to that path | **Scoped** — only components that opt in | Scoped to the resource declaring it | | What survives from the original | Nothing reachable, but the original still exists at `/libs` | Whatever you don't explicitly redefine | Nothing — that's the point | | Risk profile | **Higher** — you can't tell everything that resolves through that path | Lower — you know exactly what opted in | Depends entirely on what you left out | | Typical use | Customising the AEM authoring UI itself (a console, a classic dialog) | Extending a Core Component or a proxy | Replacing an entire dialog or script wholesale, deliberately | | Upgrade safety | You silently stop receiving Adobe's fixes to that exact path | You keep receiving fixes to everything you didn't override | You keep nothing from upstream at all | **Why overlay is riskier, stated plainly:** when you overlay `/libs/foo/bar` with `/apps/foo/bar`, you have frozen your copy in time. The next time Adobe patches or improves `/libs/foo/bar`, you don't get it — your `/apps` copy still wins the search path, and it's now stale relative to the product. This is exactly the same risk file 01 warned about for editing `/libs` directly, except overlay doesn't corrupt the original — it just silently shadows improvements to it. Nobody notices until a security patch to that exact path ships and doesn't take effect on your instance. **Why inheritance is safer, stated plainly:** because you only redefine the specific pieces you touch — one new dialog field, one changed HTL block — everything else keeps flowing through to the real component. When Adobe ships a Core Component update, your proxy still inherits all of it automatically; you only "own" the small delta you actually wrote. **The interview answer:** > "They solve related problems but they're mechanically different. Overlay is path-based — same relative location under `/apps` as under `/libs`, and the search path means yours wins. It's global, which is also its risk: you can't always tell everything that resolves through that path, and you silently stop receiving Adobe's improvements to it. Inheritance is `sling:resourceSuperType` — a deliberate, scoped relationship where a component opts into extending another one, and it's how proxy components and Core Component customisation work; you keep receiving upstream improvements to everything you didn't specifically redefine. Override is the least common of the three — a complete replacement with no fallback at all, which the Resource Merger gives you explicitly through `/mnt/override` as distinct from the merging behaviour of `/mnt/overlay`. I default to inheritance, reach for overlay only to customise the authoring UI itself, and use override rarely and deliberately." ### 2.8 The Sling Resource Merger — the problem it actually solves Here is the scenario that makes the Resource Merger necessary, told the way it actually happens on a project. You are three weeks into the energy site build. A stakeholder asks for one extra field on the page properties dialog — a "Regulatory Region" dropdown, because pages need to be tagged for compliance reasons that have nothing to do with anything Adobe anticipated. The out-of-the-box page properties dialog has a dozen tabs and does dozens of things correctly already — SEO metadata, social sharing, page thumbnails, cloud configuration references. You need exactly one more field. **The wrong way to do this** — and the way almost every AEM developer tries first — is to copy the entire OOTB dialog node from `/libs` down to `/apps`, then add your one field to the copy. It works. It also means: - You now own a full duplicate of Adobe's dialog structure, frozen at whatever version you copied it from. - Every future Adobe fix, every new field Adobe adds to page properties in a later service pack or Cloud Service release, never reaches you — your copy doesn't know it exists. - Six months later, nobody remembers this copy was made for one field, and a code reviewer has no way to tell "this diverged from Adobe's version deliberately" from "this diverged from Adobe's version because someone forgot to update it." **The Resource Merger exists specifically to avoid this.** Instead of copying the whole dialog, you create a resource under `/apps` at the relevant path that contains **only** the new field, and the Resource Merger combines — merges — your small addition with Adobe's full dialog at read time, every time it's rendered. You never own more than the delta you actually wanted. **Why this is worth stating as the "why" before the "how":** an interviewer who asks about the Resource Merger is really asking "do you understand the cost of copying product code, and do you know the alternative?" Leading with the cost of copying, the way this section just did, answers the _reason_ the mechanism exists before you even describe the mechanism itself. ### 2.9 The two mount points — /mnt/overlay and /mnt/override This is the part of the Resource Merger that most candidates who "know the name" cannot actually explain, and it's where you can visibly separate yourself from someone who has only heard the term. The Resource Merger produces its combined view of the world at two special, virtual mount points. Neither of these is something you write content into directly — you keep writing your actual content under `/apps`, at the same relative path as the thing you're extending, and the Resource Merger computes the merged (or overridden) view on the fly whenever something reads through one of these paths. **`/mnt/overlay/`** — the **merging** view. For every resource in the search path (by default `/apps` and `/libs`, in priority order), the Resource Merger combines them into one logical resource: - Properties present in the higher-priority location (`/apps`) win over the same property name from the lower-priority one (`/libs`). - Properties that exist **only** at the lower-priority location are still present in the merged result — nothing is lost by default. - Child resources are combined the same way, recursively — your one new child node under `/apps` appears alongside all of Adobe's existing children from `/libs`. This is the mount point behind almost everything people mean when they casually say "the Resource Merger" — it's how AEM computes the effective page properties dialog, and how it computes the effective dialog for a component when a proxy adds a field on top of a Core Component it inherits from. **`/mnt/override/`** — the **overriding** view. Instead of combining everything found in the search path, this mount point picks up **only** the single highest-priority resource that exists, and uses it exactly as-is — no merging with anything lower in the search path at all. If `/apps/foo/bar` exists, that is the entire answer; `/libs/foo/bar` is never consulted, not even for properties `/apps/foo/bar` doesn't define. **The plain-English distinction, worth having ready:** > " `/mnt/overlay` combines what it finds across the search path — your addition plus everything from `/libs` you didn't touch. `/mnt/override` picks only the highest-priority one it finds and stops there, with nothing merged in from underneath. Overlay is for extending; override is for replacing outright." **Why you rarely reach for `/mnt/override` deliberately:** almost every real customisation is additive — one more field, one more tab, one hidden property. Genuine full replacement is rare enough that most projects go their entire lifetime without a developer needing to invoke override semantics on purpose. It exists for the cases where merging genuinely isn't what you want — for example, a dialog so different from the original that trying to "hide" your way to the result would be more code than just replacing it. graph TD subgraph SP\["Search path resources"] LIBS\["/libs/foo/bar\
jcr:title = 'Original'\
field-a, field-b"] APPS\["/apps/foo/bar\
jcr:title = 'Energy Override'\
field-c (new)"] end LIBS --> OVERLAY APPS --> OVERLAY OVERLAY\["/mnt/overlay/foo/bar\
\MERGED:\\
jcr:title = 'Energy Override' (apps wins)\
field-a, field-b (kept from libs)\
field-c (added from apps)"] LIBS -.->|"never consulted"| OVERRIDE APPS --> OVERRIDE OVERRIDE\["/mnt/override/foo/bar\
\OVERRIDE:\\
jcr:title = 'Energy Override'\
field-c only\
(field-a, field-b are GONE)"] ### 2.10 The properties that control the merge Four properties, placed on the resource you create under `/apps`, give you fine control over the merged result. All four live in the `sling:` namespace, and all four only make sense in the context of the `/mnt/overlay` merging behaviour — they're how you selectively remove or reposition pieces of the lower-priority resource rather than accepting everything from it by default. **`sling:hideResource`** (Boolean) — placed on a node to say "this entire resource, at this path, should not appear in the merged result, even though something exists here at a lower priority." This is a full hide — the merged view behaves as if nothing exists at this path at all. **`sling:hideProperties`** — a String or String array naming specific property names to remove from the merged result, even though they exist on the lower-priority resource. Use `"*"` to hide every inherited property at that node, keeping only what you define yourself. **`sling:hideChildren`** — the same idea, but for child resources rather than properties. Name specific child node names to exclude, or `"*"` to exclude everything inherited and keep only children you've explicitly added. **`sling:orderBefore`** — a String naming a sibling node. Positions your added or merged child before that named sibling in the merged child ordering. Without this, a newly added field or tab tends to land at the end, which is rarely where you want it — a "Regulatory Region" field added to page properties should sit near the other compliance fields, not trail after everything else. **A concrete example, put together:** Say Adobe's dialog under `/libs` has a "SEO" tab containing fields `metaTitle`, `metaDescription`, and `robotsTag`. You want to: keep `metaTitle` and `metaDescription`, remove `robotsTag` because your project handles that a different way, and add a new field `regulatoryRegion`, positioned right after `metaDescription`. ```xml ``` **Notice `sling:orderBefore="robotsTag"` even though `robotsTag` is about to be hidden.** That's deliberate and worth explaining if asked: ordering is resolved against the full merged child list _before_ hiding is applied, so naming the sibling you're about to hide is still a valid, stable way to say "put me exactly where that field used to be." (If that makes you uneasy about ordering drifting when the hidden sibling itself moves in a future Adobe update, that instinct is correct — it's one of the few genuine downsides of this approach, and it's why some teams anchor `orderBefore` against a field they know Adobe treats as stable, like the tab's first item, rather than one that might be reordered upstream.) ### 2.11 The classic use cases, tied to files 02 and 22 **Extending page properties.** Exactly the scenario in 2.8 — add a field or a whole new tab to Adobe's out-of-the-box page properties dialog. The dialog itself lives under `/libs` (the exact path has shifted slightly across AEM versions — historically the classic Foundation page dialog sat at `/libs/foundation/components/page/dialog`; the mechanism is identical regardless of the exact path in your version). You place a resource at the same relative path under `/apps`, containing only your addition, and the `/mnt/overlay` merge does the rest. **One nuance worth stating precisely, because it's a genuine gotcha:** on a project built with **editable templates** — which is the standard on AEM as a Cloud Service and almost every modern project, including our energy site — each template defines its _own_ page properties structure under `/conf//settings/wcm/templates/