How to make your content packages comply with Jackrabbit FileVault Validation

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 Migrate content package projects from wcmio-content-package-maven-plugin to Jackrabbit filevault-package-maven-plugin) 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 depend 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 Cloud Service later on.

If you have packages that contain application content below /etc you should move this to /apps, see also How to switch your AEM Client Library to Proxy Mode for the most common use case.

Validation rule violations

The validation messages which are 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) you should define an “apps-repository-structure” and reference it via repositoryStructurePackages in your application package. See AEM documentation and FileVault Package Maven Plugin documentation for further details.

If you do not want to define this extra package and are sure that the missing path will always exist when the package gets installed you can also reconfigure the filter to define the missing root as “valid root”:

<validatorsSettings>
  <jackrabbit-filter>
    <options>
      <validRoots>/apps/myapp</validRoots>
    </options>
  </jackrabbit-filter>
</validatorsSettings>

Last resort: switch to old plugin version

If you have a content package with a very “legacy” structure and you currently do not have the time to really solve the reported violations, and currently do not have to care about requirements like AEM cloud service compatibility, you can switch to an older version of the plugin that does not contain all these new validations. Use this only as last resort.

<plugin>
  <groupId>org.apache.jackrabbit</groupId>
  <artifactId>filevault-package-maven-plugin</artifactId>
  <!-- This is a content package with a lot of legacy stuff that is not compatible with the package validations from the lastest plugin versions -->
  <version>1.0.3</version>
</plugin>