Define a structured metadata schema through MCP

Prerequisites

Connect your client to Cloudinary’s Structured Metadata MCP server and select the product environment whose schema you intend to change. As documented in Cloudinary’s MCP server setup and authentication guide, the remote server uses OAuth, while a local server requires credentials. MCP server access is included on every plan, including Free, as checked on 2026-08-18.

Confirm that you are using the Structured Metadata server rather than adding every available server to the project. The practical differences are covered in the Structured Metadata MCP server guide and choosing MCP servers per project.

Before changing anything, collect the searches, routing decisions, and upload flows that the schema must support. You need those examples to decide which fields deserve to exist.

Steps

1. Write down the queries the schema must answer.

   Start with questions, not field names. Examples might include “Which assets are approved for a named channel?”, “Which items require review?”, or “Which assets belong to a particular campaign?” These are design prompts, not claims about fields every product environment needs.

   For each question, write the values needed to answer it and whether the answer will be used by a person, a saved search, or an automation. Cloudinary’s search method documentation shows that structured metadata can be part of an asset search, as checked on 2026-08-18. That makes search behavior the right starting point for schema design.

   A field nobody filters on is documentation. It may still be worth keeping, but do not pretend it serves retrieval or routing. A field everyone filters on needs a controlled value list; otherwise spelling, punctuation, and naming differences will split one intended category into several values.

2. Reduce the draft to fields with a named job.

   Turn each recurring input from the queries into a candidate field. Beside every candidate, record the question it answers or the branch it controls. Remove fields that have neither role unless their documentation value justifies the work imposed on uploaders.

   Every field added is a field somebody has to fill. The schema’s real constraint is the patience of the people uploading, not the API. A technically comprehensive form that people skip, guess through, or fill inconsistently produces weaker metadata than a smaller form whose purpose is clear.

   Apply a direct test: if a field disappeared, what query or decision would stop working? If the answer is “none,” either remove it or label it honestly as descriptive information. Do not keep it merely because the data could be useful someday.

3. Give each retained field a type and write-time validation.

   Use the Structured Metadata MCP server operations exposed by your client to inspect the existing schema before creating or changing definitions. Then assign each retained field the type that matches the value it is meant to hold and add validation for unacceptable values. Cloudinary’s structured metadata documentation describes typed fields, validation, controlled lists, and conditional rules, as checked on 2026-08-18.

   Typed fields with validation reject bad values at write time, which is the only point where a correction is cheap. The uploader still has the source material and context in front of them. If a malformed value enters the collection, every later search or automation must either tolerate it, repair it, or miss it.

   Define validation from the query requirement. If a field feeds an exact comparison, reject values that cannot participate in that comparison. If it is only descriptive text, do not impose restrictions that serve no query or workflow. Validation should protect a stated use, not make the schema look strict.

4. Replace branch-driving free text with controlled lists.

   Identify every field that an automation will test before choosing an action. Give those fields a controlled set of values rather than accepting arbitrary text. A controlled list turns free text into an enumerable set, which is what makes an automation able to branch on the value rather than pattern-match it.

   For example, if a workflow has separate paths for an approval state, define the states it can receive. Do not ask the workflow to infer that two similar phrases mean the same thing. The value list becomes the contract between uploaders, searches, and automation.

   Keep the list limited to distinctions that change a query result or action. Two values that always lead to the same outcome add choice without adding information. Conversely, do not merge values that require different handling merely to shorten the menu. The condition is operational: preserve a distinction when something downstream acts differently because of it.

5. Add conditional rules for context-specific fields.

   Map fields that are relevant only after a prior choice. Define the dependency once in the schema so that the later field appears only when the earlier answer makes it necessary. Conditional rules keep the form short by revealing fields only when a prior answer makes them relevant, and they are defined once rather than in each uploader.

   This matters when several upload paths write to the same product environment. Recreating the condition independently in every uploader would make each interface responsible for remembering the schema’s logic. A schema-level rule keeps that relationship attached to the fields it governs.

   Use a conditional field only when the earlier answer truly decides whether the later value has meaning. Do not hide a generally required field to make the form appear shorter. The goal is to remove irrelevant work, not conceal required work until submission.

6. Create the schema through the MCP server in dependency order.

   Submit the definitions through the Structured Metadata MCP server, starting with fields that do not depend on other fields. Add controlled values before defining rules that refer to them, then add dependent fields and their conditions. This order gives every rule an existing field and value to reference.

   Review the resulting definitions through the server after writing them. Check the field identifiers, types, validation, controlled values, and conditions against the query worksheet. If the project also needs direct application integration, decide separately whether that runtime path should use an MCP server or the REST API; the schema should remain driven by the same questions either way.

   Do not add unrelated fields during implementation. A newly imagined field should return to the query-and-cost test before entering the schema.

7. Test the schema from upload to query.

   Enter representative valid values and confirm that each planned query can distinguish the records it is supposed to distinguish. Try an invalid value for every validated field and confirm that it is rejected at write time. For controlled fields, verify that an automation can branch on each listed value without interpreting free text.

   Walk through every conditional path. Confirm that dependent fields remain absent when irrelevant and appear when the controlling answer makes them necessary. Then ask the people responsible for uploads to complete the form using representative assets. If they cannot explain why a field is required, the field needs clearer wording, a narrower condition, or removal.

   Finish by comparing every surviving field with the original worksheet. Each should answer a named query, control a named branch, or have an explicitly accepted documentation purpose.

Expected result

The product environment has a schema whose typed fields reject invalid values when written, whose controlled lists give automations enumerable branch conditions, and whose conditional rules reveal context-specific inputs only when relevant. Every field has a stated purpose, and the planned searches can answer their questions without relying on free-text pattern matching.