Simple Schema Types
The eBay Schema makes use of many simple schema types.
| Data Type | Description |
|---|---|
| anyURI | Specifies a Uniform Resource Identifier (URI), a compact sequence of characters that identifies an abstract or physical resource.
The anyURI type is used most often to specify Uniform Resource Locators (URLs), such as a web page URL (e.g., ViewItemURL) or a file location URL (e.g., PictureURL), but can also be used for email addresses and other valid URI schemes. |
| boolean | Specifies binary-valued logic (true/false). Possible input values are true, false, 1, and 0. Possible output values are true and false only (not 1 or 0). |
| dateTime | A specific instant of time.
Date-time values are in the ISO 8601 date and time format. Hours are in 24-hour format (e.g., 2:00:00pm is 14:00:00). Unless otherwise specified, all date-time values are recorded in Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT) or Zulu (because the time portion of the time stamp ends with a Z). That is, time values do not reflect the time zone shown on the eBay Web site. Here is an example of the date-time format: YYYY-MM-DDTHH:MM:SS.SSSZ (e.g., 2004-08-04T19:09:02.768Z) See Time Values for information about how to convert between local time zones and GMT. We use the dateTime data type to convey start and end times, the official eBay time, and other time values. |
| decimal | A decimal value of arbitrary precision.
In the API, most fields of type decimal can contain the digits 0-9, a hyphen to designate negative numbers as needed, and a period (".") for the decimal separator. Decimal values should never include a thousands separator. A whole number (i.e., without a period) can be passed as a decimal value. We typically use the decimal data type to convey values related to units of measure. See individual topics for specific restrictions beyond this for fields of type decimal. |
| double | A double-precision 64-bit floating point type.
In the API, most fields of type double can contain the digits 0-9, a hyphen to designate negative numbers as needed, and a period (".") for the decimal separator. Double values should never include a thousands separator. We typically use the double data type to convey values related to monetary amounts. In some cases, a whole number (i.e., without a period) can be passed or returned as a double value. See individual topics for specific restrictions beyond this for fields of type double. |
| duration | A length of time.
Duration values are in the ISO 8601 duration format, where P represents "Period", nY represents the number of years, nM the number of months, nD the number of days, T is the date/time separator, nH the number of hours, nM the number of minutes, and nS the number of seconds. So P2DT23H32M51S means "A period of 2 days, 23 hours, 32 minutes, and 51 seconds". PnYnMnDTnH nMnS (e.g., P2DT23H32M51S) We use the duration data type to convey values like the time left until a listing ends. For ended listings, the time left is P0DT0H0M0S (zero days, zero hours, zero minutes, and zero seconds). |
| float | A single-precision 32-bit floating point type.
In the API, most fields of type float can contain the digits 0-9, a hyphen to designate negative numbers as needed, and a period (".") for the decimal separator. Float values should never include a thousands separator. We typically use the float data type to convey values related to percentages. See individual topics for specific restrictions beyond this for fields of type float. |
| int | A 32-bit integer value between -2147483648 and 2147483647.
In the API, most fields of type int can contain digits 0-9, and hyphen to indicate negative numbers. Some input fields restrict the input to particular values or a range of values. These cases are noted in the associated topic for the specific input field. We typically use the int data type for enumerations, counts (e.g., how many items are returned), quantities, certain kinds of IDs (other IDs are strings), and similar concepts. |
| long | A value between -9223372036854775808 and 9223372036854775807. |
| map | An associative array. |
| number | This data type specifies a signed (i.e., positive or negative) decimal value (e.g., "5" or "33.99" or "3.14159" or "-0.23"). The number type may be used for double or float values, such as values to indicate amounts of money, such as prices, fees, costs, and payments. |
| positiveInteger | An integer value greater than or equal to 1. |
| string | A string of characters. All characters in the Unicode character set are supported.
Character entity references are used for escaping markup-significant characters. For example, use & for the & (ampersand) character, < for the < (less-than sign) character, and > for the > (greater-than sign) character. It is a good idea to escape such characters in requests instead of using a CDATA construct. Responses from eBay do not include CDATA constructs. |
| token | A string with normalized whitespace (e.g., dropped leading and trailing spaces).
eBay typically uses the token type to constrain a field to a specific set of string values. These values are often defined in a separate enumerated type, even though the field itself is not defined as that enumerated type, and the field might not be limited to the values defined by the enum. eBay uses token instead of an enumerated type when the accepted or allowed values are volatile or are likely to vary by use case. The documentation often defines the allowed token values, such as when they are based on an enumeration type in the schema. In some cases, you can also use a metadata call to look up the allowed values for a token field. In all cases, your application should handle unexpected token values in a graceful manner. |
Repeatable (Unbounded) Fields
If the multiplicity of an element is defined as maxOccurs="unbounded" or a value greater than 1 in the schema, it means you can specify the field multiple times in a request (like you are specifying an array), or eBay can return the field multiple times in the response. In this case, the fields must be contiguous. That is, in a request, you cannot insert other fields between the repeating fields. Otherwise, some of the data will be dropped in an unpredictable manner.
For example, findItemsByKeywords can return multiple items. Here is the definition of the item element in the searchResult schema (SearchResult complexType):
<xs:element name="item" minOccurs="0" maxOccurs="unbounded" type="tns:SearchItem">
In the response, the item fields are always contiguous, with no other fields between them:
...
<searchResult count="100">
<item>
<itemId>1**********5</itemId>
...
</item>
<item>
<itemId>3**********1</itemId>
...
</item>
<item>
<itemId>3**********8</itemId>
...
</item>
...
</searchResult>
...
If you are using URL-style input or Name-Value Pair input, repeatable fields can be expressed with a comma-separated format in most cases.
Multiplicity Notation
| Sample XML notation | Corresponding doc notation | Meaning § |
|---|---|---|
| minOccurs="0" maxOccurs="unbounded" | [0..*] | Zero or more |
| minOccurs="0" | [0..1] | Zero or one |
| minOccurs="0" maxOccurs="1" | [0..1] | Zero or one |
| minOccurs="0" maxOccurs="6" | [0..6] | Zero to six |
§ While this is the general meaning, be sure to read the description of the particular field: it may state an exception for a particular use.