Dsco Catalog Attribution File Guide

• Overview
• More Help
• Core Concepts
• Core File Concepts
• Publish, Revision, Active Catalogs
  • Overview
  • Publishing A Catalog
  • Making a Catalog Revision
  • Making An Active Catalog
• Tsv File Format
  • Rows 1 & 2 - Catalog File Format
  • Row 3 Category Attribute Headers
  • Rows 4+ Category Attributes
  • Image Category Attributes
    • Dsco Image Array
    • Image Name Row
    • Export Name Rule Row
    • Export Sizes Row
    • Export Rules Row
    • Image Name Rule Dynamic Fields
    • Image Rules

Overview

Customers may upload a TSV file representing the nested categories, with associated attributes, that comprise the catalog into Rithum's Dsco platform to create and update a catalog. Dsco will then use this catalog information as part of the catalog workflow to validate item catalog data conforms to the rules implied by the customer's catalog.

More Help

After reading this document, feel free to reach out to Rithum's Dsco platform support by sending an email with additional questions to support@dsco.io.

Core Concepts

• Retailer
  The Dsco platform customer who is using Dsco's catalog attribution feature to define a catalog and its associated categories and attributes.

• Supplier
  A trading partner of the Retailer who will provide item catalog data, marked for one or more categories, which then must provide valid attributes appropriate to the given category(s).

• Catalog
  A named group of nested categories and the associated attributes for each.

• Catalog Name
  The name associated with a catalog. Customers may maintain multiple catalog versions at the same time, although currently only one version may be active, which is the version that item catalog data will be validated against.

• Attribute
  A named value, associated with a specific Category Path, that specifies the Attribute Type and whether the attribute value will be required, recommended or optional for items associated with the given category to which the attribute is associated.

  Note that the attribute names are case sensitive and are preserved by Dsco. So, these two attributes are different and may both be present at the same time because one starts with a lowercase letter and the other with an uppercase letter...

  size, Size

  If a supplier provided an item with a size attribute, note the lowercase, then the size attribute would be used to validate it and not the Size attribute.

  Note the following rules for providing valid attribute names...

  • The name may only be comprised of alphanumeric characters and the underscore character: a-z and A-Z and 0-9 and _

  • The name may not contain white space characters, e.g. a space

  • The name may not start with a number

  • The name may not start with an underscore

• Attribute Type
  The precise expected type of value for a given attribute, one of these...

  • Text - string
    Freeform character data.

    The text type is also known as the string type.

  • Number (no decimal) - integer
    A numeric value without a decimal value.

    This type is also known as the integer type.

  • Number (decimal) - float
    A numeric value with a decimal value

    This type is also known as the float type.

  • true/false - boolean
    The value must be the word true or the word false.

    This type is also known as the boolean type.

  • One Of - enum
    Indicates that the attribute's value must be one of the provided set of values, so if the One Of type designates that only red, green and blue are allowed values then any other provided values are invalid.

    Note that the one of type is also known as the enum type.

  • List - array
    Indicates that the attribute's value will be a list of possibly more than one value where each value in the list must conform to the type specified in List of Type.

    Note that a list type is also known as the array type.

  • List of Type
    If the attribute's type is a List then List of Type is used to specify the expected type of each value in the list.

• Category
  A category is a name (and the associated attributes) in a nested hierarchy of names used to group like products/items, for example...

  Apparel||Shoes||Women's Shoes

  The above represents a category named Apparel that contains another category named Shoes that itself contains another category named Women's Shoes. Suppliers would then provide an item with catalog data that first indicates the category(s) the item is within and then also includes the catalog attribute data specific to that category.

  In this example, Apparel is the parent category of Shoes. Shoes is a child category of Apparel.

• Category Path
  The complete set of categories, separated by ||, that delineates a location within the hierarchy of catalog categories to which attributes may be defined and items may be associated.

  The following is a category path that together defines a specific category in the catalog hierarchy to which items may be associated...

  Apparel||Shoes||Women's Shoes

