Data validation

When you work with a traditional API, it is important to understand the rules eBay uses for validating input fields and when fields are returned in a given call's response.

Predefined values

Some types have a predefined list (enumeration) of valid input and output values. To help you reduce errors due to invalid input data, the schema provides you with the valid values. These values are defined in code lists. For example, ListingDuration is a code list that specifies all the valid listing durations on eBay for different listing types. If a type uses a code list, only the values in that list can be passed in to a request payload, and they must be spelled in the same way as they are spelled in that list. For more information, refer to Code Lists.

Call relevance

Some fields (e.g., TimeLeft,) are relevant only when an Item is returned in a GetItem response and are invalid or ignored when an Item is passed in an AddItem request. In many cases, a field or value that is not relevant to a call is ignored if it is passed in. However, if passing a particular value or field would cause the intent of the request to become ambiguous or inconsistent, the call will return an error. For example, if both flat-rate shipping fields and calculated-rate shipping fields are passed in when listing an item, the call will fail.

Required/optional fields

As a general convention, all elements in the schema are defined with a multiplicity of minOccurs="0". This does not necessarily mean the field is optional in a call you are using.

The schema uses this convention for few reasons:

• The same types can be shared across multiple calls, but some elements defined on those types might not be shared. For example, Item.Country is a required input for AddItem but it is not relevant to the response of a GetSellerEvents call. Since both of these calls share the same basic Item object, the Item.Country element's multiplicity value must be set to minOccurs="0" in the schema so that Item can be used in both cases.
• The same field can be required in one use case and optional in another, even within the same call. For example, in AddItem calls, the Item.Title field is required as input in most cases, but it is optional if using a feature that "pre-fills" the title. Therefore, the Item.Title element's multiplicity value must be set to minOccurs="0" in the schema to account for the "pre-filling" use case.
• Future eBay enhancements can change a required field to optional. For example, Item.Location used to be required in AddItem calls. But when the Item.PostalCode field was added to support a new search feature, the Location field became optional. Therefore, to "future-proof" the schema against such logical changes, eBay typically defines fields as minOccurs="0" in the schema even when the field is currently required.

To determine whether or not a field is required in a particular context refer to the eBay Trading API Reference.

If any required fields are omitted when issuing a call, the request will fail and return errors. Refer to Error handling for additional information.

Repeating (unbounded) fields

If the multiplicity value for an element is defined as maxOccurs="unbounded" or any value greater than 1 in the schema, it indicates that the element can be specified multiple times in the request, such as when specifying an array. However, when doing so, these fields must be contiguous. That is, other fields cannot be inserted between these repeating fields. Doing so will result in some of the data's being dropped in an unpredictable manner.

Length restrictions

All string input fields that do not use predefined values (e.g., enums,) have length restrictions. For these arguments, the documentation specifies the maximum permitted length in characters.

For string fields that use predefined values (e.g., enums,) the maximum length is sometimes, but not always, specified in the documentation.

Fields of other types (e.g., integers,) may have constraints such as minimum or maximum values specified, where applicable, in the documentation.

Data types

The schema enforces the usage of correct data types. For example, if an element is defined as a double, a numeric value must be passed in. Refer to API data types for additional information.