Show TOC

Compatibility RulesLocate this document in the navigation structure

When users and developers update to a new SAPUI5 version, it is vitally important that no applications break as a result of the upgrade. For this reason, always adhere to the compatibility rules described below when developing SAPUI5 controls and functionality.

API Evolution

Unless otherwise mentioned, the word "API" in this section refers to "public API", meaning functions, classes, namespaces, controls along with their declared properties, aggregations, and so on. The sole definition of the public API is the , which is included in the SAPUI5 Demo Kit. Features that are not mentioned there are not part of the API.

The following rules apply for introducing new APIs or making incompatible changes to existing APIs:

Major release: A new major version can introduce new APIs or make incompatible changes to existing APIs. If this is the case, any incompatibilities are described in the Release Notes.

Minor release: A new minor version, can introduce new APIs but must not contain incompatible changes to any APIs.

Patch release: A new patch version only contains fixes to the existing implementation, but does not usually contain new features or incompatible API changes.

Note Exceptions to these rules are possible, but only in very urgent cases such as security issues. Such exceptions are documented in the .
Compatible Changes

The following changes to existing APIs are compatible:

  • Adding new libraries, controls, classes, properties, functions, or namespaces
  • Generalizing properties, that is, moving properties up in the inheritance hierarchy
  • Adding new values to enumeration types; this means that when dealing with enum properties, always be prepared to accept new values, for example, by implementing a "default" or "otherwise" path when reacting on enum values.

The following is not part of the public API and may change in patch and minor releases:

  • Manipulating HTML/CSS, for example via jQuery, control.addStyleClass, or directly via CSS
  • Using or overriding "private" functions that are not part of the . Private functions are typically (but not always) prefixed with a preceding "_". Always double check this by looking in the API Reference.

  • Open source libraries
  • Log messages

Inheriting from SAPUI5 objects (e.g. by calling sap.ui.extend on an existing control to add custom functionality) may endanger the updatability of your code. We might add, remove, or change the internal implementation of the parent class at any time. In addition to the restrictions listed in the section "Compatible Changes", you should not rely on the following functionality:

  • Internal structures and methods that are not part of the public API
  • Any internal logic and behavior of the object that is not reflected in the public API
  • All rendering functionality of a control, including the HTML structure and CSS classes
  • Existence of SAPUI5 lifecycle methods like init, exit, onBeforeRendering and onAfterRendering. When overriding an SAPUI5 lifecycle method, always check for existence of the method and call the super class implementation even though it is currently not implemented.
  • Naming collisions with SAPUI5 structures and methods. SAPUI5 might introduce new API or internal structures at a later point in time that collide with your implementation. To avoid collisions, a custom prefix may be applied.

We recommend that you test inherited classes very carefully after updating SAPUI5 to make sure that the extended functionality is still working as expected.

Incompatible Changes

The following changes to existing APIs are incompatible and can only be done in a new major release:

  • Removing an API (library, namespace, function, property, control, events, and so on)
  • Renaming an API (library, namespace, function, property, control, events, and so on)
  • Removing support for parameters
  • Removing support for configuration entries
  • Reducing the visibility of an API; this does not break JavaScript applications, but changes the contract
  • Removing or reordering parameters in an API signature
  • Reducing the accepted value range, for example, parameter of a function
  • Broadening the value range of a return value (or property). Exception: enumerations
  • Moving JavaScript artifacts (namespaces, functions, classes) between modules
  • Replacing asserts with precondition checks
  • Moving properties (and so on) down in the inheritance hierarchy
  • Changing the name of enum values
  • Changing defaults (properties, function parameters)
  • Renaming or removing files

If possible and appropriate, SAPUI5 developers mark old artifacts as deprecated and create new artifacts, instead of making incompatible changes. A deprecation comment in the corresponding SAPUI5 library documentation, and perhaps also a log entry in the implementation, explain why and when an artifact has been deprecated and include tips on how to achieve the same results without using deprecated functionality.

Experimental API

Some features or controls delivered with the current SAPUI5 version are flagged as "experimental". These experimental features and controls are not part of the released scope of the delivered SAPUI5 version. Do not use experimental features or controls in a productive environment, or with data that has not been sufficiently backed up.

Experimental features and controls can be changed or deleted at any time without notice, and without a formal deprecation process. They may also be incompatible to changes provided in an upgrade.

Third-Party Open Source Libraries

SAPUI5 contains and uses several third-party open source libraries, such as jQuery. These libraries can also be used by applications and/or custom control libraries, but the SAPUI5 compatibility policy described within this document does not apply to these third-party libraries.

If you want to use the third-party open source libraries included in SAPUI5, note the following restrictions:

  • SAP decides which version(s) and modules of the used libraries are provided.
  • SAP can upgrade to higher version(s) of the used libraries even within a patch release.
  • For important reasons such as security, SAPUI5 can stop providing a library at any time.
  • The third-party libraries are provided "as is". Extensions, adaptations, and support are not performed or provided by SAP.

You are only allowed to use closed source libraries for the SAPUI5 controls for which they are intended.

For a list of the third-party open source software used in SAPUI5, see the page entitled Credits in the SAPUI5 Demo Kit.