eBay SDK for .NET
Attributes & Catalogs > Attribute and Product Finder Content Models > The Attribute Meta-Data Model 
 



< Back Next >

The Attribute Meta-Data Model

Before reading this section, you should be familiar with the basic definitions of attributes, characteristics, characteristic sets, and products as described in Working with Attribute-Based Features.

When you use GetAttributesCSCall and GetProductSellingPagesCall (or classes that implement the IAttributesXmlProvider interface) the attribute meta-data is returned as an XML string in the AttributeData and ProductSellingPagesData field, respectively. This enables you to use the Item Specifics SYI XSL stylesheet to render the meta-data.

If you are using the Item Specifics SYI XSL stylesheet as part of your solution, it may be helpful to focus on these topics of this section:

AttributeData Container Elements

ProductSellingPageData Container Element

CategoryMappingDetails Elements

CharacteristicsSet Elements

Attribute Elements

If you are not using the Item Specifics SYI XSL stylesheet, you should understand how the dependencies between different attributes are represented in the XML schema and how those dependencies affect the validation of attributes that you choose to include in a listing. Thus, you should read these topics:

AttributeData Container Elements

ProductSellingPageData Container Element

AttributeSet Elements

CategoryMappingDetails Elements

CharacteristicsSet Elements

Attribute Elements

Promotional (Promo) Message Elements

GlobalSettings Element

Important: eBay strongly recommends that you avoid directly modifying the XML returned from GetAttributesCSCall and GetProductSellingPagesCall, except where described in Working with the Item Specifics XSL Stylesheet. Any other direct changes to the XML documents returned from these attribute and product meta-data calls are not supported.

AttributeData Container Elements

The following figure illustrates the root container nodes that are returned in the AttributeData XML string when you execute GetAttributesCSCall. Table 23-1 describes the purpose of each container node. The ProductSellingPagesData XML string contains similar information.

Figure 23-1 High-Level View of the Item Specifics Model (GetAttributesCS)

Elements in the Item Specifics model can specify XML attributes (not to be confused with item attributes). In the table below, the XML attributes (e.g., id) are described in bulleted lists within the "Meaning/Notes" column.

Table 23-1 AttributeData Content
Element
Meaning/Notes
eBay.Attributes 
Contains a list of one or more AttributeSet nodes (see below).
eBay.Attributes.AttributeSet 
Contains information that identifies attributes and values that have been pre-selected by eBay. See AttributeSet Elements for details about the elements in this container.
In the GetAttributesCSCall response, these attributes indicate the default value(s) that you should display for each attribute when that attribute is first presented to the user. If no default values are specified, you typically display the first value (if any) in the attribute's value list.
In the GetProductSellingPagesCall response, this set contains attributes that are pre-filled. Some of these attributes might be editable (see Determining Whether the User Can Choose an Attribute Value).
  • id (integer): Identifier for the attribute set. Unique across all eBay sites.
eBay.Attributes.CategoryMappingDetails 
Contains a list of one more more categories for which eBay has defined pre-filled attributes. See CategoryMappingDetails Elements for details about the elements in this container.
eBay.Characteristics 
Contains a list of CharacteristicsSet nodes.
If you pass an AttributeSystemVersion value that is older than the current version of the meta-data on the site, all the characteristic sets that you requested that have changed since that version are returned.
If a characteristic set you requested has not changed since the specified version, its meta-data is not returned (i.e., the Characteristics node returns empty.)
eBay.Characteristics.CharacteristicsSet 
Contains one category's set of characteristics, promotional messages related to all the characteristics in the set, and presentation instructions for rendering the characteristics. See CharacteristicsSet Elements for details about the elements in this container.
  • id (integer): Identifier for the characteristic set. Unique across all eBay sites. Same ID as the AttributeSet.
  • order (integer): (May be returned, but it is not supported by the API)
  • type (string): Applicable for certain eBay sites only. If present, the value is "SiteWide". Indicates that this is a site-wide characteristic set (see Summary of the Attributes Model).
eBay.GlobalSettings 
Container for localized month formats. This node is always returned, even when no characteristic set meta-data is returned. See GlobalSettings Element for details about the elements in this container.

ProductSellingPageData Container Element

The following figures illustrate the root container nodes that are returned in the ProductSellingPageData XML string when you execute GetProductSellingPagesCall. Table 23-2 describes the purpose of each container node.

Figure 23-2 High-Level View of the Product Model (GetProductSellingPages)

Elements in the Pre-filled Item Information model can specify XML attributes (not to be confused with item attributes). In the table below, the XML attributes (e.g., id) are described in bulleted lists within the "Meaning/Notes" column.

Table 23-2 ProductSellingPageData Content
Element
Meaning/Notes
Products 
Container for the list of products whose Pre-filled Item Information should be included in item listings.
Products.Product 
Container for product information and attribute meta-data.
  • id (string): Unique identifier for the product. Your application should store the ID to use later for adding the item with Pre-filled Item Information.
...DataElements.DataElement 
An HTML snippet that specifies hints for the user, help links, help graphics, and other supplemental information that varies per characteristic set. Usage of this information is optional and may require developers to inspect the information to determine how it can be applied in an application. Formatted as CDATA (i.e., <![CDATA[...]]>)
...ProductInfo.DetailsURL 
Fully qualified URL for optional information about the product, such as a movie's description or film credits. This information is hosted through the eBay site and cannot be edited. Applications can include this URL as a link (e.g., in a Title & Description page) so that end users can view additional descriptive information about the product before choosing to include it in a listing.
...ProductInfo.StockPhotoURL 
Fully qualified URL for a standard image that is associated with the product. A user can choose to include the stock photo in the listing (see Define the Item). Not returned if no stock photo is available.
...ProductInfo.Title 
Title associated with the product. This value can be used as the basis for a suggested listing title. If the title is longer than 55 characters, your application should make sure the suggested title has a max length of 55 characters so that it will be valid for AddItemCall.
...Copyrights.Copyright.CopyrightContent 
Copyright statement indicating the source of the product information. This information will be included in the listing with Pre-filled Item Information. Your application should also display this information. If more than one copyright statement is applicable, they can be presented to the user in alphabetical order.
...Attributes 
Container node for a list of AttributeSet nodes, which identify default values that are pre-filled in the catalog for certain attributes. An attribute is a salient aspect or feature of an item. See AttributeSet Elements.
...Characteristics 
...GlobalSettings 

AttributeSet Elements

The AttributeSet node contains the list of Attribute nodes for which values have been pre-selected by eBay. In the context of GetAttributesCSCall, these can be treated as default values. In the context of GetProductSellingPagesCall, these attributes indicate pre-filled values that are read-only (Type 1) or conditionally selectable (Type 2). See Determining Whether the User Can Choose an Attribute Value.

Default values can also be associated with user-definable (Type 0) attributes. For example, if 80% of sellers always list 2 tickets, eBay could pre-select "2" as the default number of tickets, but the user would always be able to override this value.

In some cases, eBay also defines pre-filled values that vary according to the leaf category the seller selects. These are returned in the CategoryMappingDetails node. If such values are available, you can use them instead of the default values defined in the AttributeSet node. See CategoryMappingDetails Elements.

The AttributeSet node specifies the corresponding characteristic set name (e.g., "Tickets") and the attribute defaults, if any. Each attribute can have a label (SellingDisplayLabel) and a value (Value).

Note: When a user selects or enters data and then posts the data, your application can generate a revised XML file locally that specifies the attributes the user selected. If you are using the optional Item Specifics XSL, the user's selections and input can be placed in a new node (SelectedAttributes) that is not defined in the characteristic set XML document. See Working with the Item Specifics XSL Stylesheet for more information.

As described in Table 23-1, the AttributeSet node itself has one XML attribute: id (an integer), which specifies the constant, language-independent identifier for the attribute set (unique across all eBay sites).

The following figure illustrates the elements contained in the AttributeSet node. Table 23-3 describes the purpose of each element.

Figure 23-3 The AttributeSet Model

Elements in the Item Specifics and Pre-filled Item Information models can specify XML attributes (not to be confused with item attributes). In the table below, the XML attributes (e.g., id) are described in bulleted lists within the "Meaning/Notes" column.

Table 23-3 AttributeSet Content
Element
Data Type
Meaning/Notes
Attribute 
Container
Container node for attributes whose default values are pre-selected.
  • vivisible (boolean): If true (1), the attribute is initially visible.
  • count (integer): The quantity of values the attribute contains.
  • displaysequence (integer): The attribute's display order relative to other attributes in the set.
  • source (string): The data source of the attribute's value. Possible values:
  • 0 = Seller specifies value (either enumerated or entered in text field).
    1 = Value(s) pre-filled by catalog
    2 = Computed based on other values or user input
    3 = Value(s) pre-filled by eBay
    4 = Created by a Sell Your Item use case
    If the value of source is 1 or 3 and the value of Attribute.EditType is 1 or 2 (pre-filled), the attribute should be displayed as read-only.