• Category Attributes
  The set of attributes that an item within the given category may/must provide with the exact definition of what value(s) may be provided.

  • Inherited Attributes
    These are attributes that are present as an attribute of a category because a parent category defined them.

    Given the following category path... Apparel||Shoes||Women's Shoes

    And given that the Apparel category designates a required attribute named size whose type was a number, then all categories that are contained within the Apparel category will inherit the size attribute. Thus, an item associated with Apparel||Shoes must include the required size attribute as would any item associated with the Apparel||Shoes||Women's Shoes category and so on.

  • Overridden Inherited Attributes
    These are inherited attributes that are redefined by a child category. Note that child categories may make a required overridden attribute not longer required.

    Given the example in the Inherited Attributes section above, assume that the Women's Shoes category nested within Apparel||Shoes wanted to have the size attribute as a string. The Apparel||Shoes category would simply include the definition of size again and this time change its type to a string.

• Image
  Please reference the Image Category Attributes section for additional information.

  Retailers need to tell suppliers what images to provide, the image definition which is the name of the image, the dimensions and possibly some additional metadata. Suppliers need to be able to provide the required image(s) and allow Dsco to resize them if they are not the correct size.

  An image may be placed at the root of the catalog tree, meaning that all items must have the image, or they may require different images in different categories of the catalog tree.

  Suppliers will not provide images in an ItemCatalog object's extendedAttributes property. Instead, suppliers will use the existing images arrays already defined in the Dsco schema for an ItemCatalog object.

  An image type is defined by the retailer having one of these properties in the catalog attribution information...

  • name: string (required)
    A name both the retailer and supplier will use to reference the image by

  • export name_rule (optional)
    The name that should be used when the retailer requests this image which may include some dynamic elements including the name, image dimensions and so forth

  • export sizes (optional)
    The size(s) the retailer wants generated from the image provided by the supplier; if not provided then the image is returned with whatever size the supplier provided

  • export rules (optional)
    Rules provided by the retailer that will govern whether or not Dsco will accept the image provided by the supplier

The supplier then can do one of two things, depending on what the retailer allows. If the retailer has designated a template image, then the supplier need only provide the name/url of the template image and the Dsco platform will take it from there and create the other required/optional images the supplier didn't provide. Otherwise, the supplier need only provide the name/url of each required image and any other optional images desired.

Core File Concepts

• TSV Delimiter Format
  While the Dsco platform may in the future accept comma delimited files, the use of commas as a delimiter caused issues with suppliers and so Dsco will only officially support receiving tab delimited files - TSV.

• Global Inherited Attributes
  You may create attributes that apply to all categories in the entire catalog, say an html_description attribute. These are defined as attributes of the catalog itself, not of a specific category.

  In the TSV file format, use this special category name to indicate that an attribute should be associated with the catalog itself and thus apply globally to all categories of the catalog...

  {catalog}

• Additional Attribute Rules
  These are additional properties to further constrain the valid values for an attribute.

  • Range
    Specifies that a numeric value must be in the given range, as in...

    // This means the value must be greater than 5
    >5
    
    // This means the value must be greater than 5 and also less than 100
    >5 AND <100
    

    You use a > or < symbol followed by the number, optionally followed by the word AND if specifying an ending range value.

    You may only use the Range type property on numeric attribute types.

  • Length
    Specifies that the attribute value must be a certain number of characters, as in...

    // This means the value must be less than 4 characters long
    // so the value abc is valid but the value abcd is invalid
    // since it isn't less than 4 chars long
    <4
    
    // This means the value must be between 5 and 100
    // characters long, so abcdef is valid but abc is not valid
    >5 AND <100
    

    You use a > or < symbol followed by the number, optionally followed by the word AND if specifying an ending length range value.\

    You may only use the Length type property on text or numeric attribute types.

  • Pattern
    Specifies the single regular expression pattern to validate the attribute value against.

    Dsco uses the Javascript Regular expression syntax as defined here.

  • Multi-pattern
    Specifies multiple regular expression patterns, where the first pattern must match and then OR, AND or NOT may be used to create complex groups of patterns.

    // This means the value may contain any alphabet characters
    // but may not be the word Samsung or the word Google
    /^a-zA-Z$/ :NOT: /^Samsung/ :OR: /^Google/
    

    Dsco uses the Javascript Regular expression syntax as defined here.

  • require
    Add this additional rule on an attribute to cause one or more other attributes to be required only when a certain condition is met on the first attribute.

    // make hue required when the attribute has a value
    conditonally_require: exists :THEN: hue
    
    // make Dsco's upc attributed required when the attribute
    // doesn't have a value
    conditonally_require: not_exists :THEN: dsco.upc
    
    // make two attributes required when this attribute is blue
    conditonally_require: this = \'blue\' :THEN: blue_field_1 :AND: blue_field_2
    
    // make one of two attributes required when this attr is blue
    conditonally_require: this = \'blue\' :THEN: blue_field_3 :OR: blue_field_4
    
    // make a certain named image required when attr is blue
    conditonally_require: this = \'blue\' :THEN: dsco.images.color_image
    

