AEM Forms backward compatibility and SDK update impact on Adaptive Forms proxy components
In Adobe Experience Manager (AEM) Forms, organizations often customize Adaptive Forms by using project-owned proxy components. Questions can arise about how SDK updates affect these customizations and how Adobe’s backward compatibility policy applies to Adaptive Forms component versions. To fix this issue, follow supported customization practices and validate all proxy components before promoting updates to production.
Description description
Environment
Adobe Experience Manager (AEM) as a Cloud Service (all versions)
Issue/Symptoms
- Concerns about minor SDK updates affecting custom proxy components or client libraries.
- Issues observed after SDK updates where custom code was impacted.
- Need for clarity on Adobe’s compatibility guarantees for Adaptive Forms component versions.
Cause
Minor or backward-compatible changes to Adaptive Forms component versions may affect custom proxy components if those customizations rely on internal or undocumented implementation details. Adobe’s compatibility guarantees apply only to documented extension points and supported out-of-the-box behavior, not to internal structures or overlaid resources.
Resolution resolution
Follow the steps below to resolve the issue:
- Configure project-owned proxy components: Use project-owned proxy components with
sling:resourceSuperTypereferencing the required Adobe Adaptive Forms component version. - Limit custom component changes: Minimize custom HTL and dialog changes. Use only documented APIs, events, selectors, and extension points.
- Create project-owned client libraries: Create separate project-owned client libraries with unique category names.
- Protect Adobe-owned client libraries: Avoid overlaying or modifying Adobe-owned shared runtime base or dependent client libraries.
- Validate customizations: Validate all customizations in a lower environment before promoting updates to production. After each SDK or Forms component update, regression-test all proxy components and customizations for rendering, authoring, validation, rules, prefill, submission, accessibility, client library loading, and custom JavaScript behavior.
- Validate and promote SDK updates: If the project manages the Adaptive Forms Core Components version as a dependency, update and deploy it to a lower environment first. Confirm that all custom proxy components and client libraries function as expected, and then promote the update to higher environments through your standard deployment process.
Notes
- Backward compatibility applies to supported out-of-the-box behavior, documented APIs, and documented extension points for Adaptive Forms components.
- Bug fixes and backward-compatible enhancements may be delivered within an existing component version as long as the supported contract is maintained.
- A new component version is introduced only for backward-incompatible changes to supported behavior or documented extension points.
- Implementation details such as HTL rendering, HTML and DOM structure, CSS classes, JavaScript behavior, client-side APIs, validation, rules execution, dialog and configuration structure, and client libraries may change within the same component version, provided the supported contract is maintained.
- Customizations that depend on internal implementation details, such as copied HTL, private DOM structures, undocumented selectors, or overlaid Adobe client libraries, aren’t guaranteed to remain unaffected by minor updates.
- Adobe-managed environments don’t provide a separate development-only automatic upgrade switch.