Attribute.SellingDisplayLabel 
string
Display name for the attribute as shown on the Sell Your Item pages.
Attribute.Value 
Container
The default value selected for the attribute. A Value element may contain other elements (e.g., Name) or it may be an empty tag that only specifies an ID (e.g., <Value id="1001" />).
  • id (integer): Identifier for the value. Possible ID values:
  • -3 = Literal value (e.g., "Please choose State")
    -5 = Full date (day, month, and year)
    -6 = A value of "Other"
    -10 = -- (display a dash)
    ID = An ID that is unique within the characteristic set (e.g., 1001)
Attribute.Value.Day 
string
If present, the default (or pre-filled) day to present to the user (e.g., 01).
Attribute.Value.Month 
string
If present, the default (or pre-filled) month to present to the user (e.g., 04).
Attribute.Value.Name 
string
If present, the display name for the value. The content of the Name element can be CDATA (i.e., <![CDATA[...]]>.
Attribute.Value.Year 
string
If present, the default (or pre-filled) year to present to the user (e.g., 2004).
DomainName 
string
The well-known name of the characteristic set (e.g., "Tickets").

CategoryMappingDetails Elements

Important: The IncludeCategoryMappingDetails flag is not available in the version of the WSDL that is delivered with the eBay SDK for .NET. You can use this functionality by updating the GetAttributesCSRequestType class based on the latest version of the WSDL. For more information, see Using a WSDL to Update the SDK.

A CategoryMappingDetails node contains information active categories and, in some cases, old categories that are mapped to the active categories. For each mapping, it also contains information about attributes that can be auto-filled if the specified active or obsolete category is selected in the listing flow. This node is only returned when you specify IncludeCategoryMappingDetails in the GetAttributesCS request (and when the site supports this feature).

Note: You are not required to use this category mapping information. It is provided for applications that support sellers who want more control over their attribute selections.
Alternatively, you can pass Item.CategoryBasedAttributesPrefill and Item.CategoryMappingAllowed in the listing request and eBay will automatically auto-fill the same attributes for you based on the category specified in the request.

If you are using the Item Specifics SYI XSL Stylesheet to render an Item Specifics form, see Auto-filling Attribute Values Based on a Listing's Category for information on how to include auto-filled data when you initially render a form.

In some cases, the attributes are determined by the active category only. (An obsolete category might not be present in the mapping.) In this case, the attribute values may represent the most common selections, or they may represent values that are logically equivalent to a particular category. For example, if the category is DVD & Movies > VHS, eBay might return a Format attribute auto-filled with the value "VHS".

In other cases, the attribute values are determined by mappings between obsolete and active leaf categories. These are for cases in which the obsolete category has been combined with an active category. In this case, the attributes usually reflect the semantics of the obsolete category. For example, if the obsolete category represented a specific brand of bicycle (Cannondale), and the category is now mapped to a more generic active category (Road Bikes & Frames), eBay might return a Brand attribute with a value that reflects the old category's semantics (Cannondale). Using this information in a listing enables seller to maintain the differentiation that was previously provided by the old category. Auto-filled attributes for combined categories are primarily useful when revising or relisting an item whose category is no longer valid.

These category-based values vary according to the leaf category. That is, unlike the default values specified in AttributeSet Elements, these auto-filled attribute values are not applicable as defaults for all categories that are mapped to the same characteristic set.

Figure 23-4 shows an example of the way eBay might return category mappings with auto-filled attributes (Brand=Cannondale and Brand=Specialized) based on old leaf categories (Cannondale and Specialized).

Figure 23-4 Attributes Auto-filled Based on Old Categories

The old and new categories and the corresponding pre-filled attributes would be provided in the following mappings in the meta-data. Given this example, if the seller originally defined an item with category 58091 (Cannondale), you could update the item to use category 98084 (Complete Bikes & Frames) and then use the first mapping below to pre-fill the Brand attribute with value 30306 (Cannondale). (The seller could then change the value if necessary.)

Example 23-1 Attributes Auto-filled Based on Old Categories
<CategoryMapping oldId="58091" id="98084"> 
  <AttributeSet id="1895"> 
    <Attribute id="14"> 
      <Value id="30306"> 
        <Name><![CDATA[Cannondale]]></Name> 
      </Value> 
    </Attribute> 
  </AttributeSet> 
</CategoryMapping> 
<CategoryMapping oldId="58092" id="98084"> 
  <AttributeSet id="1895"> 
    <Attribute id="14"> 
      <Value id="30355"> 
        <Name><![CDATA[Specialized]]></Name> 
      </Value> 
    </Attribute> 
  </AttributeSet> 
</CategoryMapping> 

GetAttributesCSCall returns current mappings only (not historical mappings). For example, the mapping of a category could occur in this manner:

  1. In January, eBay maps category 123 to category 456. (These IDs are for illustration only; they are not a real category mapping.)
  2. Thus, in January the 123-to-456 mapping is returned.

  3. In May, eBay maps category 456 to category 789.
  4. Category mappings are transitive, so in May category 123 is now also mapped to category 789.

    Thus, in May two mappings are returned:

    • One for the 123-to-789 mapping
    • One for the 456-to-789 mapping.
    • The previous (historical) 123-to-456 mapping is no longer returned because 456 is no longer an active category.

      Furthermore, the attributes that are returned for the 123-to-789 mapping might be different from the attributes that are returned for the 456-to-789 mapping (because the "original" categories are different).

The following figure illustrates the elements contained in the CategoryMapping node, which is a child of CategoryMappingDetails. Table 23-4 describes the purpose of each element.

Figure 23-5 The CategoryMapping Model

Elements in the Item Specifics and Pre-filled Item Information models can specify XML attributes (not to be confused with item attributes). In the table below, the XML attributes (e.g., id) are described in bulleted lists within the "Meaning/Notes" column.

Table 23-4
Element
Data Type
Meaning/Notes
eBay.Attributes.CategoryMappingDetai
ls.CategoryMapping 
Container
Information about attributes that can be auto-filled if the specified active or obsolete category is selected in the listing flow.
Only returned when IncludeCategoryMappingDetails is specified in the GetAttributesCS request.
Auto-filled attributes for combined categories are primarily useful when revising or relisting an item whose category is no longer valid. See Mapping Old Category IDs to Current IDs.
  • id (integer): ID of an active category. Unique for the site. Multiple mappings can return the same active category ID (because different old IDs can be mapped to the same active category).
  • oldId (integer): ID of a category (if any) that has been combined with the active category. Unique for the site. Only returned for one mapping (because an old ID can only be mapped to one active category ID).
AttributeSet 
Container
Contains the list of Attribute nodes that specify auto-filled values for the category mapping.
  • id (integer): Identifier for the attribute set. Matches a characteristic set ID defined in the CharacteristicsList node returned from the same call. Unique across all eBay sites.
...AttributeSet.Attribute 
Container
Container node for attributes that specify auto-filled values based on the category mapping. Multiple Attribute nodes can be returned within a given AttributeSet node.
  • id (integer): Identifier for the attribute. Matches an attribute defined in a CharacteristicsList returned from the same call.
...AttributeSet.Attribute.Value 
Container
The auto-filled value. A Value element may contain other elements (e.g., Name) or it may be an empty tag that only specifies an ID (e.g., <Value id="1001" />).
  • id (integer): Identifier for the value. Possible ID values:
    • -3 = String value from a text field
    • -5 = Full date (day, month, and year). Not applicable as input to listing calls (only applicable when auto-filled by eBay).
    • -6 = A value of "Other"
    • ID = An ID that is unique within the characteristics set (e.g., 1001)
...AttributeSet.Attribute.Value.Name 
string
If present, the display name for the value. The content of the Name element can be CDATA (i.e., <![CDATA[...]]>).
...AttributeSet.Attribute.Value.Year 
string
If present, the year (e.g., 2005) to present to the user as an auto-filled value.

CharacteristicsSet Elements

A CharacteristicsSet node contains one category's set of characteristics, promotional messages related to all the characteristics in the set, and presentation instructions for rendering the characteristics.

The following figure illustrates the elements contained in the CharacteristicsSet node. Table 23-5 describes the purpose of each element.

Figure 23-6 High-Level View of the CharacteristicsSet Model
Table 23-5 CharacteristisSet Content
Element
Meaning/Notes
DomainName 
The well-known name of the characteristic set (e.g., "Tickets").
CharacteristicsList 
Container node for a list of characteristics within the specified set. See CharacteristicsList Elements for details about the elements in this container.
PresentationInstruction 
Hints for how to display attributes in a graphical user interface. Container tag for the list of instructions. See PresentationInstruction Elements for details about the elements in this container.
The presentation instructions are designed to work with eBay's Item Specifics SYI XSL stylesheet to render Item Specifics. Future versions of the presentation instructions may not be backward compatible. If you are not using the XSL, you can use the presentation instructions programmatically, but you should avoid hard-coding the presentation values for specific attributes. Check for updates to the meta-data on a daily basis to assure you are in sync with eBay's current version. It is also a good idea to keep a backup of the last version of the meta-data that you downloaded, so that you can revert to the last version if necessary.
  • pageLocation (string): Identifies the location (e.g., the return policy section) where the attributes listed in the presentation instructions appear on the eBay Web site. If not specified, the default location is the Item Specifics section in the Sell Your Item flow.
Note: Different characteristic sets can return different combinations of presentation instructions, including XML attributes. Some presentation instruction elements may include additional XML attributes that are not documented. These are usually specific to one characteristic set and are used internally at eBay. Applications can ignore this internal information.

CharacteristicsList Elements

A characteristic set contains a characteristics list and other information. A characteristics list is organized into three major sections. Table 23-6 describes the Initial, Conditional, and Other container elements. Each of these elements contains zero or more Attribute nodes.

Table 23-6 CharacteristicsList Content
Element
Data Type
Meaning/Notes
Initial 
Container
Contains all the characteristics that should initially be available to the user. This is the list of attributes to present when the user first accesses the Item Specifics user interface. See Attribute Elements.
Conditional 
Container
Contains additional characteristics that should initially be hidden from the user.
This is a list of attributes that are conditionally visible based on the user's initial selections. Initially, these attributes are not visible. They become visible based on the values that are chosen for other attributes. See Conditional Characteristics.
Empty (e.g., <Conditional></Conditional>) if not applicable.
Other 
Container
Contains characteristics for storing values that the user enters in "Other" fields. These are attributes that might need an "Other" entry based on the user's initial selections. See Other-Value ("Other") Characteristics.
Empty (e.g., <Other></Other>) if not applicable.

The following subsections describe the purpose of each of these sections in more detail.

Initial Characteristics

The Item Specifics SYI XSL stylesheet handles the logic described in this section. Therefore, the following information should mainly be of interest if you are not using the stylesheet in your solution.

When you present a characteristic set to a user, you should begin by displaying a subset of the available characteristics. This prevents the user from making invalid or unnecessary selections. For example, one of the first characteristics a user chooses in the Tickets characteristic set is the Event Type. The Event Type has a list of possible values, such as "Concerts", "Movies", and "Other".

Figure 23-7 An Initial Characteristic

Other-Value ("Other") Characteristics

If a user selects "Other" (e.g., from a drop-down list), eBay may display a text input field to allow the user to enter a value. In this documentation, these are referred to as other-value characteristics.

Figure 23-8 An Other-Value Characteristic (Venue City)

Other-value characteristics have a simpler structure than initial and conditional characteristics.

The Item Specifics XML defines three main types of values that can contain "Other". These are distinguished by their IDs:

These values (and other values with negative IDs) are also summarized in Attribute Elements.

Conditional Characteristics

The Item Specifics SYI XSL stylesheet handles the logic described in this section. Therefore, the following information should mainly be of interest if you are not using the stylesheet in your solution.

Based on the user's selections, the application may need to display additional characteristics that were not initially presented to the user. In some cases, these characteristics should only be presented when certain values are chosen for other characteristics. Otherwise, they will be invalid for the listing. If these characteristics are predefined (i.e., they do not correspond to "Other") the characteristics are called conditional. Conditional characteristics can have the same structure as initial characteristics.

For example, some governments require the seller to specify the face value of a ticket. If the seller indicates that the event is in that government's location, the application should present an additional field called "Face Value". Otherwise, the application should not present the field (as it will be invalid for the listing). API applications should provide similar functionality. See Child Attribute Visibility Dependencies (Type 4: Value-to-Attribute) for additional information.

Figure 23-9 A Conditional Characteristic (Face Value)
Note: On eBay Web sites, conditional characteristics are usually displayed on a separate page. If you use the Item Specifics SYI XSL stylesheet, conditional characteristics are rendered on the same page as initial characteristics.

Attribute Elements

This section describes the Attribute content model. Some of the subsections are useful to understand regardless of whether or not you are using the Item Specifics SYI XSL stylesheet.

Each characteristic is represented by an Attribute node. Each attribute (or characteristic) is identified by an ID and has a Label element containing the display name. Both the ID and the label are unique within the characteristic set. For example, the event-type attribute ID is 40 and its label is Event Type. When the user selects a value (or values, if multiple selections are allowed) for an attribute, the application should store the IDs of that attribute and value. You will need this information in order to list the item (see Summary of the Attributes Model for IDs needed to list items).

Note: Attribute IDs are unique within the same characteristic set, but they are not necessarily unique across all characteristic sets. You shouldn't assume that two attributes with the same ID will have the same values, or that two similar attributes will have the same attribute ID. For example, on the US site, Cassettes and PDAs both support an Condition attribute with ID 10244, but their condition values are different. Men's Jeans and Women's Shoes both support a Condition attribute with ID 94, but their condition values are different too.)

Figure 23-10 Graphical Presentation of the Event Type Attribute and Its Values

The fact that the Event Type attribute should be visually presented as a drop-down list is described in the characteristics list's presentation instructions (see PresentationInstruction Elements).

Note: The presentation instructions are primarily intended to work with the Item Specifics SYI XSL stylesheet. If you are not using the stylesheet, you can parse the presentation instructions yourself, but you should not hard-code the presentation instruction data in your application's code as the rules for presenting attributes can change. For example, an attribute that previously allowed a single value might start allowing multiple values, and vice versa.
Check for updates to the meta-data on a daily basis to assure you are in sync with eBay's current version. It is also a good idea to keep a backup of the last version of the meta-data that you downloaded, so that you can revert to the last version if necessary.

Table 23-3 describes the purpose of each element contained within an Attribute element.

Elements in the Item Specifics and Pre-filled Item Information models can specify XML attributes (not to be confused with item attributes). In the table below, the XML attributes (e.g., id) are described in bulleted lists within the "Meaning/Notes" column.

Table 23-7 The Attribute Model 
Element
Data Type
Meaning/Notes
Conditional.Attribute 
Container
An aspect or feature that is salient to items in a particular category. Only displayed when certain values are selected for other characteristics.
If a conditional characteristic is a child in a visibility (Type 4, Value-to-Attribute (VA)) dependency relationship, it is only valid for a listing when certain parent values are selected. See Characteristic Parent-Child Relationships (Dependencies).
  • id (integer): Unique identifier for the attribute within the characteristic set. See Summary of the Attributes Model for information about attribute IDs that need to be used in listing requests.
  • labelVisible (boolean): If True (1), the label is displayed.
Conditional attributes can specify most of the same elements as initial attributes (see Initial.Attribute), but they do not generally contain Dependency nodes.
Initial.Attribute 
Container
An individual characteristic that is common to all items within the same category.
  • id (integer): Identifier for the attribute. Unique within the characteristic set. Required as input when listing items.
  • isRequired (boolean): If true (1), the attribute is required for listing items in categories that are mapped to this characteristic set.
  • labelVisible (boolean): If true (1), the label is displayed. Applicable to child attributes.
  • dateFormat (string): The preferred sequence and format for date values. For example, M-d-Y implies that the month, date, and year are expected and the order should be month-day-year. See Date Characteristics. The month symbol is case-senstive:
  • M = Use the long form of the month (see GlobalSettings Element)
    m = Use the short form of the month (see GlobalSettings Element)
    Possible sequences are month-day-year (order may vary per site), month-year (or year-month), and year.
Note: The date separator (e.g., "-") is used internally by eBay and has no significance in the API. Also, the Tickets characteristic set does not use the standard date format described here. Instead, the year, month, and day are represented as separate attributes for Tickets.
  • pageLocation (string): The location where the attribute appears in the eBay Web site's Sell Your Item forms. If not specified, the default is the Item Specifics section. Typically, attributes with different page locations are presented to the user in separate locations within an application. For example, return policy attributes would be presented separately from Item Specifics. See Offering a Clear Return Policy.
  • Invisible (boolean): For internal use only. Applications can ignore this information.
  • parentAttrId (integer): Unique identifier for this attribute's parent attribute. Applicable for child attributes in Type 1 (VVC) and Type 2 (VVP) dependencies only. See Characteristic Parent-Child Relationships (Dependencies)
Initial.Attribute.CurrentTime 
Container
For internal use only. Applications can ignore this information.
Initial.Attribute.Dependency  
Container
The values (if any) to be presented for the specified child attribute (childAttrId) if the specified parent value (parentValueId) is selected. This list is defined within the meta-data of the parent characteristic. See Characteristic Parent-Child Relationships (Dependencies). Applications should also use this information (along with validation rules and other meta-data) to determine valid combinations of attributes and values before submitting Item Specifics data in AddItem requests.
  • count (integer): The quantity of Value nodes within the list.
  • childAttrId (integer): The ID of the child attribute (e.g., 37 for Event Type 2) whose values this dependency list can affect.
  • parentValueId (integer): The value ID in the parent attribute's ValueList (e.g., 1001 for "Concerts", in the Event Type attribute's value list) which will cause this dependency list to be used.
  • type (integer): The impact on the specified child attribute (see childAttrId) if the specified parentValueId is selected. Possible values:
  • 1 = Value-to-Value Client (VVC): The child's value list changes via client.
    2 = Value-to-Value Post (VVP): The child's value list changes via server post.
    3 = Value-to-Value Selective Post (VVSP): The child's value list changes via client or post.
    4 = Value-to-Attribute (VA): The child's visibility and listing validity changes.
    5 = Value-to-Meta (VM): The child's required status changes.