Publish, Revision, Active Catalogs

Overview

A catalog is uniquely identified by its name. When a customer uploads a catalog with a name that the Dsco platform has never seen before, Dsco will create the catalog in a "draft" state known as a catalog revision. If a customer uploads a catalog with the same name, it will be merged over the top of the existing catalog revision, the one that is in draft mode. Any category that is present in the catalog will overwrite any categories and subcategories and their respective attributes.

Publishing A Catalog

At any time, a customer may choose to "publish" a catalog revision, one that is a draft catalog, using the Dsco platform portal. A published catalog cannot be modified and exists in a read-only mode. Suppose that a customer uploads her first catalog, named "Fall 2020", to Dsco. This catalog will exist as the one draft revision for that name "Fall 2020." The customer then clicks the publish button on that catalog, publishing the catalog. What will happen if the customer wants to continue to make changes to the "Fall 2020" catalog? Will that newly published catalog and the rules derived from its categories and attributes be shared with the customer's trading partners to validate item catalog information?

Making a Catalog Revision

Taking these questions in order, the customer may not edit the published version of the "Fall 2020" catalog. However, the Dsco platform portal web page for Catalog Attribution has a button named "Make a revision" that will make a draft copy of the selected catalog. Then, the customer may make changes to the draft copy. When done making changes, the customer may click the publish button to publish the draft revision and make it the one published version of the "Fall 2020" version, completely overwriting the current "Fall 2020" published version. Note there may only be one draft revision of a named catalog at a time.

There is another way to make a revision of a catalog. Let's assume that the "Spring 2021" catalog exists as a published catalog and that there is currently no draft revision. If the customer uploads a catalog whose name is "Spring 2021" the newly uploaded file will be created as the draft revision of the "Spring 2021" catalog.

Making An Active Catalog

Now that there is a published "Fall 2020" catalog, it needs to be made the "active" catalog in order for the Dsco platform to begin using the catalog's categories and attributes to validate item catalog information provided by the customer's trading partners. The Dsco portal's Catalog Attributions page includes a "Make active catalog" button next to catalogs that are published. Although any number of catalogs may be "published" only one of the published catalogs may be active at a time. This is because only one catalog's categories and attributes may be used to validate the item catalog information provided by the customer's trading partners. The customer may at any time make a different published catalog the one active catalog used for validation.

Tsv File Format

Note that the examples below will use a comma as the delimiter for the sake of clarity even though Dsco recommends using the tab character to delimit values in TSV files.

Rows 1 & 2 - Catalog File Format

The first row of the file, called the Catalog File Format row, defines the columns for the Catalog File Format while the 2nd row defines the values for the Catalog File Format, as in...

format,catalog_name,publish_and_make_active,catalog_is_complete,,,,,,
dscoCatalogAttribution-1.0,Fall 2021,true,false,,,,,,

• format
  The Dsco version of the TSV file, today must be the exact value dscoCatalogAttribution-1.0

