This topic describes eBay's versioning strategy, which enables us to evolve the schema while maintaining backward compatibility for at least 18 months. This strategy is intended to address these concerns:

eBay adds new features every two weeks. If you update your client software less frequently, your software needs a way to handle unrecognized data from eBay.
Over time, it becomes more difficult for eBay to support third-party software that is using outdated business logic or features. eBay needs a way to eventually drop support for outdated features.
We understand that it may be difficult for you to update your software on short notice. To help you, eBay needs to maintain support for outdated features for some period of time, and we need to give you as much notice as possible before we completely stop supporting a feature.

In each release, we do our best to update the schema in a backward-compatible way. However, sometimes we need to make changes that aren't backward compatible:

As XML schema constructs are typed, any modification that would result in a type change is a potential incompatibility. As a very simple example, we might currently express a measurement or a count in integer values (xs:int), but in a future enhancement we might need a way to allow decimal fractions for the same value (xs:double). If your application is expecting a field to return an integer at runtime and we start returning a double instead, your application could fail. So, we need a way to avoid changing the type directly.
Changing the multiplicity of an element is also a potential incompatibility. For example, we might currently allow a single URL field, but in a future enhancement we might allow repeating URL fields (maxOccurs="unbounded"). As some toolkits interpret repeating fields as arrays, this would be equivalent to a type change.

When such changes are necessary, we need a way to gracefully phase in the new approach and gracefully phase out the old one. (That is, we need to make changes without causing third-party applications to fail unexpectedly, and applications need to be designed to accommodate routine changes.) This approach is described below.

Note: This versioning strategy replaces our old (legacy XML API) compatibility level convention.

Basic Schema Concepts
Versioning Strategy Key Points
eBay's Version Support Schedule
Schema Changes That Affect Compatibility
Object Deprecation Example
Logical Changes That Affect Compatibility
Schema Versions and Requirements for Compatible Application Check
Upgrading Applications to Support New Versions

Also see:

Version-Dependent Logical Changes
Object Deprecation Schedule

Basic Schema Concepts

Before reading this document, you should be familiar with these basic concepts.

Concept	Description
object	eBay's schema consists of these basic building blocks: API calls Types Element within types Attributes within types Values within enumerated types (code types) We call all these building blocks objects. (API calls are expressed as request and response types, but the entire call can be thought of as an object for versioning purposes.) All of these objects are subject to the usage policies described in this document.
schema version	eBay releases new features and functional changes to US sites (e.g., ebay.com) every two weeks. At the same time, we also release an updated version of the schema. All schema versions are numbered (497, 499, 551, and so forth). The versions are always odd numbers. In general, we release the same code to international sites (e.g., ebay.co.uk) about a week after the US release. (We use the same version of the schema for both US and international releases.) The Release Notes list all schema versions and their US release dates, as well as the changes that were made in each release.
request version	With each API request, you specify the version of the schema your client software is using. The request version helps eBay determine which objects and business logic we should use to process the request. The version can also affect the response schema, because when we have replaced an object, we check the request version to decide whether to return the old object. See Schema Changes That Affect Compatibility below. Note: The request version was previously also called the compatibility level.

Versioning Strategy Key Points

This section summarizes key points you should understand about our versioning strategy. These points are explained in more detail in later sections.

Object Deprecation and Deletion:
A deprecated object is an object that we no longer recommend. The schema version when this deprecation occurs is the object's deprecation version. For example, if we deprecate an object called "Flavor" in version 503 of the schema, then the deprecation version for that object is 503.

As of February 2007 (version 499), whenever we deprecate an object, we also delete the object from the latest schema at the same time (unless otherwise noted). Your application(s) should not be affected by these deletions until you upgrade to a newer version of the schema. (See the object deprecation schedule for a list of previously deprecated objects that have been deleted from the schema.)

We control a deprecated object's usage based on the request version:
- If it's an input object, you may only receive a warning (regardless of the request version).
- If it's an output object, we only return it with request versions that are lower than the deprecation version (unless otherwise noted). See Object Deprecation Example below for an example of how this works.
- If it was deprecated earlier than the lowest supported version (see below), it will no longer work.
See Deprecation of Existing Objects for more details.
Lowest Supported Version:
As of August 2007, we will increment the lowest supported version every 6 months. The lowest supported version will be 18 months old. See eBay's Version Support Schedule.

Objects that were deprecated in unsupported versions (more than 18 months old) will no longer work.

eBay's Version Support Schedule

In February and August of each year, eBay increments the lowest supported schema version.

The table below shows eBay's schema version support schedule. The row with bold text indicates the current lowest supported version. Rows with gray text indicate future versions that are not yet published or past versions that are no longer supported.

Version Support Schedule (Projected)

Schema Version	Lowest Supported Version as of
415	June 2006
447	August 2007
473	February 2008
499	August 2008
525	February 2009
551	August 2009
577	February 2010
603	August 2010

Here's how this schedule will affect you:

If your application is using a version lower than the lowest supported version, you should upgrade your software to use a supported version. You are encouraged to use the latest version available.
If you are creating a new application, you are required to use the latest version available.