Initial.Attribute.Dependency.
Value 
Container
Available value for a child attribute. Most commonly used for type 1 (Value-to-Value) and type 2 ( Value-to-Value Post) dependencies. Container node for the value's display name. The order in which the Value nodes are returned is the order your application should use to present them to the user.
  • id (integer): Identifier for the value. When the user selects the attribute value, the application should store the ID to be used later in the AddItem call. Possible ID values:
  •  0= Any of the child attribute's values can be selected. Only applicable to type 4 (Value-to-Attribute) and type 5 (Value-to-Meta) dependencies.
    -6 = Other (user enters the value in an "Other" field)
    -10 = -- (display a dash)
    -12 = Other (user cannot enter a value)
    ID = An ID that is unique within the same characteristic set (e.g., 1001)
Note: For other-value text boxes, multi-select lists, and check boxes, multiple values can be associated with the same value ID. For example, -6 is not a unique value ID.
...Dependency.Value.
DisplayName 
string
An alternative display name that is used to specify the scaled quantity and unit of measure corresponding to Value.Name. For example, for Max Processor Speed, if Value.Name is 1500, Value.DisplayName would be 1.5 Ghz. The content of the DisplayName element can be returned as CDATA (i.e., <![CDATA[...]]>).
...Dependency.Value.Name 
string
The name of the value as it should be displayed to users. The content of the Name element can be returned as CDATA.
Initial.Attribute.EditType 
int
Indicates whether the attribute's value(s) is (are) editable (i.e., the user can select or enter a value). Possible values:
0 = Always user-selectable or user-definable
1 = Always pre-filled by eBay (read-only)
2 = May be pre-filled by eBay (conditionally editable)
If 2 and not pre-filled, the user can select or enter a value.
Child attributes can only be user-selectable (EditType 0 or 2). If AttributeSet.Attribute.source is 1 (pre-filled by eBay) or 3 (pre-filled by catalog) and the value of EditType is 1 or 2 (pre-filled), the attribute should be displayed as read-only.
Initial.Attribute.
DefaultUnitOfMeasureFormatS
tring 
string
A hint (e.g., "{0} Mhz") that indicates how an application can display an attribute whose values should be interpreted according units of measure (e.g., Max Processor Speed), where {0} is a placeholder for the quantity and the second value (Mhz) is the base unit. The quantity and units are scaled with respect to the default unit according to standard upper and lower bounds (e.g., 1500 Mhz is represented as 1.5 Ghz). The Value.Name element specifies the quantity in the default unit (e.g., 1500). The Value.DisplayName element specifies the scaled quantity and scaled unit (e.g., 1.5 Ghz). Usage of the default format string is optional. If you pass in "1500 Mhz" in the AddItem call (or related calls), eBay converts the value to "1.5 Ghz".
Initial.Attribute.HasGlossary 
boolean
For internal use. Not applicable to Sell Your Item use cases. Applications should ignore this element.
Initial.Attribute.HelpText 
string
Help text that can appear when the user's cursor hovers over the attribute (e.g., Alt text).
Initial.Attribute.Label 
string
Display name of the attribute. Corresponds to the label that usually appears above the attribute widget.
Initial.Attribute.
MessageBottom 
string
Message to display below the attribute widget.
Initial.Attribute.
MessageLeft 
string
Message to display to the left of the attribute widget.
Initial.Attribute.
MessageRight 
string
Message to display to the right of the attribute widget.
Initial.Attribute.MessageTop 
string
Message that should appear above the attribute.
Initial.Attribute.Type 
int
The attribute data type. (Not to be confused with EditType or Dependency.type) Possible values:
    1 = Numeric
    2 = String
    3 = Date
