Content for  TS 29.501  Word version:  18.4.0

API version numbers shall consist of at least 3 fields, following a MAJOR.MINOR.PATCH pattern according to the Semantic Versioning Specification [17]. The 1st Field (MAJOR), the 2nd Field (MINOR), and the 3rd Field (PATCH) shall contain unsigned integer numbers, and they shall not contain leading zeroes. An additional field (called "pre-release version" in Semantic Versioning Specification [17]) is added to denote an OpenAPI version under development, i.e. prior to the freeze of the corresponding OpenAPI description for a given 3GPP Release. This additional field is appended after the 3 first version fields using the hyphen "-" character and shall have the format "alpha.n", where "n" is an unsigned integer number without leading zeroes. After the freeze of a 3GPP Release, additional fields (called "build metadata" in Semantic Versioning Specification [17]), containing operator-specific version information, may be appended after the 3 first version fields using the plus sign "+" character and they shall consist of a list of dot-separated identifiers, where each identifier may contain only alphanumeric characters and hyphens ([0-9A-Za-z-]). EXAMPLES:

The first version of a new API under development shall obtain the version number "1.0.0-alpha.1". At the first publication of the 3GPP Technical Specification defining the API after the OpenAPI freeze of the first 3GPP Release that contains the API, the version number of the API shall be set to "1.0.0". When a new version of the 3GPP TS containing OpenAPI file(s) is published, the fields of the corresponding API version number(s) shall be incremented according to the following rules:

• The 1st Field (MAJOR) shall be incremented only if the applied change is backward incompatible relative to the earlier, i.e. frozen version of the given OpenAPI (see the details below). For a non-frozen OpenAPI, the first backwards incompatible change relative to the latest frozen version triggers incrementing the 1st Field (MAJOR), while subsequent backwards incompatible changes do not increment the value, until the OpenAPI stays non-frozen. When the 1st Field (MAJOR) is incremented, this impacts the lower level fields as follows:
  • The 2nd Field (MINOR) shall be reset to "0";
  • The 3rd Field (PATCH) shall be reset to "0";
  • The 4th Field (NON-FROZEN), if present shall be reset to "alpha.1" (this field is removed when the OpenAPI freezes).
  The 2nd Field (MINOR) shall be incrementd only if the applied change is a backward compatible new feature relative to the earlier, i.e. frozen version of the given OpenAPI (see the details below). For a non-frozen OpenAPI, the first backwards compatible change relative to the latest frozen version triggers incrementing the 2nd Field (MINOR), while subsequent backwards incompatible changes do not increment the value, until the OpenAPI stays non-frozen. When the 2nd Field (MINOR) is incremented, this impacts the lower level fields as follows:
  • The 3rd Field (PATCH) shall be reset to "0";
  • The 4th Field (NON-FROZEN), if present shall be reset to "alpha.1" (this field is removed when the OpenAPI freezes).
  The 3rd Field (PATCH) shall be incrementd only if the applied change is a backward compatible correction relative to the earlier, i.e. frozen version of the given OpenAPI (see the details below). For a non-frozen OpenAPI, the first backwards compatible change relative to the latest frozen version triggers incrementing the 3rd Field (PATCH), while subsequent backwards incompatible changes do not increment the value, until the OpenAPI stays non-frozen. When the 3rd Field (PATCH) is incremented, this impacts the lower level field as follows:
  • The 4th Field (NON-FROZEN), if present shall be reset to "alpha.1" (this field is removed when the OpenAPI freezes).
• The 4th Field (NON-FROZEN), if present shall be incremented in a non-frozen OpenAPI every time any kind of changes are applied the given non-frozen OpenAPI (see the details below). This field is removed when the OpenAPI freezes.

• This numerical field shall be incremented when:
  1. there are one or more backward incompatible changes to the API after the OpenAPI freeze for a given 3GPP Release; and
  2. there are the first backward incompatible change(s) to the existing API with respect to the latest version in the previous 3GPP Release while a 3GPP Release is under development (i.e. prior to the OpenAPI freeze for a given 3GPP Release).
  EXAMPLE 1:
  Assuming that 3GPP Rel-16 under development contains API version "1.1.0-alpha.2", and a backward incompatible change with respect to the latest version in the previous 3GPP Release is applied to that API before the OpenAPI freeze, the new Rel-16 API version is "2.0.0-alpha.1".
