How to make your content packages comply with Jackrabbit FileVault Validation

1 Overview
2 Package Type
3 Validation rule violations
- 3.1 Configuration examples
4 Solutions for common problems
5 Related articles

Overview

Since version 1.1.0 the Jackrabbit FileVault Package Maven Plugin validates the package contents against a set of validators that check the consistency and validness of your package content and filter definition.

If your package was created with older versions of the plugin, or migrated from other content package plugins (see also https://wcm-io.atlassian.net/wiki/spaces/WCMIO/pages/91586585) it is likely that your package violates some of theses rules and your build fails.

In most cases the validation errors reported are correct, and you indeed have to some problems in your content package that need to be fixed.

Package Type

An important configuration property of the Jackrabbit FileVault Package Maven Plugin is the packageType. Previous versions of the plugin already required this property, but did only few validations based on it. The documentation of this property lists these types:

application: An application package consists purely of application content. It serializes entire subtrees with no inclusion or exclusion filters. It does not contain any subpackages nor OSGi configuration or bundles.
- Contains only (application) content below /apps or /libs.
content: A content package consists only of content and user defined configuration. It usually serializes entire subtrees but can contain inclusion or exclusion filters. it does not contain any subpackages nor OSGi configuration or bundles.
- Contains only content below /content or /conf.
container: A container package only contains sub packages and OSGi configuration and bundles. The container package is only used as container for deployment.
- Contains no content at all, but only OSGi configurations, bundles and/or sub packages
mixed: Catch all type for a combination of the above.
- This is only for legacy use cases. You should avoid to use this package type.

So, before looking in detail on any of the validation errors or warnings, check that the package type is correct. The validations applied on the package depends on the package type.

If your package contains a mixture of the different package types you should split up or refactor your packages so that each one complies with one of the requirements of the first three package types. This is also important if you migrate to the AEM as a Cloud Service later on.

If you have packages that contain application content below /etc you should move this to /apps, see also https://wcm-io.atlassian.net/wiki/spaces/WCMIO/pages/1204322305 for the most common use case.

Validation rule violations

The validation messages printed by the plugin are usually quite self-explanatory. Try to fix them one-by-one until your build runs fine. Also check the warnings and try to resolve the issues as well.

If you are stuck with a rule violation where you have no valid fix and are sure that it will not create a problem when deploying on the AEM instances, you can disable single checks of the validators, or whole validators.

First, you have to lookup the validators and their options in the documentation:
https://jackrabbit.apache.org/filevault/validation.html

Configuration examples

In this example, we reconfigure the jackrabbit-filter validator to tell him that it’s fine that the parent application folder is not contained in the package itself, and also not in a package declared as dependency:

<plugin>
  <groupId>org.apache.jackrabbit</groupId>
  <artifactId>filevault-package-maven-plugin</artifactId>
  <extensions>true</extensions>
  <configuration>
    <packageType>application</packageType>
    <validatorsSettings>
      <jackrabbit-filter>
        <options>
          <validRoots>/apps/myapp</validRoots>
        </options>
      </jackrabbit-filter>
    </validatorsSettings>
  </configuration>
</plugin>

Example to disable a validator completely:

<plugin>
  <groupId>org.apache.jackrabbit</groupId>
  <artifactId>filevault-package-maven-plugin</artifactId>
  <extensions>true</extensions>
  <configuration>
    <packageType>mixed</packageType>
    <validatorsSettings>
      <jackrabbit-packagetype>
        <isDisabled>true</isDisabled>
      </jackrabbit-packagetype>
    </validatorsSettings>
  </configuration>
</plugin>

Solutions for common problems

Filter root's ancestor is not covered by any of the specified dependencies nor a valid root

Problem:

[ERROR] ValidationViolation: "jackrabbit-filter: Filter root's ancestor '/apps/myapp' is not covered by any of the specified dependencies nor a valid root.", filePath=META-INF\vault\filter.xml

Solution:

If this affects an application package (e.g. ui.apps or complete package) and affects content paths you are sure that exist already (e.g. because they are AEM standard paths, or because they are already created by other means, e.g repoinit or other packages), customize the validator to allow those parent paths:

The Adobe AEM project archetypes uses an “apps-repository-structure” package and references it via repositoryStructurePackages property. But this approach is more verbose and requires a separate maven module to achieve the same result. So it’s recommended to use the validRoots configuration approach.

Given root node name 'xxx:yyy' (implicitly given via filename) cannot be resolved

In case you get an error like this:

the folder name contains an escaped namespace (like _cq_tags), but the namespace declaration of “cq” is missing in the contained .content.xml. Solution: Add the missing namespace declaration, or re-export the package from AEM using the latest wcmio-content-package-maven-plugin.

Last resort: Disable Validators

If you have a content package with a very “legacy” structure and you at the moment do not have the time to really solve the reported violations, and currently do not have to care about requirements like AEMaaCS compatibility, you can disable some or all validators. Use this only as last resort.

Example for disabling two validators (full list see here):