• catalog_name
  The customer-provided name of the catalog this file's categories will be created or updated within.

  In the example above, this is the catalog_name value, meaning the catalog name that this catalog information will be identified by inside of Dsco...

  Fall 2021

• publish_and_make_active
  A boolean value, either true or false. If true then Dsco will automatically publish and activate the catalog attribution data when it is sent to Dsco.

• catalog_is_complete
  A boolean value, either true or false. If true then any existing category data for the given catalog_name will be completely replaced by the categories contained in this file.

  If false, then any category specified in this file will replace the existing category and its attributes, if there is an existing catalog with the same name contained in catalog_name.

• commas to equal total columns so remains a valid TSV file

Row 3 Category Attribute Headers

The third row of the file, called the Category Attribute Headers, provides the name of the category header columns, as in...

category,attribute_name,attribute_dscription,required_type,data_type,secondary_data_type,possible_values,additional_rules,category_is_complete,is_dsco_schema

• category
  Required. The Category Path that identifies where the given attribute will be associated.

• attribute_name
  Required. The name of the attribute to create/replace (see the Core Concepts Section Attribute bullet for info on valid attribute names).

• attribute_description
  Optional. A description for the attribute that will be shown to the suppliers to help them understand what the attribute is for.

• required_type
  Required. Whether the attribute is required, one of these values...

  • required
    Dsco's validation system will treat any missing required attribute of an item provided by a supplier as an error and not flow the associated item that is missing this attribute to the retailer

  • recommended
    Dsco's validation system will treat any missing recommended attribute of an item provided by a supplier as a warning, notifying the supplier of the warning, but will flow the item catalog data to the retailer

  • optional
    Dsco's validation system will treat any missing optional attribute of an item provided by a supplier as an info, notifying the supplier of the info, but will flow the item catalog data to the retailer

• data_type
  Required. Specifies the type of value for the attribute being defined (see the Core Concepts Section Attribute Type bullet). One of these values...

  • string
  • integer
  • float
  • boolean
  • array
  • enum

• secondary_data_type
  Required when data_type is array or enum. Should not be provided otherwise.

  When the data_type is array or enum, this value specifies the type of the values within the array or the enum, which may only be one of these values...

  • string
  • integer
  • float

• possible_values
  Required when data_type is enum. Should not be provided otherwise.

  When the data_type is enum, this is a double pipe || delimited list of the possible valid values for the attribute, as in...

  Tall||Regular||Petite

  Thus this attribute's value may only be one of Tall, Regular or Petite.

• additional_rules
  Optional. This specifies additional rules to apply to the attribute value (see the Core File Concepts Section Additional Attribute Rules bullet)

  If you want more than one rule, separate them with the double pipe || delimiter as in...

  range: \>5 \|\| pattern_match:/\^\[A-Za-z0-9\\- \]+\$/
  

  • Range Rule

    range: >5
    

  • Length Rule

    length_range: >5 AND <100
    

  • Pattern Rule

    pattern_match:/^[A-Za-z0-9\- ]+$/
    

  • Multi-Pattern Rule

    multi_pattern: /^a-zA-Z$/ :NOT: /^Samsung/ :OR: /^Google/
    

  • Conditionally require rule
    See the conditionally require section above for examples

• category_is_complete
  Optional. This is a boolean value, true or false. If provided and true, it means that the category attributes defined in this file should completely replace any existing category attribute data, deleting any attributes on the existing category of the same name before importing the new category attributes.

• is_dsco_schema
  Optional. A boolean value, either true or false. The customer's supplier trading partners will provide attributes on an Item Catalog object in the attribute of the object named extendedAttributes. However, there may be some occasions where the customer may wish to define an attribute somewhere in the category hierarchy that is part of Dsco's general purpose Item Catalog schema. When this is the case, is_dsco_schema should be true and Dsco will look in the top-level of the object for the attribute of the corresponding name instead of within extendedAttributes.

  For example, Dsco's schema includes a description attribute already as a top-level attribute of an Item Catalog object. By setting this to true, the supplier trading partner would pass in ItemCatalog.description instead of ItemCatalog.extendedAttriutes.default.description.