Initial.Attribute.ValueList 
Container
A list of one or more valid values that the user can select for the attribute. Applications should present all values to the user. See ValueList and Value Elements.
Contains a list of Value nodes, unless the attribute is a pre-filled EditType 1 or pre-filled EditType 2 attribute (see Determining Whether the User Can Choose an Attribute Value).
If the attribute is a child in a dependency, the Dependency node of the parent attribute specifies the values that can be used for the child attribute in the Sell Your Item flow. See Child Value List Dependencies (Types 1, 2, and 3: Value-to-Value).
If not present, there are no predefined values. In this case, specify a free-text value for the attribute in item-listing requests.
  • count (integer): The quantity of Value nodes within the list.
Initial.Attribute.ValueList.
Value 
Container
Available value for the attribute. Contains the values display name. The order in which the Value nodes are returned is the order your application should use to present them to the user.
  • id (integer): Identifier for the value. When the user selects the attribute value, the application should store the ID to be used later in the AddItem call. Possible ID values:
  • -6 = Other (user enters the value in an "Other" field)
    -10 = -- (display a dash)
    -12 = Other (user cannot enter a value)
    ID = Any other ID that is unique within the attribute (e.g., 1001)
Note: Other negative IDs returned by attribute meta-data calls can be handled and used as is. However, for your reference, here are some of the common negative value IDs.
    -13 = Yes, or the equivalent (optionally render as a checked box)
    -14 = No, or the equivalent (optionally render as an unchecked box)
    -15 = "Any" or "All"
    -16 = "Other Model" in US and CA Motors categories. In general, you need to use the category to specify the make and model instead.
...ValueList.Value.
DisplayName 
string
The name of the value as it should be displayed, if different from Value.Name. Often used to specify the scaled quantity and unit of measure corresponding to Value.Name. For example, for Max Processor Speed, if Value.Name is 1500, Value.DisplayName would be 1.5 Ghz. The content of the DisplayName element can be CDATA (i.e., <![CDATA[...]]>).
...ValueList.Value.Name 
string
The text name of the value. The content of the Name element can be CDATA.
Initial.Attribute.
ValidationRules 
Container
Contains rules describe how to validate the attribute's value(s), if applicable. For example, characteristics that accept user-entered text can include rules for validating the user's input against regular expressions and/or string length constraints. An attribute can have zero or more rules.
...ValidationRules.Rule 
Container
A rule for validating an attribute's value(s) selected or entered by the user. Contains the rule's name and list of zero (0) or more additional elements. Usually, a given rule contains no more than three elements, including Name. The list of applicable elements varies depending on the rule name.
See Validation Rules in the Attribute Meta-Data for information about specific rule names and how to interpret the rule data.
...ValidationRules.Rule.
Length 
int
The permitted length the value.
...ValidationRules.Rule.Mask 
string
A sequence of characters that must be included in the value.
...ValidationRules.Rule.Max 
int or double
The maximum value permitted. Some rules that contain a Max element also contain a Min element.
...ValidationRules.Rule.Min 
int or double
The minimum value permitted. Some rules that contain a Min element also contain a Max element.
...ValidationRules.Rule.Name 
string
A unique, descriptive name for the rule. Rule nodes always return a Name element. See Validation Rules in the Attribute Meta-Data for information about specific rule names and how to interpret the rule data.
...ValidationRules.Rule.
PeerAttributeId  
int
When two fields are used to represent a date range (e.g., for dates of stay in Travel categories), the 'from" date and "to" date are defined as separate attributes. In some cases, date validation rules may be specified on the "from" date attribute. In these cases, the PeerAttributeId contains the ID of the "to" date attribute.
...ValidationRules.Rule.
Precision 
int
For doubles, the scale (number of digits after the decimal) for the value. Only for display purposes (not for validation). This value may no longer be supported for some attribute sets.
...ValidationRules.Rule.Regex 
string
A regular expression that the value must match. Applicable to string data types.
...ValidationRules.Rule.
Required 
boolean
Indicates whether the attribute is required for listing the item. If the Required element is present (true), the attribute is required. If the element is not present (false), the attribute is not required.
...ValidationRules.Rule.
Separator 
string
Symbol used as a numeric values separator (e.g. "," in "1,000"). Not necessarily a period (.), space ( ), or comma (,). It could be any string.
Other.Attribute 
Container
An attribute that might need an "Other" entry based on the user's initial selections.
Contains the attribute label and additional meta-data.
  • id (integer): Unique identifier for the attribute within the characteristic set.
  • isRequired (boolean): If true (1), required for listing items in this category.
Other.Attribute.Label 
string
Display name of the attribute. Corresponds to the label that usually appears above the attribute widget.
Other.Attribute.MessageBottom 
string
Message to display below the attribute widget.
Other.Attribute.Required 
(boolean)
Indicates that a value must be specified for the attribute. If the element is present, it means the attribute is required. If the element is not present, the attribute is not required. (The boolean semantics are indicated by the presence/absence of the element, not by 0/1 values.)
The presence of this tag is usually interpreted to mean that the user should be notified that the field is required. For example, in an application with a graphical user interface, an asterisk (*) might be placed adjacent to the field.

