Metadata Definitions

Metadata Definitions allow administrators to define the data structure for assets within a specific Asset Class. By configuring these fields, you determine what information users must provide when uploading assets and how that information is displayed, searched, and linked across the platform.

This feature is essential for maintaining data integrity, enabling advanced filtering in the gallery, and creating relationships between assets through shared metadata values.

Page Overview

• Purpose: To define the schema and validation rules for asset information.
• When to use it: Use this page when setting up a new Asset Class or when you need to add, modify, or remove data fields for existing assets.
• What you can do here:
  • Create new metadata fields with specific data types (String, Date, Boolean, etc.).
  • Configure multilingual support for text fields.
  • Set up cascading dependencies between vocabulary fields.
  • Designate fields as "Quick Filters" for the gallery.
  • Define default values and help text for users.

Page Layout

• Top bar: Displays the "Metadata Fields" title, the specific Asset Class being edited, and the Add Field button.
• Main area: A table listing all defined fields, showing their Type, Multilingual status, Required status, and associated Vocabularies.
• Right panel / dialogs: Contains the "Add/Edit Field" form and the "Type Change Warning" dialog for managing data migrations.

Main Features

Field Type Configuration

• What it's for: Assigning a specific data format to a field (e.g., Integer, Date, Vocabulary).
• Typical use: Choosing "Date" for a "Production Date" field to ensure users use a calendar picker.
• Result: The system enforces the correct input format during asset editing and upload.

Cascading Vocabularies

• What it's for: Creating a parent-child relationship between two vocabulary fields.
• Typical use: A "City" field that only shows options based on the selection in a "Country" field.
• Result: Users see filtered, relevant options, reducing data entry errors.

Promoted Filters

• What it's for: Elevating a metadata field to a primary search control.
• Typical use: Setting a "Department" vocabulary as a quick filter.
• Result: The field appears as a one-click filter next to the main gallery search bar.

Bulk Paste Search

• What it's for: Letting users paste a long list of identifiers (SKUs, product references, supplier codes) into a single smart filter rule. See Bulk Paste Search for the end-user view.
• Typical use: Enabling Allow bulk paste search on a product_reference text field.
• Result: When users pick that field in Advanced Filters with the Is one of operator, they get a paste-list textarea (up to 1000 values) and a CSV export of unmatched values.

Sensitive Information Toggle

• What it's for: Marking fields that contain private or restricted data.
• Typical use: Hiding "Internal Cost" from standard users.
• Result: Access to view or edit the field is restricted based on user permissions.

Detailed Feature Documentation

Adding or Editing a Field

• Purpose: To define the properties and behavior of a metadata attribute.
• Where to find it: Click the Add Field button in the top bar, or click the Edit icon in the "Actions" column of an existing field.
• What you'll see: A large dialog containing tabs for multilingual labels and various configuration checkboxes.

How to use it:

1. Enter the Label in the default language; the Key will auto-generate (e.g., "Asset Title" becomes asset_title).
2. Select a Type from the dropdown (e.g., String, Text, Int, Date, Vocabulary).
3. If using "Vocabulary", select the specific Vocabulary source from the list.
4. Toggle functional settings like Required Field or Multilingual Support.
5. Click Add Field or Update Field to save.

Managing Type Changes

• Purpose: To safely change the data type of a field that already contains data.
• Where to find it: Change the Type dropdown while editing an existing field.
• What you'll see: A warning dialog showing how many assets are affected and whether the change is "Allowed" or "Blocked."

How to use it:

1. Select a new type in the Edit Field dialog.
2. Review the "Impact Information" in the warning popup.
3. If the change is safe, click Confirm Change.
4. If the change has significant impact, click Proceed Anyway (if available) or Cancel to revert.

Complete Workflows

Workflow: Create a Cascading Vocabulary Field

• Goal: Set up a "Sub-Category" field that depends on a "Category" selection.
• Prerequisites: Both fields must use the same Vocabulary source. The "Parent" field must already exist.

Steps:

1. Click Add Field in the Top bar.
2. Select Vocabulary from the Type dropdown.
3. Select the appropriate Vocabulary from the list.
4. Under Cascading Configuration, select the "Category" field from the Parent Field dropdown.
5. Set the Term Depth to "Level 2 (first children)".
6. Click Add Field.

• Expected result: When users edit an asset, the "Sub-Category" field will remain disabled until a "Category" is selected.