Rows 4+ Category Attributes

All rows from four on are the actual category attributes themselves. Here are some examples.

// This attribute will be added as a global inherited attribute
// with html_description as its name and with string as its data type
{catalog},html_description,required,string,,,,

// This defines a Size attribute as a string in a top-level category named Clothes
Clothes,Size,required,string,,,,

// This defines a Length attribute of the Shirts category contained
// within the Clothes category whose value must be Tall, Regular or Petite.
Clothes||Shirts,Length,recommended,enum,string,Tall||Regular||Petite,,

// This defines a Style attribute of the Running Shoes category that
// is a string value that must be between 6 and 99 characters in
// length and that may only contain alphanumeric characters
Clothes||Shoes||Running
Shoes,Style,required,string,,,length_range:> 5 AND <100||pattern_match:/^[A-Za-z0-9]+$/

Image Category Attributes

Please read the Core Concepts Section Image bullet if you haven't already.

Partners need to define the images they want their trading partners to provide. Partners will define images a little differently in the catalog attribution file.

Images have a definition, which will include at least an image name and may also include an image export name_rule and image export sizes. Each element of an image definition is a different row in the catalog attribution file.

Here's an example of defining an image called top_view that suppliers must provide on every item in the entire catalog.

Dsco Image Array

The attribute name needs to start with the Dsco schema array name that suppliers will provide the image within. The following delineates the list of Dsco images arrays that may be used...

• images
  images.top_view means suppliers would have to provide an image named top_view in the Dsco images array attribute of the item

• brand_logo_images
  brand_logo_images.top_view means suppliers would have to provide an image named top_view in the Dsco brand_logo_images array attribute of the item

• product_images
  product_images.top_view means suppliers would have to provide an image named top_view in the Dsco product_images array attribute of the item

• swatch_images
  swatch_images.top_view means suppliers would have to provide an image named top_view in the Dsco swatch_images array attribute of the item

Image Name Row

As one can see from the example, the supplier will be required to provide an image named top_view in the item's images array. The attribute name starts with the special images. keyword to let Dsco know that this image will be provided by the partner's trading partners in the Dsco standard images attribute in the root of the item catalog object as opposed to the extendedAttributes section of the item catalog object.

The name of the image, which suppliers will include with the image when they provide it to Dsco, is seen here which is top_view. Of course, any name may be used, top_view is simply an example.

Remember that only the first row in the example above, the row that defines the image name, has to be provided by the retailer in the catalog attribution file to define an image the supplier is meant to give to Dsco with their catalog data.

Below are the exact values for each column of the "name" row of an image in the catalog attribution file. Any column not included below is not used and will be ignored.

Export Name Rule Row

The second row allows the retailer to designate a rule to name the image as to ensure the image is named precisely when exported to the retailer.

Below are the exact values for each column of the "export.name_rule" row of an image in the catalog attribution file. Any column not included below is not used and will be ignored.

Export Sizes Row

The third row allows the retailer to specify the sizes to create from this one supplier-provided image. If this is not provided, the image will be exported using the width/height of whatever was provided by the supplier. Note that if this is not provided then the name rule may not include dim_name, dim_w, dim_h. Note that if the size object names are not provided then dim_name may not be used in an image name rule.

Below are the exact values for each column of the "export.sizes" row of an image in the catalog attribution file. Any column not included below is not used and will be ignored.

Export Rules Row

The fourth row allows the retailer to specify any rules specific to the image provided by the supplier and the supplier image will fail if it does not conform to the provided rules.

Below are the exact values for each column of the "export.sizes" row of an image in the catalog attribution file. Any column not included below is not used and will be ignored.

Image Name Rule Dynamic Fields

The table below delineates every possible field that may be used in an export name rule to help dynamically define the name that Dsco will export the image to the retailer as.

Image Rules

The table below delineates every possible image rule that can be provided by a retailer.