Determining Whether the User Can Choose an Attribute Value

The Item Specifics SYI XSL stylesheet handles the logic described in this section. Therefore, the following information should mainly be of interest if you are not using the XSL stylesheet in your solution. See Attribute Error Handling

Sometimes GetAttributesCSCall or GetProductSellingPagesCall will return attributes or values that should not be presented to the user or that should not be treated as editable.

The EditType element indicates whether the attribute's value is read-only or whether the user can select or enter the characteristic's value (or values). Your application should correctly present such data as editable, read-only, or hidden, and update the editable state of the data for revise/relist requests according to the attribute's current EditType value.

A characteristic can have one of these edit types:

Your application should correctly present such data as editable, read-only, or hidden, and update the editable state of the data for revise/relist requests according to the attribute's type.

ValueList and Value Elements

If you are using the stylesheet, this section may give you insight as to the IDs that appear in the POST data (see Parsing the Item Specifics Form POST Data).

To reduce data-entry errors and, in some cases, for informational accuracy, most characteristics define a list of valid values for the user to choose from. Within the Initial and Conditional nodes, the predefined valid values (one or more) for an attribute are represented by a ValueList element that contains Value elements.

Value lists are mainly applicable to independent (parent) attributes (see Characteristic Parent-Child Relationships (Dependencies)). If an independent attribute has no ValueList node, there are no predefined values for that attribute. In this case, specify a free-text value for the attribute in item-listing requests. Child attributes in Value-to-Value dependency relationships do not contain ValueList nodes.

Figure 23-11 The ValueList Model

For parsing purposes, the ValueList specifies the number of values it contains (the count). Each value is identified by an ID (e.g., 1001) and has a display name (e.g., "Concerts").

Example 23-2 A ValueList Element
 <ValueList count="6"> 
    <Value id="-10"> 
      <Name><![CDATA[-]]></Name> 
    </Value> 
    <Value id="1001"> 
      <Name><![CDATA[Concerts]]></Name> 
    </Value> 
    <Value id="1002"> 
      <Name><![CDATA[Movies]]></Name> 
    </Value> 
    <Value id="1003"> 
      <Name><![CDATA[Sporting Events]]></Name> 
    </Value> 
    <Value id="1004"> 
      <Name><![CDATA[Theater]]></Name> 
    </Value> 
    <Value id="-12"> 
      <Name><![CDATA[Other]]></Name> 
    </Value> 
  </ValueList> 

When the user selects a value (or values, if multiple selections are allowed) for an attribute, the application should store the IDs of that attribute and value. You will need this information in order to list the item (e.g., in the AddItem family of calls).

For for other-value text boxes (i.e., text boxes for filling in "Other"), multi-select lists, and check boxes, multiple values can be associated with the same value ID.

Characteristic Parent-Child Relationships (Dependencies)

The Item Specifics SYI XSL stylesheet handles the logic described in this section. Therefore, the following information should mainly be of interest if you are not using the stylesheet in your solution.

Selecting or changing values can result in changes to other characteristics and/or their values. Some characteristics have hierarchical relationships (e.g., State and City) in which the value list of one characteristic is determined by the value specified for another. Some characteristics toggle between optional and required depending on the values chosen for other characteristics. Some characteristics are initially hidden until the user makes other selections. Each of these situations sets up a parent-child relationship between the affected characteristics.

A parent and child characteristic can have one or more of the following types of dependency relationships.

The parent characteristic defines a child attribute's values in a dependency value list (the Dependency element), and the child characteristic contains a reference to its parent. This concept is explained further in the sections below.

Figure 23-12 The Characteristic Value List and Dependency Value List Models

A dependency value list (i.e., a Dependency element defined in the parent) specifies the ID of the child characteristic it affects (e.g., childAttrId="37" for Event Type 2), and the ID of the parent value whose selection will cause this dependency value list to be used (e.g., parentValueId="1001" for Concerts or parentValueId="1003" for Sporting Events).

The Attribute element of a child characteristic specifies the ID of its parent (parentAttrId).

The snippet below shows:

Child Value List Dependencies (Types 1, 2, and 3: Value-to-Value)

Some attributes have hierarchical relationships in which the value of one attribute is determined by the value of another.

For example, suppose a seller wants to list a ticket for a pop concert. First, the seller selects a value called "Concerts" from a list of available event types (the parent). Then, the application presents a more specific list of values (the child), such as "Classical" and "Pop".

Figure 23-13 Graphical Presentation of a Child Attribute and Its Valid Values

However, if the user selects an event-type value called "Sporting Events", the second drop-down list displays values like "Golf" and "Hockey". In other words, the values that appear in the second list are dependent on the value (or values, if multiple selections are permitted) selected in the first one.

Figure 23-14 Graphical Presentation of an Attribute and Alternative Valid Values

In a Web-based application, the various alternative value lists are either stored on the client or server, depending on the size of the data set:

Initial and conditional characteristics can have "Other" values and may define dependency lists that contain "Other" values for child characteristics. If "Other" is selected, the corresponding Other-Value characteristic is displayed.

As the value list for the child in a hierarchical dependency can vary depending on the parent's selected value (and, potentially, the values selected for multiple parent attributes), the child does not maintain its own value list. Instead (as stated in the previous section), the parent characteristic defines all possible value lists for the child in a set of dependency value lists (each represented by the Dependency element).

As with any attribute value, each Value element within the dependency list has an ID (e.g., 1021) and has a display name (e.g., "Pop").

Example 23-4 Child Value List Dependencies
<Attribute labelVisible="true" id="40">  
  <Label><![CDATA[Event Type]]></Label> 
  <ValueList count="6"> 
    <Value id="1001"> 
      <Name><![CDATA[Concerts]]></Name> 
    </Value> 
    <Value id="1003"> 
      <Name><![CDATA[Sporting Events]]></Name> 
    </Value> 
    <Value id="1004"> 
    ... more Value nodes ... 
  </ValueList> 
  ... other meta-data tags in parent ... 
  <Dependency count="8" childAttrId="37" type="1" parentValueId="1001">   
    <Value id="1018"> 
      <Name><![CDATA[Classical]]></Name> 
    </Value> 
    ... more Value nodes ... 
  </Dependency> 
  ... more Dependency nodes ... 
</Attribute> 
<Attribute id="37" parentAttrId="40">  
  <Label><![CDATA[Event Type 2]]></Label> 
  ... other meta-data tags in child, but no Value nodes ...  
</Attribute>  

Characteristics in the Initial and Conditional nodes can have "Other" values and may define dependency lists that contain "Other" values for child characteristics. If "Other" is selected, the corresponding Other-Value characteristic (defined in the Other node) is displayed.

Child Attribute Visibility Dependencies (Type 4: Value-to-Attribute)

Some attributes are rarely specified for an item and should only be presented to the user when certain values are chosen for other characteristics.

For example, the Face Value attribute for Tickets is initially hidden from the user. However, a government might require the seller to specify the face value of a ticket (which could be more or less than the listing price). If the seller specifies a location within that government's jurisdiction, the application must present the Face Value attribute. Otherwise, the application should not present the attribute (as it will be invalid for the listing).

Figure 23-15 Graphical Presentation of a Child Attribute Becoming Visible

A child attribute in a Value-to-Attribute relationship appears in the Conditional characteristics node. In the example below, the State/Province attribute (id="9") has a value called "Arkansas" (id="1038") and specifies a Type 4 dependency for Face Value (childAttrId="62"). The dependency list contains only one Value node (id="0"), which will hold a user-entered value. The Face Value attribute appears in the Conditional node. If the user selects "Arkansas", the Face Value attribute will be presented. Characteristics in the Conditional node can also be parents of other conditional characteristics.

Example 23-5 Value-to-Attribute Visibility Dependencies
<Initial> 
  <Attribute id="9" IsRequired="true"> 
    <EditType>0</EditType> 
    <Label><![CDATA[Venue State/Province]]></Label> 
    <ValueList count="66"> 
      <Value id="-10"> 
        <Name><![CDATA[-]]></Name> 
      </Value> 
     ... more Value nodes ... 
     <Value id="1038"> 
        <Name><![CDATA[Arkansas]]></Name>  
       </Value> 
      ... more Value nodes ... 
    </ValueList> 
    ... Dependency nodes ... 
    <Dependency count="1" childAttrId="62" parentValueId="1038" type="3"> 
      <Value id="0"></Value> 
    </Dependency> 
    <Dependency count="1" childAttrId="62" parentValueId="1038" type="4">  
      <Value id="0"></Value> 
    </Dependency> 
    <Dependency count="1" childAttrId="62" parentValueId="1038" type="5"> 
      <Value id="0"></Value> 
    </Dependency>  
    ... more Dependency nodes ... 
  </Attribute> 
</Initial> 
<Conditional> 
  <Attribute labelVisible="true" id="62">  
    <Label><![CDATA[Face Value]]></Label> 
    <EditType>0</EditType> 
    ... more tags ... 
  </Attribute> 