Important: Once a schema version is no longer supported, objects that were deprecated as of that version (or earlier) are not supported, regardless of the request version.

Note: By "not supported", we mean that the deprecated object will no longer work, and eBay will not address issues you report related to the deprecated object (or functionality).

Applications that still depend on unsupported objects do so at their own risk. If you use unsupported objects, your application may encounter severe errors.

Here's an example of how to interpret the table:

As of February 2008 the lowest supported version is 473.
In August 2008, we will increment the lowest supported version to 499.
The change to the lowest supported version should only affect existing applications about every 18 months, as long as you upgrade to a recent version at that time. For example, if you upgrade to a fairly new version like 573 by August 2008, you should be able to use 573 for about 18 months until February 2010 (when the lowest supported version moves to 577).

Note: In rare cases when it becomes necessary, eBay reserves the right to drop support for an object immediately. This could be due to a sudden business development or to an unanticipated design issue.

In these cases, we may provide you with only limited notice of deprecation, and we may drop support for the object right away. This helps you avoid undesirable adoption of unusable features. When we have needed to do this in the past, it has occurred within a release or two of the object's initial appearance.

Schema Changes That Affect Compatibility

eBay makes three basic kinds of changes to the schema:

We add new objects.
We deprecate existing objects.
We replace existing objects or change their type.

In many cases, these changes will not affect your application until you upgrade to a newer schema. The effects can depend on whether your application happens to use the functionality that has changed, and the version of the schema you are using.

We do our best to keep you informed of schema changes through the schema documentation, release notes, the eBay Developers Program weblog and newsletter, system announcements, and other mechanisms.

Addition of New Objects

We can introduce new objects at any time and at any level of the schema.

Usually, the request version doesn't control your ability to use new elements or calls (unless otherwise noted). For example, new output elements are usually returned for all request versions. We add an xs:any element to the end of each type to express this openness. (Some toolkits fail parsing if we add new elements without doing this.) By policy we also try to add elements to the end of a type before the xs:any element. (This is only a policy; it's not a guarantee.)

Note: Our approach gives you the flexibility to adopt individual elements without updating your request version, if necessary. This can be useful when your application uses the same request version for all calls, but you only have the time or resources to adopt one particular feature.

However, the request version does control whether we return new code type values (enumerations) in responses. If your software is already using an element that is a code type, you need a safe way to handle new values that your software doesn't recognize yet. Therefore, we check your request version, and then in our response we map any newer code type values to a default value you can recognize (CustomCode) instead. (See Overview of the API Schema for more information about code types.)

For backward compatibility:

You should design your software to be able to handle or gracefully ignore extra elements that we add to the schema. For example, at any time, API calls may return new elements in addition those declared in the version of the schema you are using.
Your software should also be prepared to see and handle "CustomCode" (without quotes) for values that we have added to code types in versions that are newer than your current request version.

Deprecation of Existing Objects

As stated earlier, a deprecated object is an object that we no longer recommend (although we still support it). We do our best not to deprecate objects, but sometimes it becomes necessary to deprecate an object due to business, legal, or functional issues. The schema version when this deprecation occurs is the object's deprecation version.

As of February 2007 (version 499):

When we deprecate an object, we will delete it from the schema at the same time. (If your application already uses the object, you should not be affected until you upgrade to the deprecation version or higher.)
When we increment the lowest supported schema version, we will drop support for all objects that were deprecated in lower versions. See eBay's Version Support Schedule.

Note: Your application should not be affected by newly deleted objects as long as you are using good coding practices. For example, you should not hard-code a check for, say, "the 20th element" in the response.

For backward compatibility, how you use a deprecated object depends on whether the object is in the request (input) or the response (output). The policy in the table below assumes that the deprecation version and your request version are both supported (i.e., greater than the lowest supported version).

See Object Deprecation Example for a concrete example, including a diagram.

Context	Description
Input	You can still pass in the deprecated object (unless otherwise noted). You may receive a warning in the response. If the deprecated object has been replaced and you supply both objects in the request, the new object is given precedence (the deprecated object is ignored).
Output	If the request version is less than (<) the deprecation version: The deprecated object is still returned. If a new object has replaced the deprecated object, the new object is also returned. If the request version is greater than or equal to (≥) the deprecation version: The deprecated object is no longer returned. If a new object has replaced the deprecated object, the new object is returned.

Context

Description

Input

You can still pass in the deprecated object (unless otherwise noted). You may receive a warning in the response.

If the deprecated object has been replaced and you supply both objects in the request, the new object is given precedence (the deprecated object is ignored).

Output

If the request version is less than (<) the deprecation version:

The deprecated object is still returned.
If a new object has replaced the deprecated object, the new object is also returned.

If the request version is greater than or equal to (≥) the deprecation version:

The deprecated object is no longer returned.
If a new object has replaced the deprecated object, the new object is returned.

When testing a call, you can set WarningLevel to High to identify whether you are using deprecated objects in your request.

Replacements and Type Changes

