Asset metadata

In this section we explain what metadata is and the process for creating the schema - the definition of your metadata. We also cover the process of creating and updating metadata.

What is metadata?

Metadata provides a way for you to store additional information, such as product data, with assets. There are three main use cases for metadata:

• Improving searchability of assets in Content Hub - product metadata is one example

• Providing data to improve front end experiences - we use this to implement Point of Interest (POI)

• Providing data to assist automated processes, to identify assets and provide data for scripts to operate on

For example, product information might include colors, original and sale prices and product codes. You could add a field to your metadata called "color" and  dynamically build up an Autumn fashion collection by including all the items that had a color of "brown". Metadata could also be used for original and sale prices, allowing you to retrieve the sale price from your inventory system, updating this information in the asset's metadata and displaying this on your site.

Metadata can be retrieved using the Dynamic Media API, as explained on the Dynamic Media playground and shown in the example below.

https://cdn.media.amplience.net/i/ampproduct/brown-hat-image.json?metadata=true

In order to access metadata it must be provisioned on your account. Any custom schemas need to be enabled as part of the provisioning process, which would then allow customers to retrieve this metadata using the Dynamic Media API.

Metadata can also be displayed, edited and searched for in Content Hub.

Managing metadata

The process for defining your metadata schema and subsequently adding metadata to your assets is as follows:

• Define your metadata schema. See Defining your metadata for more details.

• Once you are sure that the schema contains the information you wish to store with your assets, send the schema definition to your Amplience technical consultant.

• The technical consultant will create a metadata schema using your specification and add this to your OnDemand account.

• A script will be created to add metadata to assets using this schema. This script will process a file that you supply containing the assets and the metadata to add.

Note: that the metadata schema cannot be modified once it has been added to your account.

To process for adding metadata to assets is explained on the Adding metadata to assets page. A brief summary of the process is as follows:

• Upload a pipe ("|") delimited CSV file to a folder at an agreed location (usually the Amplience FTP server). This file specifies which assets to add metadata to the required values.

• The metadata CSV file will be processed automatically and metadata will be added to the specified assets. The asset is then published with the new metadata.

Defining your metadata

We refer to the definition of your metadata as the schema. When you specify your schema you need to define the name and label. The name will be used to refer to the metadata using the API and the label defines the friendly name that will appear in Content Hub.

In the example below the label for the schema is "Tutorial Schema".

Your schema will contain one or more fields and for each you need to specify the name, label and type.

note

The name of any field in your metadata cannot be the same as the name of the schema.

The following types of fields are supported:

• string

• integer  (does not include decimals)

• number (can include decimals)

• boolean (this field type is also facetable, see the definition below)

Searchable and facetable strings

For string fields you should also consider if the field should be searchable or facetable.

If a string field is searchable it means that natural language searching is used for a full or partial string without the need to use wildcards. For example, if a field contains the string "spring collection" then searching for "spring", "coll" or "collection" will return the asset containing this string.

A facetable field is one that can be searched and filtered from a limited number of options. An example is a "color" field, where the range of available values is limited to the range of colors entered.

An example of filtering an asset using a facetable field in Content Hub is shown below. The facetable field is highlighted and one of the values available to search on was "brown". The assets returned from the search have "color" set to this value.

An indexable string can be searched, but only exact text matches will return the associated assets. You can also use wildcards (*) to do wildcard searching. All fields are indexable.

Defining string format

The format of a string will determine whether the field is searchable and facetable.

The following formats are supported for the string type:

• symbol (use this to make the text facetable)

• text

• multiline-text

• date-time (will display a UI in the field allowing user to choose date and time)

These string formats specify whether a string is indexable or facetable as shown in the table below.

Format	Searchable	Facetable
symbol	false	true
text	true	false
multiline-text	true	false
date-time	false	false

Supplying the metadata

The process for adding the metadata to your account is as follows:

• Define your metadata. Consisting of fields of the types shown above.

• Send this to your Amplience technical consultant. See below for an example schema.

• The technical consultant will use the information you provided to add the metadata to your account.

• You can then test the metadata to make ensure that it meets your requirements.

Example

In this example we want to add the following metadata: color, original price and sale price. The original price and sale price will be retrieved from an inventory system and updated during a sale promotion. The schema name will be "tutorial_schema" and the label (as it appears in Content Hub) is "Tutorial Schema".

The Original and sale price fields should be of type number.

The color field should be facetable, so it is defined as a string type with format symbol.

The schema can be defined as follows (you may find it easiest to send it to us in a spreadsheet or whatever format you find convenient):

Schema name: tutorial_schema

Property:
  name: original-price
  label: "Original Price"type: number

