Skip to content

use-structured-metadata.md

Latest commit

 

History

History
71 lines (52 loc) · 2.24 KB

use-structured-metadata.md

File metadata and controls

71 lines (52 loc) · 2.24 KB
Raw

Use structured metadata

When to use

Attach typed, validated business fields (SKU, campaign, rights expiry) to assets, so applications can filter and route on a stable schema instead of free-form tags.

Define a field (once, per product environment)

const cloudinary = require('cloudinary').v2; // reads CLOUDINARY_URL

await cloudinary.api.add_metadata_field({
  external_id: 'sku',
  label: 'SKU',
  type: 'string',
  mandatory: false
});

Field types include string, integer, date, enum, and set (enum/set take a datasource of allowed values).

Write values on an asset

// At upload time:
await cloudinary.uploader.upload('https://res.cloudinary.com/demo/image/upload/sample.jpg', {
  public_id: 'examples/product-photo',
  overwrite: true,
  metadata: { sku: 'SKU-00042' }
});

// Or later:
await cloudinary.uploader.update_metadata({ sku: 'SKU-00042' }, ['examples/product-photo']);

Query by metadata

const result = await cloudinary.search
  .expression('metadata.sku="SKU-00042"')
  .execute();

Pattern: analysis to reviewed metadata

A common pattern for turning model output into data you can rely on:

  1. Run AI analysis on the asset (captioning, tagging — for example the Analyze API, subscription required).
  2. Normalize the output against your schema — map free-form values onto your allowed list, drop low-confidence results, apply business rules.
  3. Write the resulting values as structured metadata.
  4. Search, route, and deliver based on that metadata.

Step 2 is where the value is: structured metadata fields are typed and validated, so whatever you write has to conform. Automate it when the rules are clear and route to a person only for the cases your rules cannot decide.

Troubleshooting

  • external_id already exists — field definitions are per-environment and permanent; reuse the existing field instead of re-creating it.
  • Enum/set writes fail when the value is not in the datasource — update the datasource first (api.update_metadata_field_datasource).

Related