</Conditional> 

Note: When a characteristic specifies multiple dependencies that map the same value to the same child attribute, all of those dependencies take effect. Thus, in the example above, if the user selects "Arkansas" (id="1038"), the application must handle the specified type 3, type 4, and type 5 dependencies.

Child Required-Status Dependencies (Type 5: Value-to-Meta-data)

Some attributes toggle between optional and required depending on the values chosen for other characteristics.

For example, the Face Value characteristic for Tickets is initially hidden from the user, and it is not required in order to list the item. However, as described above, a government might require the seller to specify the face value of a ticket (which could be more or less than the listing price). If the seller specifies a location within that government's jurisdiction, the application must present the Face Value characteristic and the user is required to specify a value for it.

If an attribute is always required (under all circumstances), it would likely not be identified as a child attribute with this kind of dependency. This type of dependency is generally used when an attribute is only required in certain circumstances.

A child characteristic in a Value-to-Meta-data relationship is defined in the Conditional characteristics node. In the example shown in the section above, the State/Province attribute (id="9") has a value called "Arkansas" (id="1038") and specifies a Type 5 dependency for Face Value (childAttrId="62"). The dependency list contains only one Value node (id="0"), which will hold a user-entered value. The Face Value characteristic appears in the Conditional node. If the user selects "Arkansas", the Face Value characteristic will be presented and it will become required.

Validation Rules

Characteristics that accept user-entered text usually include rules for validating the user's input against regular expressions (RegularExpressionValidationRule) and/or string length constraints (StringLengthRule).

See Validation Rules in the Attribute Meta-Data for information about using validation rules and a current list of the rules.

Date Characteristics

In many characteristic sets, date characteristics are expected to be displayed as a group of drop-down lists—one drop-down list for each portion of the date (i.e., day, month, and year).

Figure 23-16 Graphical Presentation of a Date Attribute

This section describes how to interpret the schema in order to render dates. For information about the valid date formats to use in AddItemCall, see Specifying Date Attributes when Listing Items.

Date characteristics are handled in a special manner in order to carefully control the combinations of day, month, and year values that are presented to the user.

Note: Some characteristic sets, such as US Tickets and US Commercial Real Estate, do not use the standard date format described here. Instead, the year, month, and day are represented as separate attributes, and all values (e.g., 1-31 for Day) are specified in individual Value nodes.

Months of the year are identified by name. eBay sites can support a long form (e.g., "January") or abbreviated (short) form (e.g., "Jan") of the month name. Localized month names (as appropriate for the SiteId) are defined in a GlobalSettings node at the root level of the XML response (i.e., as a child of the eBay element). See GlobalSettings Element. Several sources of information about localized date formats are available on the Internet. For example:

Locale Information

Microsoft Corporation

http://msdn.microsoft.com/library/en-us/intl/nls_8rse.asp?frame=true
java.text.DateFormat

Sun Microsystems, Inc.

http://java.sun.com/j2se/1.4.2/docs/api/java/text/DateFormat.html

A date characteristic's presentation instruction (see PresentationInstruction Elements) includes hints for displaying dates.

Days of the month range from 01 to 31 (depending on the number of days in the month). An application with a graphical user interface would typically present these values in drop-down lists.

The following snippet shows an example of a date characteristic's presentation instruction. The sort_order XML attribute (see the Month element) indicates whether to present the choice of months in ascending (increasing) or descending (decreasing) order. To determine whether to use the short or long form, see the corresponding date characteristic (descrbed below).

Example 23-6 Presentation Instructions for a Date Characteristic
<Widget type="date"> 
  <Attribute align="left" id="25009" quadrant="top"> 
    <Label align="left" color="#000000" face="Arial, Helvetica, Sans-Serif" size="2"/> 
    <Day align="left" color="#000000" face="Arial, Helvetica, Sans-Serif" quadrant="top" 
size="13" sort_order="INCREASING">Release Date</Day> 
    <Month align="left" color="#000000" face="Arial, Helvetica, Sans-Serif" quadrant="top" 
size="13" sort_order="INCREASING">Release Date</Month> 
    <Year align="left" color="#000000" face="Arial, Helvetica, Sans-Serif" quadrant="top" 
size="13">Release Date</Year> 
    <Input columns="2" type="textfield" format="m_d_y"/> 
  </Attribute> 
</Widget> 

Note: Some characteristic sets return a different set of presentation instructions for dates. For example, fields named DayAscending, DayDescending, MonthAscendingLong, MonthAscendingShort, MonthDescendingLong, and MonthDescendingShort may be returned.
The Widget.Attribute.Input field may contain a format XML attribute for dates. The Widget.Attribute node may also contain Years fields.
This alternate date attribute meta-data will be deprecated in a future version, and all characteristics will use the format described above. Applications that do not use the Item Specifics SYI XSL stylesheet should rely on the date information defined in the characteristic instead of using the presentation instructions, as described below.

A dateFormat XML attribute is defined in the date characteristic (not in the presentation instruction). The dateFormat XML attribute specifies the valid combination of day, month, and year options and the order in which these date elements should appear. The case of the "M" in the format string specifies whether to use the short ("m") or long ("M") form of the month names, as defined in the global settings. For example, a value of "M-d-Y" means the application should present all three date elements to the user in the order month-day-year, and it should use the long form of the month name. A value of "m-Y" means the application should present the month and year elements to the user (in that order), and it should use the short form of the month name.

Year values are strings and are always in the form YYYY. The valid years are specified in the characteristic's value list. (Applications should ignore any year information that appears in the presentation instruction.) The order in which the year values should be presented is implied by the order in which they appear in the value list.

The following snippet shows an example of a Travel Date characteristic in the Lodging characteristic set. For date characteristics, the data type (Type) field returns a value of "3". This is the characteristic that matches the date presentation instruction shown above. Notice that only the year values appear in the ValueList. The presence of the month and day are indicated in the dateFormat XML attribute.

Example 23-7 A Travel Date Characteristic
<Attribute id="23" labelVisible="true" dateFormat="M-d-Y"> 
  <EditType>0</EditType> 
  <Type><![CDATA[3]]></Type> 
  <Label><![CDATA[Date Range]]></Label> 
  ... other meta-data elements ... 
  <ValueList count="4"> 
    <Value id="-10"> 
      <Name><![CDATA[-]]></Name> 
    </Value> 
    <Value id="1193"> 
      <Name><![CDATA[2002]]></Name> 
    </Value> 
    <Value id="1194"> 
      <Name><![CDATA[2003]]></Name> 
    </Value> 
    <Value id="1195"> 
      <Name><![CDATA[2004]]></Name> 
    </Value> 
  </ValueList> 
  ... other meta-data elements ... 
</Attribute> 

Default values for the day, month, and year may be specified in the AttributeSet node (see AttributeSet Elements). A value ID of "-5" indicates that the value contains date information.

Example 23-8 An AttributeSet Node with Date Fields
<AttributeSet id="15550"> 
  <Attribute id="8050" vivisible="true" count="1" displaysequence="1" source="3"> 
    <SellingDisplayLabel><![CDATA[From Date]]></SellingDisplayLabel> 
    <Value id="-5"> 
      <Day>05</Day> 
      <Year>2004</Year> 
      <Month>02</Month> 
    </Value> 
  </Attribute> 
  ... more Attribute nodes ... 
</AttributeSet> 

After the user has specified a date, your application should collect the values and convert them to the appropriate format for the AddItem call. (This is handled easily if you are using the Item Specifics SYI XSL stylesheet.) See Specifying Date Attributes when Listing Items.

PresentationInstruction Elements

Important: The presentation instructions in the Item Specifics XML can change without notice and the changes are not necessarily backward compatible. They are included in the API primarily for use with eBay's Item Specifics SYI XSL stylesheet to render Item Specifics. If you are not using eBay's XSL, you can intepret the presentation instruction elements programmatically, but avoid hard-coding the specific details described in the presentation instruction elements.

For applications that display Item Specifics by means of a graphical user interface and that use the XSL stylesheet, each characteristic set returned from GetAttributesCSCall and GetProductSellingPagesCall includes a list of optional presentation instructions. Presentation instructions are essentially hints that indicate the user-interface controls (e.g., drop-down lists) that can be used to render characteristics. They can contain related elements such as the first value that should appear in the list and messages that might appear adjacent to the attribute. In addition, the instructions may specify text messages (TextMessage) that relate to a group of attributes (e.g., tips to help the seller fill in the form).

Use eBay's Item Specifics Sell Your Item (SYI) XSL stylesheet to transform a single characteristic set XML document into an HTML document. eBay's Item Specifics XSL stylesheet uses the presentation instructions during the XML-to-HTML transformation. Use GetAttributesXSLCall to download the stylesheet.

The stylesheet uses the presentation instructions to present each attribute as well as related elements, such as the first value that should appear in the list and messages that might appear adjacent to the attribute. In addition, the instructions specify text messages that relate to a group of attributes (e.g., tips to help the seller fill in the form).