Property
  name: sale_price
  label: "Sale Price"
  type: number

Property
  name: color
  label: "Color"
  type: string
  format: symbol

Once a metadata schema has been added to your account it cannot be deleted, so it is worth spending time on the definition of your schema before asking for it to be added to your account.

Your technical consultant will use this information to add the metadata schema to your account.

Adding metadata to assets

Once the metadata schema has been added to your account, the process for adding or updating asset metadata is as follows:

• Supply a pipe ("|") delimited CSV file of metadata exported from your product inventory system. This would include the name of the asset together with values for each of the required fields.

• Upload this file to the specified location.

• A script is run automatically to parse the metadata file, create the metadata, assign it to each asset and publish the updated asset.

On this page we'll explain each part of this process in more detail.

You can also add metadata to an asset manually using Content Hub. See Adding metadata using Content Hub.

Metadata file structure

Your technical consultant will specify the location to which you should upload the metadata file. The script to parse this file and create the metadata will run automatically every hour. You might also choose to upload the file to a location within your FTP server. The script will check for a file in the specified location, so the location should not change once it's specified.

The folder structure will be agreed with your technical consultant, but it will generally be something like.

Metadata

  toprocess

    metadata1.csv

    The metadata file that you upload

  processed

    metadata1-{timestamp}.csv

    Created by the script and containing the metadata successfully added

  invalid     invalid-{timestamp}.csv

    Contains a file generated by the script that specifies any metadata that failed the script's validation. See below for more details.

Format of the metadata file

The metadata file contains the name of the asset, together with the values for each of the metadata fields. There are some important rules to note:

• Each field is delimited with the pipe symbol "|"

• All fields must be contained within "" quotes. Even number fields will be treated as strings within the CSV file

• All fields must be supplied. Empty string fields are represented by empty quotes ""

Example

In the example introduced on the Defining your metadata schema page, there are three fields: original_price,sale_price and color. Here's an example of a metadata CSV file that adds metadata to assets using this schema. The file will contain the name of each asset, together with values for each of the fields:

"3256543_short_black_dress"|"29.99"|"19.99"|"black"|"3256548_signature_summer_dress"|"29.99"|"19.99"|"green"|
"3256548_winter_coat"|"99.99"|""|"white"|"3256555_fashion_mirror"|"49.99"|"39.99"|""

The metadata CSV file is limited to 10000 lines. If you wish to add or update metadata for more than 10000 assets, then you would need to break this up in to multiple import jobs.

Deleting metadata

To delete metadata from an asset, include "Delete" in the metadata file, followed by the name of the asset:

"Delete"|"3256543_short_black_dress"

Processing the metadata file

When the metadata file is processed, the script will validate each of the field values you supply. Values that would fail the validation include field length, an unrecognised date format and letters in a numeric field, for example. The details of the assets to which metadata has not been added or updated will be written to a file contained in the "invalid" folder shown in the folder structure above.

Whenever metadata is added to an asset or updated, the asset must be re-published. This ensures that the latest version of the asset, including the metadata, is published to the Content Delivery Network (CDN) and available to your users. Newly created metadata will be available immediately. If you are updating an asset's metadata, then the older version of the asset may be cached in the CDN and not served to your users for up to 24 hours (depending on your "Time to Live" (TTL) settings). Similarly if you delete metadata from an asset, this change may not be available immediately.

Adding metadata using Content Hub

In most cases metadata will be added to an asset using an automated script. However, sometimes you may wish to add the metadata manually using Content Hub.

Open Content Hub and select the asset to which you wish to add the metadata. Right click the asset to display the settings menu and select the "Metadata" item.

The metadata pane is opened to the right of the asset. On the left hand side of this pane you'll see a list of the metadata sets that can be used with this asset. In this case we want to add metadata using "Tutorial Schema" so we click the name of the metadata set to select it.

Tutorial Schema defines three fields: color, original price and sale price. Add values for each of these fields (or leave them empty as required).

Entering metadata

The value entered in each field will be validated and saved when you click away from each field. No message will be displayed if a value is not valid- if you enter letters in a numeric field, for example, so you should check the values where the metadata pane is redrawn.

Once you have entered values for the Tutorial Schema shown above, refresh the pane by clicking on another metadata set (such as Image or EXIF) and then back to Tutorial Schema.

Some string fields, such as "color" defined in the Tutorial Schema, are facetable. This means that is easy to search and filter on this value from a limited number of options entered by the user. The values entered in this field are case sensitive, so if you entered "black" for the hat image above and then entered "Black" for the color for another asset, then two separate facets would be created. We recommend picking a consistent naming scheme for your fields to avoid this problem.

Related pages

Dynamic Media playground