• If a backward incompatible change needs to be applied to several 3GPP Releases the following applies:
  1. If the 3GPP Releases contain different MAJOR versions of the same API, a new MAJOR API version shall be assigned to each 3GPP Release in the order of those 3GPP Releases in such a manner that the lowest of those 3GPP Releases shall obtain the first unassigned MAJOR version value.
     EXAMPLE 2:
     Assuming that 3GPP Rel-15 contains API version "1.0.0", and Rel-16 contains API version "2.0.0", and that the same backward incompatible change is applied to that API in both Releases, the new Rel-15 API version is "3.0.0" and the new Rel-16 API version is "4.0.0".
  2. If the 3GPP Releases contain the same MAJOR version but different MINOR versions of the same API, a single new MAJOR API version value shall be assigned for all those 3GPP Releases, unless other backward incompatible changes only applied to some of those Releases require the creation of separate MAJOR versions.
     EXAMPLE 3:
     Assuming that 3GPP Rel-15 and Rel-16 contain API version "1.0.0", and Rel-17 contains API version "1.2.0", and that the same backward incompatible change is applied to that API in all 3GPP Releases, the new 3GPP Rel-15 and Rel-16 API version is "2.0.0" and the new 3GPP Rel-17 API version is "2.2.0".
  3. If the 3GPP Releases contain the same API versions, a single new API version shall be assigned for all those 3GPP Releases, unless other changes only applied to some of those Releases require the creation of separate versions.
  EXAMPLE 4:
  Assuming that 3GPP Rel-15 and 3GPP Rel-16 contain API version "1.0.0", and that only the same backward incompatible change is applied to that API in both 3GPP Releases, the new 3GPP Rel-15 and Rel-16 API version is "2.0.0".
  EXAMPLE 5:
  Assuming that 3GPP Rel-15 and Rel-16 contain API version "1.0.0", and that the same backward incompatible change is applied to that API in both Releases and an additional backward compatible change is applied in 3GPP Rel-16, the new 3GPP Rel-15 API version is "2.0.0", and the 3GPP Rel-16 API version is "2.1.0".
  EXAMPLE 6:
  Assuming that 3GPP Rel-15 and Rel-16 contain API version "1.0.0", and that the same backward incompatible change is applied to that API in both Releases and an additional backward incompatible change is applied in 3GPP Rel-16, the new 3GPP Rel-15 API version is "2.0.0", and the 3GPP Rel-16 API version is "3.0.0".

• This numerical field shall be incremented when:
  1. there are the first one or more backward compatible changes not corresponding to changes to earlier 3GPP Releases (i.e. changes introduced by 3GPP CR with other categories than "mirror") to the same API in a given 3GPP Release without any prior backward incompatible changes in that Release. If the same 1st field (MAJOR) and the 2nd field (MINOR) are assigned to n previous 3GPP Releases, a MINOR version number shall be reserved for each intermediate 3GPP Release for possible subsequent changes in that Release and the MINOR version number shall be incremented by n; and
     EXAMPLE 7:
     Assuming that 3GPP Rel-15 and Rel-16 contain API version "1.0.0" (because there were no changes to the API in Rel-16), and in Rel-17 the first backward compatible new feature is added before the OpenAPI freeze, the API version "1.2.0-alpha.1" is assigned to Rel-17.
  2. there are one or more subsequent backward compatible additions of features not corresponding to changes to previous 3GPP Releases to the API in a frozen 3GPP Release before a higher MINOR number has been allocated for the same MAJOR version (for a subsequent Release).
• This field shall be reset to "0" if the 1st field (MAJOR) is changed, unless a backward incompatible change needs to be applied to several 3GPP Releases that already contain the same MAJOR but different MINOR API versions. In that case a single new major API version is assigned, and for each such 3GPP Release with an own MINOR version, a new MINOR version shall be assigned, starting with MINOR version "0" for the lowest such Release, and reserving a MINOR version number for each intermediate Release without an own MINOR version. (see Example 3)
  EXAMPLE 8:
  Assuming that an API was introduced with version "1.0.0" in Rel-15, and that the Rel-16 version is "1.1.0-alpha.5" because the OpenAPI is not yet frozen in Rel-16, and that a new backward compatible Rel-17 feature is added, the Rel-17 API version is "1.2.0-alpha.1".

