Summary
In 1.4.0 (#33, PR #34) the Oak index naming check was tightened from
to
The new pattern requires a <productVersion> segment. Not every out-of-the-box AEMaaCS index definition has one, and for those the required pattern cannot be satisfied without pointing at a base index that does not exist.
Concrete case: cqPageLucene
On a current AEM as a Cloud Service instance (AEM SDK 2026.7.x) /oak:index holds 61 lucene index definitions. Many do carry a version segment, for example ntBaseLucene-2, damAssetLucene-13, cqTagLucene-4, damAssetStateIndex-8, fragments-12.
cqPageLucene does not. The product node is simply:
To customize it, the definition has to be named cqPageLucene-custom-<customVersion>, because <indexName> is cqPageLucene and there is no <productVersion> to insert. That name is rejected by 1.4.0.
Naming it cqPageLucene-<someVersion>-custom-<customVersion> would satisfy the validator, but it would reference a base index that does not exist on the instance, so it would no longer be a customization of the product index at all.
Worth noting that the currently "invalid" name works exactly as intended. On our instance /oak:index/cqPageLucene-custom-7 is active and picked by the query engine:
[cq:Page] as [p] /* lucene:cqPageLucene-custom-7
indexDefinition: /oak:index/cqPageLucene-custom-7
estimatedEntries: 15131
luceneQuery: +:ancestors:/content +jcr:content/jcr:title:A*
*/
So in this case the rule flags a naming convention, not a functional defect.
Why renaming is not a cheap workaround
A new index node name means a brand new index that Oak has to build from scratch, it does not inherit the old index's data. The index above is 5.3 GB on our production environment. Adobe's recommended rollout (deploy the new definition alongside the old one, wait for reindexing, remove the old one in a later deployment) has to complete within the deployment, and at that size it does not.
So the validator effectively asks for a rename that is disproportionately expensive, to fix a name that is arguably already correct for this particular product index.
Why the existing configuration does not help
defaultSeverity=warn lowers all seven rules for the affected package, not just this one, so the other six checks lose their teeth.packageRestriction only scopes per package, so the exception cannot be narrowed to a single index definition.- The FileVault validation framework offers no per-message severity, no path or file exclusion, and no way to suppress an individual violation.
- The four available options (
allowReadOnlyMutablePaths, allowLibsNode, allowHooksInMutableContent, allowVarNodeOutsideContainer) do not cover this.
Pinning back to 1.3.0 does work, since this regex was the only functional change in 1.4.0, but that freezes the validator and forgoes any future rules.
Feature request
An option to exempt specific index definitions from the naming check, in the style of the existing options. Something like:
<netcentric-aem-cloud>
<options>
<ignoredIndexNames>cqPageLucene-custom-7</ignoredIndexNames>
</options>
</netcentric-aem-cloud>A comma-separated list of node names, or a regex, would both work. The important part is that it leaves the other six rules at error and keeps the exception visible and documented in the POM, rather than silently downgrading the whole validator.
An alternative would be to also accept <indexName>-custom-<customVersion> and <prefix>.<indexName>-custom-<customVersion> when the index name carries no version segment. That is harder to do correctly, since the validator cannot know which product indexes are unversioned, which is why an explicit opt-out seems the more pragmatic route.
Happy to contribute a PR if you are open to adding such an option.
Summary
In 1.4.0 (#33, PR #34) the Oak index naming check was tightened from
to
The new pattern requires a
<productVersion>segment. Not every out-of-the-box AEMaaCS index definition has one, and for those the required pattern cannot be satisfied without pointing at a base index that does not exist.Concrete case:
cqPageLuceneOn a current AEM as a Cloud Service instance (AEM SDK 2026.7.x)
/oak:indexholds 61 lucene index definitions. Many do carry a version segment, for examplentBaseLucene-2,damAssetLucene-13,cqTagLucene-4,damAssetStateIndex-8,fragments-12.cqPageLucenedoes not. The product node is simply:To customize it, the definition has to be named
cqPageLucene-custom-<customVersion>, because<indexName>iscqPageLuceneand there is no<productVersion>to insert. That name is rejected by 1.4.0.Naming it
cqPageLucene-<someVersion>-custom-<customVersion>would satisfy the validator, but it would reference a base index that does not exist on the instance, so it would no longer be a customization of the product index at all.Worth noting that the currently "invalid" name works exactly as intended. On our instance
/oak:index/cqPageLucene-custom-7is active and picked by the query engine:So in this case the rule flags a naming convention, not a functional defect.
Why renaming is not a cheap workaround
A new index node name means a brand new index that Oak has to build from scratch, it does not inherit the old index's data. The index above is 5.3 GB on our production environment. Adobe's recommended rollout (deploy the new definition alongside the old one, wait for reindexing, remove the old one in a later deployment) has to complete within the deployment, and at that size it does not.
So the validator effectively asks for a rename that is disproportionately expensive, to fix a name that is arguably already correct for this particular product index.
Why the existing configuration does not help
defaultSeverity=warnlowers all seven rules for the affected package, not just this one, so the other six checks lose their teeth.packageRestrictiononly scopes per package, so the exception cannot be narrowed to a single index definition.allowReadOnlyMutablePaths,allowLibsNode,allowHooksInMutableContent,allowVarNodeOutsideContainer) do not cover this.Pinning back to 1.3.0 does work, since this regex was the only functional change in 1.4.0, but that freezes the validator and forgoes any future rules.
Feature request
An option to exempt specific index definitions from the naming check, in the style of the existing options. Something like:
A comma-separated list of node names, or a regex, would both work. The important part is that it leaves the other six rules at
errorand keeps the exception visible and documented in the POM, rather than silently downgrading the whole validator.An alternative would be to also accept
<indexName>-custom-<customVersion>and<prefix>.<indexName>-custom-<customVersion>when the index name carries no version segment. That is harder to do correctly, since the validator cannot know which product indexes are unversioned, which is why an explicit opt-out seems the more pragmatic route.Happy to contribute a PR if you are open to adding such an option.