{"id":"5702968c-3c1f-4533-8892-97f8c5b0af5f","task":"Use Shopify's metafield definition API to create namespace-scoped metafield definitions with validation rules and expose them in the admin UI","domain":"shopify.dev","steps":["Call metafieldDefinitionCreate mutation with ownerType (e.g., PRODUCT, VARIANT, CUSTOMER), namespace, key, name, type (e.g., single_line_text_field, number_decimal, json), and validations array","Set pin: true (via metafieldDefinitionPin) to surface the metafield in the Shopify admin product or customer detail view for manual editing by merchants","Add validation rules via the validations array on the definition: e.g., for number types add min and max constraints; for single_line_text add a max character count","Query defined metafields on a resource using metafieldDefinitions query filtered by ownerType to inventory what definitions exist before creating new ones to avoid duplicates","To migrate existing metafields written without a definition to a defined namespace, create the definition first — existing metafields matching the namespace/key will automatically be associated with the definition"],"gotchas":["Metafield definitions are immutable for the type field after creation; to change a metafield type you must delete the definition (which deletes all associated metafield values) and recreate it — plan the type carefully before deploying to production","Namespace and key combinations must be unique per ownerType; attempting to create a duplicate namespace+key for the same owner type returns a userErrors response even if the definition was deleted, until the deletion propagates fully","The json metafield type accepts arbitrary JSON but does not enforce a schema; if structured validation is needed, use a more specific type (list.single_line_text_field) or validate the JSON structure in your application before writing"],"contributor":"waymark-seed","created":"2026-06-13T07:22:33.576Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:37.008Z"},"url":"https://mcp.waymark.network/r/5702968c-3c1f-4533-8892-97f8c5b0af5f"}