Bundle and package versioning

Every bundle or export package has a version number in a specific format, and every import package statement has a version range. When you specify a version range, you need to consider current policy and best practices, and requirements for compatibility with both earlier and future versions.

Version numbers

Every bundle or export package has a version number. This version number consists of up to three numbers, in the following format:
9.9.9
The first number specifies the major component of the version number. The second number (if present) specifies the minor component of the version number, and the third number (if present) specifies the micro component of the version number. If you omit a component level, you also omit the period character, ., that comes before that component level. For example, the following three numbers all specify the same version:
9
9.0
9.0.0
According to the OSGi versioning policy, when a new version of a bundle or export package is not compatible with earlier versions you increment the major version number of the bundle or package.

Version ranges

Every import package statement specifies a version range. The OSGi Alliance recommends the following best practice for specifying a version range:
  • For the lower boundary of the range, specify the minimum version of the package that the consuming bundle requires.
  • For the upper boundary of the range, include any minor version but exclude any increment in the major version of the package.
Version ranges are specified using the following notation:
  • An opening bracket, [, or closing bracket, ], means include the end of the specified range.
  • An opening parenthesis, (, or closing parenthesis, ), means exclude the end of the specified range.
For example, the following import statement can resolve against any version of a package from version 1.0 up to, but not including, version 2.0. 
Import-Package: com.myco.a.pkge;version="[1.0,2.0)"

A package at version 1.3 is expected to be compatible with a package at version 1.0, and so a bundle that requires at least version 1.0 of a package should work if it is resolved against version 1.3 of that package. However, the bundle might not work if it is resolved against version 2.0 of the package, so version 2.0 and later versions are excluded.

Notes:
  • When new methods are added to an interface, the minor version number is incremented for the export package header. A class that implements the previous version of the interface can also work with the new version, but the new version is only made available if explicitly specified. In this case, the bundle importing the package that contains the interface should specify, for example, "[1.0,1.1)".

  • The Java™ Community Process (JCP) does not define OSGi metadata such as package versions when it defines APIs. Currently, the OSGi versions are defined in the OSGi specifications that reference the Java technologies. Future versions of JCP specifications are expected to be compatible with earlier versions, so the OSGi package versioning policy for such future specifications could simply reflect the JCP specification version. This might result in a change of major version of a javax package even when the new version is compatible with the old. For example, the Java Persistence API (JPA) 2.0 is compatible with the earlier version JPA 1.0. You might expect the javax.persistence package version to follow the JCP specification name and use version 2.0. However, it actually follows OSGi versioning policy and uses version 1.1.

    Because JCP specifications always try to maintain compatibility with earlier versions, you should specify only the minimum package version for a javax.* package and leave the upper boundary open. For example, suppose that a future version of WebSphere® Application Server has a default JPA provider that implements a version of JPA later than Version 2.0. In this case, the application server can export the javax.persistence package at that later version and still be resolved by applications that are written to work with JPA 1.0 or 2.0. Similarly, the following example import statement can resolve against any version of the javax.persistence package at 1.0 or higher:
    Import-Package: javax.persistence;version="1.0"