• This numerical field shall be incremented:
  1. if the changes are only one or more backward-compatible corrections (but no changes requiring an update of the 1st field (MAJOR) or of the 2nd field (MINOR) are made to the API after the OpenAPI freeze of a 3GPP Release; and
  2. if one or more backward compatible additions of features, but no changes requiring an update of the 1st field (MAJOR) or of the 2nd field (MINOR), are made to the API after the OpenAPI freeze of a 3GPP Release and after the assignment of a MINOR version to a higher 3GPP Release.
• This field shall be reset to "0" if the 1st field (MAJOR) or 2nd field (MINOR) is changed.

• The 4th Fields may or may not be present, based on the following conditions.
• NON-FROZEN type. The presence of this filed type depends on the OpenAPI status, as follows:
  • The 4th Field (NON-FROZEN) shall be present before the OpenAPI freeze of a 3GPP Release. An additional field (separated from the 3 first version fields by a hyphen "-" character) shall be supplied as follows:
    1. When the 1st field (MAJOR) or 2nd field (MINOR) is incremented before the OpenAPI freeze of a 3GPP Release, this field shall obtain the value "alpha.1".
    2. The numerical value "n" within the field value "alpha.n" shall be incremented if one or more subsequent changes (either backward incompatible, or backward compatible) are made to the given non-frozen OpenAPI.
  • The 4th Field (NON-FROZEN) shall not be present after the OpenAPI freeze of a 3GPP Release, this additional field (including the hyphen "-" character) containing pre-release version info is removed from the API version.
• OPERATOR-SPECIFIC type that represents operator-specific version field(s) . The presence of these fields depends on the OpenAPI status, and the operator preferences:
  • The 4th Field (OPERATOR-SPECIFIC) shall be present after the OpenAPI freeze of a 3GPP Release. Additional fields may be supplied based on operator policy after the 3 first version fields and separated by a plus sign "+" character. The rules for setting, or incrementing, such fields are out of the scope of 3GPP, but they shall comply with the rules described in the Semantic Versioning Specification [17], and contain a list of dot-separated labels within the allowed character set ([0-9A-Za-z-]).

If no change is applied to an API in a new published TS version, the API version number shall not be incremented unless the additional field ("-alpha.n") needs to be removed at OpenAPI freeze. This also applies if the TS is published in a new 3GPP Release.

The API version shall be indicated in the resource URI of every API, as described in clause 4.4.1. The API version shall be indicated as the concatenation of the letter "v" and the 1st field (MAJOR) of the API version number. The other fields shall not be included in the resource URI. The full API version number (i.e., containing all the fields) shall be visible in the OpenAPI specifications, in the "version" subfield of the "info" field, as described in clause 5.3.3.

There is no one-to-one mapping between an API version number and the version number of the 3GPP Technical Specification defining this API. A 3GPP Technical Specification specifies one or more APIs, which may have different versions. A change in the 3rd field (PATCH) of a 3GPP TS version number (i.e. an editorial change) should not lead to a change in the version number of the APIs specified in the 3GPP TS. A change in the 1st field (MAJOR) and 2nd fields (MINOR) of the 3GPP TS version number is likely to lead to at least a change in the minor version number of the APIs specified in the 3GPP TS. EXAMPLE: The 3GPP TS defining the API is indicated in the OpenAPI specification of the API, as described in clause 5.3.4.

The NF service consumer may discover the API version(s) supported by an NF service producer using the following mechanisms:

• NRF query: The NF service consumer may retrieve from the NRF the NF profile of a given NF Instance. This NF profile contains the full version number(s) of the API(s) supported by an NF Service Instance, as described in the clause 6.2.6.2.4 of TS 29.510 and the planned retirement date.
• NF profile change notifications: The NF service consumer may subscribe for NF status change notifications with the NRF as specified in clause 5.2.2.5 of TS 29.510. The NRF shall notify as specified in clause 5.2.2.6 of TS 29.510, any change to the NF profile which may include updated NF service profile containing the current list of NF services and their versions supported by the NF.

When a new major version is created, the NF service producer shall continue supporting at least the previous major version until a retirement date unless all API versions (except for draft API versions published prior to the OpenAPI freeze) with that previous major version are withdrawn (see clause 4.3.1.6); this enables NF service consumers to migrate to the new version. After expiration of the retirement date, the old major version should be deprecated. The retirement date of an old major version supported by a NF service instance may be updated in the NF profile in the NRF.

If it is discovered that one or several previous API versions are not providing the basic mandatory functionality of an API due to severe functional or encoding deficits (for instance, there is no or very limited interoperability between the NF service consumer and NF service producer when such an API version is used, or the API is hardly implementable because of severe deficits in the OpenAPI file that cannot easily be fixed by implementers in an interoperable manner), those API versions shall be listed as withdrawn in subsequent versions of the TS defining the corresponding API; any withdrawn API versions from the same or previous 3GPP releases shall be listed. API versions published before the OpenAPI freeze of the corresponding 3GPP Release, i.e. with a 4th Field (NON-FROZEN and/or OPERATOR-SPECIFIC) as part of the version number, shall not be withdrawn. Withdrawn API versions should not be deployed.