We sometimes need to effectively change an existing object to a different type, or replace or rename an object. Rather than replacing an object directly, we usually use the addition and deprecation approaches described above. That is, we add a new object with a different name and we deprecate the old object.

For backward compatibility:

Treat the new object like any other new object. It will be available regardless of the request version (unless otherwise noted). See Addition of New Objects above.
Treat the old object like any other deprecated object. See Deprecation of Existing Objects above.

Client software that depends on the old object should start using (or expecting) the new one as soon as possible. This is particularly important if the old object reflects functionality that is inconsistent with current eBay site logic. Otherwise, your application's users may see unexpected (and undesirable) behavior.

In some cases, we may change an existing object's behavior without replacing it. See Logical Changes That Affect Compatibility for an example. Again, we do our best to minimize these kinds of changes.

Object Deprecation Example

Let's suppose eBay offers a new "flavor" feature, and then later enhances the feature in a way that isn't backward compatible.

This is how the schema and the object's usage might change in this case:

Version	Release Date	Event
483	October 2006	eBay adds a Flavor element of type FlavorType to ItemType. Flavor is fully supported.
503	March 2007	eBay starts allowing multiple flavors, and therefore needs to replace Flavor with a repeating NewFlavor element of type NewFlavorType. In schema version 503, Flavor is deprecated and it is deleted from ItemType. On input, you can specify either Flavor or NewFlavor. (NewFlavor takes precedence if both are specified.) On output, Flavor is only returned for request versions lower than 503. (NewFlavor is returned for all request versions.) Note: If you are using SOAP (or the SDK) and you have coded against compiled language objects generated by the schema, you would no longer be able to reference a compiled Flavor object, because Flavor is deleted from the WSDL file as of version 503. So you would need to use NewFlavor for input and output when you upgrade to version 503 or higher.
525	August 2007	This is a milestone version. The lowest supported version moves up to 447. Flavor is still supported, because version 503 is still supported.
551	February 2008	This is a milestone version. The lowest supported version moves up to 473. Flavor is still supported, because version 503 is still supported.
577	August 2008	This is a milestone version. The lowest supported version moves up to 499. Flavor is still supported, because version 503 is still supported.
603	February 2009	This is a milestone version. The lowest supported version moves up to 525. Now eBay drops all support for Flavor, because version 503 is no longer supported. Applications that are still using the deprecated Flavor object could break if they depend on the flavor functionality.

Logical Changes That Affect Compatibility

Incompatible changes can be logical or functional; not necessarily changes to the schema itself. As with deprecated objects, we implement these kinds of changes based on the version whenever possible.

For example, suppose a call returns a node called ManyDetails:

In version 483, we always return ManyDetails.
In version 503, we add a new IncludeManyDetails field to the request, and we set the default to false (so that ManyDetails is only returned when you specifically ask for it).

In this example, we are not deprecating ManyDetails or changing the schema in any way, but this change would break any application that specifically looks for ManyDetails and expects it to be returned by default. Therefore, we would implement this change so that only clients specifying request version 503 or higher would see the new behavior.

See the Version-Dependent Logical Changes table for a summary of objects that behave differently based on the request version.

Schema Versions and Requirements for Compatible Application Check

To comply with eBay's requirements for Compatible Application Check, new applications must use the latest version that is available in the Production environment at the time of Compatible Application Check.

For example, suppose your application had a Compatible Application Check at version 525. If version 555 is the latest version available in production, then you can still use version 525 or higher.

On the other hand, suppose you submit a new request for a Compatible Application Check. If version 555 is the latest version available in production, you would need to use the latest version (555 in this example).

We increment the lowest supported version periodically. Make sure you understand how your application will be affected by these changes (see eBay's Version Support Schedule). Plan to start adjusting your application to use the latest version before we drop support for the version you are using. (You do not necessarily need to redo a Compatible Application Check for your application if you are only upgrading it to a newer version.)

Upgrading Applications to Support New Versions

At a high level, we suggest you follow this process when you upgrade an application to a newer version of the schema:

Make sure the application uses no invalid objects or functionality. For example:
- For each call, remove dependencies on objects that have been deprecated for the version you are upgrading to.
- For each call, make sure the request only includes applicable and valid fields. For example, certain fields that are valid in AddItem calls may be invalid in ReviseItem calls.
Use the Sandbox to test your application's compatibility with the new version.
- Make sure that all requests trigger no warnings or errors.
- Set WarningLevel to High to make sure no schema warnings are returned.

FAQs

What is a Compatibility Level?

With the legacy XML API (obsolete as of 2005), we used a mechanism called a "compatibility level" to shield applications from backward-incompatible changes.

The old compatibility level mechanism is not applicable to the schema, so we have replaced the old mechanism with the versioning strategy described above.

You may still see the term "compatibility level" used instead of "request version" in the Forums, KB articles, older documentation, and other resources. Also, for XML API users, the historical name of the X-EBAY-API-COMPATIBILITY-LEVEL header has not changed, but now you use it to specify your request version instead.

eBay Trading API Schema Versioning Strategy