As described in Characteristic Parent-Child Relationships (Dependencies), selecting or changing characteristic values can result in changes to other characteristics and/or their values. This is governed by dependency relationships defined in advance for all characteristics in the set. Depending on the dependency type, the user's selection may trigger a post to the server, refreshing the page and dependent attributes, or it may be handled locally within on the client (e.g., by means of a JavaScript function).

If a user wants to enter a value not available in an options list, the user may select "Other" as an option. In this case, the user is presented with one or more attributes as text fields—one for each "Other" value chosen from the characteristic set. In the characteristic set XML document, these text fields are defined within the characteristics list's Other node (see Other-Value ("Other") Characteristics).

If validation errors occur, the application typically repaints the page or screen with the errors identified and appropriately flagged at the field level. See Presenting Valid Attributes and Values to Users for examples of these rules.

The presentation instructions and the Item Specifics Sell Your Item (SYI) XSL stylesheet can be used equally well to generate HTML for Web-based applications and for Windows desktop applications that embed an Internet Explorer control. Other types of applications can use this information as a model for custom implementations as well. See Working with the Item Specifics XSL Stylesheet for more information.

As mentioned above, if you are not using eBay's XSL, you can intepret the presentation instructions programmatically, but avoid hard-coding the specific details described in the presentation instruction elements. For example, avoid hard-coding whether a specific attribute accepts multiple values or not. (Always look up that kind of information programmatically.) Check for updates to the meta-data on a daily basis to assure you are in sync with eBay's current version. It is also a good idea to keep a backup of the last version of the meta-data that you downloaded, so that you can revert to the last version if necessary.

Relying on the presentation instructions is optional. Depending on the categories you list in and your application's use cases, you could also choose to only use the presentation instructions as hints during your development process:

Table 23-8 describes the elements that were contained in the PresentationInstruction node as of the time of this writing. Different characteristic sets can return different combinations of presentation instructions, including XML attributes. Some presentation instruction elements may include additional XML attributes that are not documented. These are usually specific to one characteristic set and are used internally at eBay. You can ignore this internal information. Also, as the presentation instructions can change periodically without notice, it is possible that the table below will become out of date. However, as this information is only mainly used by the Item Specifics SYI XML stylesheet, this should not affect most developers. Please feel free to contact the documentation team through the Documentation Forum on the eBay Developers Program site if you need information about undocumented presentation instructions.

Elements in the characteristic set model can specify XML attributes (not to be confused with item attributes). In the table below, the XML attributes (e.g., id) are described in bulleted lists in the "Meaning/Notes" column.

Due to the large size and deep structure of the result set, the Element column uses ellipses (...) to indicate that a tag's fully qualified name is the same as that of the tag above it.

Table 23-8 PresentationInstruction Content
Element
Data Type
Meaning/Notes
Conditional 
Container
Container tag for one or more Row elements that should be displayed if values with type 4 (Value-to-Attribute) or type 5 (Value-to-Meta-data) dependencies are selected for certain attributes. Can contain the same elements as the PresentationInstruction.Initial element (see below).
DomainName 
String
The well-known name of the domain (e.g., "Tickets"). (The term domain is maintained for users of previous versions of the Attributes API. A domain is equivalent to a characteristic set.)
Initial 
Container
Container tag for one or more Row elements that should be displayed when the Item Specifics form is initially rendered.
Initial.Row 
Container
Container tag for one or more Widget elements. Row elements should be displayed from top to bottom.
...Row.Widget 
Container
Container tag for presentation instructions related to an attribute, including associated messages. Widget elements within the same Row element should be displayed side-by-side. See Item Specifics Widgets.
  • type (string): Possible values:
  • text_message = The widget consists of plain text only.
    normal = The widget is an input (or selection) element.
    date = The widget is used for selecting dates (see Input below).
  • isVisible (string): Applicable when the characteristic set is 1137 (US eBay Motors Cars & Trucks). See Using Item Specifics in eBay Motors US Listings. Possible values:
  • y = The widget is always displayed.
    n = The widget is never displayed.
    c = The widget is only displayed in the VIN Catalog flow. (Not supported by the API.)
    nc = The widget is only displayed in the standard flow (non-Catalog), which is supported by the API.
...Row.Widget.Attribute 
Container
Container for the attribute's presentation instructions.
  • id (integer): The attribute ID
  • align (string): Alignment of the attribute (including label and values) within its table cell (e.g., left, right, center).
  • quadrant (string): The layout of the attribute name in relation to the input element. Possible values:
  • Top = Above the attribute input control
    Bottom = Below the attribute input control
    Left = To the left of the attribute input control
    Right = To the right of the attribute input control
  • hide (boolean): If True (1), the widget is initially hidden when the characteristic set is presented to the user.