Workflow: Promote a Field to Gallery Quick Filter

• Goal: Make a specific metadata field easily accessible for filtering in the main gallery.
• Prerequisites: The field must be of type Vocabulary.

Steps:

1. Locate the field in the Main area table and click Edit.
2. Check the box labeled Show as quick filter in gallery.
3. Click Update Field.

• Expected result: A new filter dropdown appears next to the search bar in the Asset Gallery.

Workflow: Enable Bulk Paste Search on an Identifier Field

• Goal: Let users paste a list of SKUs, product references, or other identifiers directly into a smart filter and look up every matching asset at once.
• Prerequisites: The field must be of type Text, Long Text, Number, or Float. (Vocabulary, Date, Boolean, and JSON fields are not eligible.)

Steps:

1. Locate the field in the Main area table and click Edit.
2. Check the box labeled Allow bulk paste search.
3. Click Update Field.

• Expected result: When users open Advanced Filters, pick this field, and choose the Is one of operator, they see a multi-line paste textarea instead of the regular single-value box, plus a "matched of pasted" summary and a CSV export for unmatched values. See Bulk Paste Search for the end-user walkthrough. The 1000-value cap is configurable via the BULK_PASTE_LIMIT environment variable.

Who can use it

Managing metadata definitions requires the dedicated "Metadata Definitions" administrator permission. Users with only the asset-viewing permission can see the resulting fields on assets, but cannot add or modify them.

Field types available

When adding a field, you can choose from eight data types:

• Text for short strings
• Long Text for multi-line content
• Number for whole numbers
• Float for decimal numbers
• Boolean for yes/no toggles
• Date for calendar values
• JSON for structured data
• Vocabulary for a value picked from a controlled list

Only fields of type Vocabulary can be promoted to a quick filter in the gallery, linked to a parent cascade, or constrained to a specific depth in a hierarchical vocabulary (up to 10 levels deep).

Limits and guardrails

• Deletion is blocked when in use: A metadata field cannot be deleted while any asset still has a value stored in it. Clear or migrate that data first, then retry the deletion.
• Type change safety net: Changing a field's type triggers an impact check that counts how many assets would be affected and whether the data can be safely reinterpreted in the new type. If the conversion is unsafe (for example, text containing letters into Number), the save is blocked with a clear reason. Compatible changes are allowed and applied.
• Cascading rules: A child cascading field must point to a parent field that lives in the same asset class and uses the same vocabulary. A field cannot be its own parent, and the system detects and rejects circular chains (A → B → A).
• Quick filter toggle is Vocabulary-only: The "Show as quick filter in gallery" checkbox is automatically ignored for non-vocabulary types.
• Bulk paste toggle is scalar-only: The "Allow bulk paste search" checkbox is offered on Text, Long Text, Number, and Float fields, and is automatically cleared if a field's type is changed to one that isn't eligible.

What happens behind the scenes

• The Key is auto-generated from the label using underscores. Once set, it acts as the stable identifier for that field across the platform and in any API integrations, so editing it after data has been captured can disrupt downstream systems.
• Translations you enter for field labels are saved per language. Removing a language from the translation list on update also removes the stored translation for that language.
• The list of fields on this page is ordered by the translated label in your current interface language, so admins browsing in different languages see the fields sorted for their own locale.

Tips and Best Practices

• Key Naming: The system uses underscores for keys (e.g., project_name). Avoid manual edits to the key unless you have a specific naming convention requirement.
• Default Values: Use the Default Value field to speed up data entry for common values, such as setting a "Copyright" field to your company name by default.
• Help Text vs. Field Hint: Use Help Text for long-form instructions (appears as a tooltip) and Field Hint for short, immediate guidance (appears below the input).

Troubleshooting

Issue: Cannot change a field type

• Symptoms: The "Confirm Change" button is disabled, and a red "Type Change Blocked" message appears.
• Cause: The new data type is incompatible with existing data (e.g., trying to change a "Text" field containing letters into an "Integer" field).
• Fix: You must either delete the data from that field in all assets or create a new field with the correct type and delete the old one.
• Prevention: Finalize your data model before uploading large batches of assets.

Issue: Vocabulary field is empty

• Symptoms: The "Vocabulary" dropdown in the Add Field dialog says "No vocabularies available."
• Cause: No vocabularies have been defined in the system yet.
• Fix: Navigate to the Vocabularies administration page and create at least one vocabulary before returning to Metadata Definitions.