...Row.Widget.Attribute.Day 
String
Label to use for the day drop-down in a date widget (which can be a combination of three drop-down lists for day, month, and year).
  • align (string): Alignment of the label within its table cell (e.g., left, right, center).
  • color (string): Color of the label text in hexadecimal (e.g., #000000 for black).
  • face (string): A comma-separated list of font faces to use, in order of preference (if available on the user's system).
  • quadrant (string): Position of the label relative to the widget. Possible values:
  • top = Above the widget
    bottom = Below the widget
    left = To the left of the widget
    right = To the right of the widget
  • size (integer): The point size of the font.
  • sort_order (string): The order in which to present the values (INCREASING or DECREASING).
...Row.Widget.Attribute.DayAscending 
String
Days of the month, in ascending order. Only returned for some characteristic sets. Others use the Day.sort_order presentation instruction and the Attribute.dateFormat characteristic meta-data to specify date presentation and format. In the future, all characteristics will use the latter format.
...Row.Widget.Attribute.DayDescending 
String
Days of the month, in descending order. Only returned for some characteristic sets. Others use the Day.sort_order presentation instruction and the Attribute.dateFormat characteristic meta-data to specify date presentation and format. In the future, all characteristics will use the latter format.
...Row.Widget.Attribute.Glossary 
String
For future use. Not applicable for Sell Your Item use cases. Applications should ignore this element.
...Row.Widget.Attribute.Input 
Container
The type of control to use when presenting the attribute. If you want to maintain a look and feel that is consistent with eBay and familiar to eBay users, your application should present the attribute using the specified type of input element. If you use the XSL stylesheet, it will handle this for you.
  • type (string): The type of input element to use. Possible values include:
  • dropdown = A drop-down list that permits one value to be selected. Can contain an "Other" value.
    textfield = Text-entry box (for a single string)
    single = A combo box that permits one value to be selected.
    radio = A set of radio button(s) that permits one value to be selected.
    multiple = A list box that permits multiple values to be selected.
    check = A check box (or a set of check boxes that permit multiple values to be selected).
    collapsible_textarea = Text area that can be shown or hidden. Only shown when an applicable value is selected for a field this field depends on (see Characteristic Parent-Child Relationships (Dependencies)).
  • format (string): The date format, if any. This field is ignored by the Item Specifics XSL and should be considered obsolete. Instead, use the value returned for Attribute.dateFormat in the characteristics data (e.g., Initial.Attribute.dateFormat).
  • columns (integer): Number of columns in which to display check boxes or radio buttons.
  • size (integer): Font size of values within type=dropdown, multiple, or single.
  • display_size (integer): Height of scroll box in rows when type=multi or type=single. Number of rows to show when dropdown is open for selection.
  • maxlength (integer): Number of characters that can be entered for a textfield.
...Row.Widget.Attribute.InitialValue 
String
Default value that should be displayed (e.g., "Please Choose City").
...Row.Widget.Attribute.Label 
Container
Instructions for presenting the attribute's display name. Some instructions are only applicable for applications with graphical user interfaces.
  • face (string): A comma-separated list of font faces to use, in order of preference (if available on the user's system).
  • size (integer): The relative size of the font.
  • required (boolean): If True (1), the label must be presented to the user.
  • align (string): Alignment of the label within its table cell (e.g., left, right, center).
  • color (string): Color of the label text in hexadecimal (e.g., #000000 for black).
...Row.Widget.Attribute.MessageBottom 
Container
Format for message that should appear below the widget.
  • face (string): A comma-separated list of font faces to use, in order of preference (if available on the user's system).
  • size (integer): The relative size of the font.
  • align (string): Alignment of the label within its table cell (e.g., left, right, center).
  • color (string): Color of the label text in hexadecimal (e.g., #000000 for black).
...Row.Widget.Attribute.Month 
String
Label to use for the month drop-down in a date widget (which can be a combination of three drop-down lists for day, month, and year).
  • align (string): Alignment of the label within its table cell (e.g., left, right, center).
  • color (string): Color of the label text in hexadecimal (e.g., #000000 for black).
  • face (string): A comma-separated list of font faces to use, in order of preference (if available on the user's system).
  • quadrant (string): Position of the label relative to the widget. Possible values:
  • top = Above the widget
    bottom = Below the widget
    left = To the left of the widget
    right = To the right of the widget
  • size (integer): The point size of the font.
  • sort_order (string): The order in which to present the values (INCREASING or DECREASING).
...Row.Widget.Attribute.MonthAscendingLon
g 
String
Indicates that if the month attribute is expected (see Initial.Attribute.dateFormat), the months of the year should be presented in the order and format returned in the GlobalSettings.MonthAscendingLong element.
Only returned for some characteristic sets. Others use the Month.sort_order presentation instruction and the Attribute.dateFormat characteristic meta-data to specify date presentation and format. In the future, all characteristics will use the latter format.
...Row.Widget.Attribute.MonthAscendingSho
rt 
String
Indicates that if the month attribute is expected (see Initial.Attribute.dateFormat), the months of the year should be presented in the order and format returned in the GlobalSettings.MonthAscendingShort element.
Only returned for some characteristic sets. Others use the Month.sort_order presentation instruction and the Attribute.dateFormat characteristic meta-data to specify date presentation and format. In the future, all characteristics will use the latter format.
...Row.Widget.Attribute.MonthDescendingLo
ng 
String
Indicates that if the month attribute is expected (see Initial.Attribute.dateFormat), the months of the year should be presented in the order and format returned in the GlobalSettings.MonthDescendingLong field.
Only returned for some characteristic sets. Others use the Month.sort_order presentation instruction and the Attribute.dateFormat characteristic meta-data to specify date presentation and format. In the future, all characteristics will use the latter format.
...Row.Widget.Attribute.MonthDescendingSh
ort 
String
Indicates that if the month attribute is expected (see Initial.Attribute.dateFormat), the months of the year should be presented in the order and format returned in the GlobalSettings.MonthDescendingShort field. Only returned for some characteristic sets. Others use the Month.sort_order presentation instruction and the Attribute.dateFormat characteristic meta-data to specify date presentation and format. In the future, all characteristics will use the latter format.
...Row.Widget.Attribute.NoJS 
Boolean
Not currently supported by the API. Applications should ignore this information.
...Initial.Row.Widget.Attribute.Year 
String
Label to use for the year drop-down in a date widget (which can be a combination of three drop-down lists for day, month, and year).
  • align (string): Alignment of the label within its table cell (e.g., left, right, center).
  • color (string): Color of the label text in hexadecimal (e.g., #000000 for black).
  • face (string): A comma-separated list of font faces to use, in order of preference (if available on the user's system).
  • quadrant (string): Position of the label relative to the widget. Possible values:
  • top = Above the widget
    bottom = Below the widget
    left = To the left of the widget
    right = To the right of the widget
  • size (integer): The point size of the font.
  • sort_order (string): The order in which to present the values (INCREASING or DECREASING).
...Row.Widget.Attribute.YearInitialValue 
String
Initial value to display for the Year in a drop-down list.
...Row.Widget.Attribute.Years 
Partial Date
Specifies a year (e.g., 2003). Multiple Years fields can be returned. This field is ignored by the Item Specifics XSL and will be deprecated in a future version. Instead, applications should rely on the attribute's Value.id field and the Value.Name field, which contains the actual year value (e.g., "2003").
...Row.Widget.Message 
String
Generic message to be displayed along with the widget.
  • quadrant (string): Position of the message relative to the widget. Possible values:
  • Top = Above the widget
    Bottom = Below the widget
    Left = To the left of the widget
    Right = To the right of the widget
  • size (integer): Font size of the message
...Row.Widget.TextMessage 
String
Information or instructions associated with the presentation of the characteristic set. This only appears when the Widget.type value is text_message.

Item Specifics Widgets

The presentation instructions for each attribute are grouped in a Widget node. That is, the Widget defines the layout of each attribute. Widgets are organized into rows (Row nodes). The order in which the Row elements appear is the order in which the user-interface elements should appear in an application, from the top down. Usually, there are one or two widgets in a row, but the design can vary for different characteristic sets.

Figure 23-17 The Widget Model

Each widget specifies whether it is for a plain text message (type="text_message"), an attribute (type="normal"), or a date (type="date"). If it is for an attribute, the Widget node contains an Attribute node that specifies the attribute ID (e.g., 40 for Event Type) and defines the layout of the attribute. For example, it includes an Input element that defines the type of input (e.g., dropdown) that should be used to render the values for the particular attribute, a Label that specifies the label's font, and the location (quadrant) where the attribute name should appear in relation to the input element.

Note: Although the Widget node specifies a type and font, these values can be manipulated by means of the XSL returned by the GetAttributesXSL call and an XSL file that overrides these formats. See Working with the Item Specifics XSL Stylesheet.

Some widgets include additional information, such as the initial value (InitialValue) that should be displayed (identical to the values in the SelectedAttributes node described earlier) or important messages (Message) related to the attribute.

Example 23-9 Widget Nodes in ROW Nodes
<PresentationInstruction> 
  <DomainName>Tickets</DomainName> 
  <Row> 
    <Widget type="text_message"> 
      <TextMessage>To enable your item to appear in the Tickets Product Finder search 
results, 
        enter the Item Specifics below.</TextMessage> 
    </Widget> 
  </Row> 
    <Row> 
    <Widget type="normal"> 
      <Attribute id="40" quadrant="top"> 
        <Label face="Verdana,Geneva,Arial,Helvetica" size="2"/> 
        <Input type="dropdown"/> 
      </Attribute> 
    </Widget> 
    <Widget type="normal"> 
      <Attribute id="37" quadrant="top"> 
        <Label face="Verdana,Geneva,Arial,Helvetica" size="2"> </Label> 
        <Input type="dropdown"/> 
      </Attribute> 
    </Widget> 
 </Row> 
  ... more Row nodes ... 
  <Row> 
    <Widget type="normal"> 
      <Attribute id="9" quadrant="top"> 
        <Label face="Verdana,Geneva,Arial,Helvetica" size="2" required="true"/> 
        <Input type="dropdown"/> 
      </Attribute> 
      <Message quadrant="bottom" size="1">Based on the Venue State/Province you select, 
you may be required to enter Face Value on the next page.</Message> 
    </Widget> 
    <Widget type="normal"> 
      <Attribute id="10" quadrant="top"> 
        <Label face="Verdana,Geneva,Arial,Helvetica" size="2"/> 
        <Input type="dropdown"/> 
        <InitialValue>Please Choose State</InitialValue> 
      </Attribute> 
    </Widget> 
  </Row> 
  ... more Row nodes ... 
</PresentationInstruction> 

Promotional (Promo) Message Elements

In addition to the attribute data and presentation instructions, some characteristic sets can include promotional messages that should be displayed in the Item Specifics section of an application. These messages typically contain special discount offers, legal information, and other information.

To ensure that users see this important information, the string that appears in the PromoTop element should always be displayed at the top of the form or screen, and the string in the PromoBottom element should be displayed at the bottom.

The following diagram illustrates how the promotional messages relate to other sibling elements.

Figure 23-18 Promotional Information Elements

GlobalSettings Element

Table 23-9 describes the elements contained in the GlobalSettings node in the Item Specifics XML.

The GlobalSettings node describes the localized month formats that are supported in Item Specifics. This node is always returned, even when no characteristic set meta-data is returned.

Table 23-9
Element
Data Type
Meaning/Notes
BaseHtmlPath 
String
Base path for URLs of help pages on the eBay site to which the request was sent. Used by the Item Specifics SYI XSL stylesheet when rendering links to help pages.
MonthAscendingLong 
String
List of months in ascending order. Specifies the long form of the month names (e.g., December), which are localized for the specified site ID.
MonthAscendingShort 
String
List of months in ascending order. Specifies the abbreviated form of the month names (e.g., Dec), which are localized for the specified site ID.
MonthDescendingLong 
String
List of months in descending order. Specifies the long form of the month names (e.g., December), which are localized for the specified site ID.
MonthDescendingShort 
String
List of months in descending order. Specifies the abbreviated form of the month names (e.g., Dec), which are localized for the specified site ID.

The following snippet shows an example of the global settings for the US site (SiteId = 0), formatted here on separate lines to make it easier to read.

Example 23-10 The GlobalSettings Node
<GlobalSettings> 
  <MonthAscendingLong> 
January;February;March;April;May;June;July;August;September;October;November;December; 
  </MonthAscendingLong> 
  <MonthDescendingLong> 
December;November;October;September;August;July;June;May;April;March;February;January; 
  </MonthDescendingLong> 
  <MonthAscendingShort> 
    Jan;Feb;Mar;Apr;May;Jun;Jul;Aug;Sep;Oct;Nov;Dec; 
  </MonthAscendingShort> 
  <MonthDescendingShort> 
    Dec;Nov;Oct;Sep;Aug;Jul;Jun;May;Apr;Mar;Feb;Jan; 
  </MonthDescendingShort> 
  <BaseHtmlPath><![CDATA[http://pages.ebay.com/]]></BaseHtmlPath> 
</GlobalSettings> 


< Back Next >


 
Attributes & Catalogs > Attribute and Product Finder Content Models > The Attribute Meta-Data Model 
© 2005–2007 eBay Inc. All rights reserved.