El estándar JSON de metadatos NFT es el pequeño archivo que le dice a un marketplace qué es realmente tu token: su nombre, su imagen y sus atributos. Si aciertas tres campos (name, image, attributes), OpenSea renderiza tu NFT perfectamente. Si los configuras mal sutilmente, tu token aparece como un espacio gris vacío sin atributos, aunque el contrato se haya minteado bien. Esta guía recorre el estándar campo por campo, cubre las diferencias entre ERC-721 y ERC-1155 que la documentación oficial pasa por alto, y te muestra cómo generar metadatos limpios para toda una colección sin editar manualmente 10,000 archivos.
La mayoría de los creadores descubren el estándar de la manera difícil, después del despliegue. El contrato funciona, el token existe en la cadena, y luego la listación se ve rota. La solución casi siempre está en el JSON, no en Solidity. Así que antes de mintear, vale la pena entender exactamente qué leen los marketplaces y dónde están las trampas comunes.
Qué es realmente el estándar JSON de metadatos NFT#
Cuando una wallet o marketplace quiere mostrar tu NFT, no mira la imagen directamente. Llama a una función en tu contrato, tokenURI(tokenId) para ERC-721, que devuelve una URL. Esa URL apunta a un archivo JSON. El archivo JSON son tus metadatos, y es lo que regula el estándar.
Por lo tanto, la cadena almacena el enlace, y el enlace almacena la descripción. En realidad hay dos estándares en juego, y coinciden en lo esencial pero difieren en el marco:
- ERC-721 / ERC-1155 (la interfaz en cadena): define la función
tokenURI(ouri) y un esquema mínimo sugerido conname,descriptioneimage. - El estándar de metadatos de OpenSea (el esquema de visualización de facto): un superconjunto que añade
attributes,external_url,animation_url,background_colory el sistemadisplay_type. Este es el que los marketplaces realmente renderizan.
En la práctica, escribes según el esquema de OpenSea porque es lo que se muestra. Es compatible con versiones anteriores de la interfaz ERC, por lo que seguirlo satisface ambos.
Punto clave: la blockchain casi nunca almacena tu imagen o atributos. Almacena un puntero. Si ese puntero se rompe o el JSON detrás está mal formado, el NFT se ve roto aunque el token sea perfectamente válido en cadena.
Los campos esenciales que todo NFT necesita#
Aquí tienes un archivo de metadatos mínimo y válido. Esta es la estructura que se renderiza correctamente en OpenSea, Blur, Magic Eden (EVM) y la mayoría de las billeteras.
{
"name": "Cosmic Fox #042",
"description": "Un zorro dibujado a mano de la colección Cosmic Foxes.",
"image": "ipfs://bafybeigdyr.../042.png",
"external_url": "https://cosmicfoxes.xyz/042",
"attributes": [
{ "trait_type": "Fondo", "value": "Nebulosa" },
{ "trait_type": "Pelaje", "value": "Naranja" },
{ "trait_type": "Ojos", "value": "Láser" }
]
}
Cuatro campos hacen el trabajo pesado:
name: el título visible. La convención esNombre de la colección #TokenID. Aparece como el encabezado grande en la página del ítem.description: admite Markdown básico en OpenSea (saltos de línea, negritas, enlaces). Mantenlo breve y legible.image: la URL de la obra de arte. PNG, JPG, GIF y SVG funcionan. Es el punto de fallo más común (más detalles abajo).attributes: el arreglo de rasgos que alimenta los filtros de rareza que los compradores usan para explorar y valorar tu colección.
Si solo incluyes name, description e image, el NFT se renderizará igual. Pero no tendrá rasgos para filtrar, lo que en una colección generativa es una gran omisión.
El campo image y la trampa de ipfs://#
La mayor fuente de "mi NFT está en blanco" es que el campo image apunte a algo que el mercado no puede obtener. Tres reglas te mantienen a salvo:
- Usa una URL estable y resoluble por gateway.
ipfs://CID/file.pnges preferido porque los mercados resuelven el esquemaipfs://de forma nativa. Un enlace HTTPS a tu propio servidor también funciona, pero ata la supervivencia del arte a tu hosting. - No uses una URL de localhost o temporal. Los mercados almacenan en caché los metadatos. Si obtienen un enlace roto una vez, a menudo debes forzar una actualización manual.
- Haz coincidir el archivo con la extensión. Una URL
.pngque sirve un JPEG puede fallar silenciosamente en algunos renderizadores.
Para decidir entre IPFS y un servidor normal (y qué significa "riesgo de rug" para los compradores), el generador gratuito de metadatos NFT produce archivos listos para ipfs:// para que no tengas que armar las URIs a mano.
Cómo funcionan realmente los atributos y display_type#
El array attributes es donde el estándar se vuelve interesante, y donde la documentación oficial es más escasa. Por defecto, cada atributo se muestra como un rasgo de texto. Pero display_type cambia cómo se muestra un valor, y hacerlo bien es lo que diferencia una colección pulida de una amateur.
| display_type | Qué hace | Ejemplo de uso |
|---|---|---|
| (ninguno) | Rasgo de texto plano, mostrado como una píldora | Fondo: Nebulosa |
number | Rasgo numérico con una clasificación en toda la colección | Generación: 2 |
boost_number | Añade un + y se muestra como un medidor de mejora | Velocidad: +20 |
boost_percentage | Igual que boost, mostrado como porcentaje | Resistencia: +10% |
date | Muestra una marca de tiempo Unix como fecha de calendario | Cumpleaños: Ene 2024 |
Aquí está el detalle que la mayoría de las guías omiten: cuando usas un display_type numérico, el value debe ser un número real, no una cadena. "value": 20 funciona; "value": "20" puede renderizarse incorrectamente o ser ignorado.
{
"attributes": [
{ "trait_type": "Nivel", "display_type": "number", "value": 7 },
{ "trait_type": "Poder", "display_type": "boost_number", "value": 40 },
{ "display_type": "date", "trait_type": "Acuñado", "value": 1704067200 }
]
}
Observa que la última entrada tiene un display_type y ninguna etiqueta trait_type en la fecha en algunas configuraciones. Ambas formas existen en la práctica; incluir trait_type es la opción más segura y clara.
Rasgos de clasificación y el campo max_value#
Para estadísticas numéricas puedes añadir max_value para forzar un denominador consistente en toda la colección, de modo que una estadística se lea como 7 / 10 en lugar de solo 7. Esto es puramente un detalle de visualización, pero hace que las colecciones de estilo RPG parezcan intencionadas.
{ "trait_type": "Fuerza", "display_type": "number", "value": 7, "max_value": 10 }
ERC-721 vs ERC-1155 Metadatos: La Diferencia Que Nadie Explica#
Esta es la brecha que confunde a los creadores que pasan de obras únicas a ediciones o artículos de juego. Los dos estándares manejan la URI de metadatos de manera diferente, y la documentación oficial de OpenSea apenas lo menciona.
| Aspecto | ERC-721 | ERC-1155 |
|---|---|---|
| Modelo de token | Un token único por ID | Múltiples copias por ID (ediciones) |
| Función URI | tokenURI(uint256 id) | uri(uint256 id) |
| Sustitución de ID | Generalmente una URL completa por token | El estándar admite un marcador de posición {id} |
| Metadatos típicos | Un archivo JSON por token | A menudo una plantilla resuelta por ID |
| Campo decimals | No se usa | decimals opcional para tokens tipo fungible |
La diferencia principal es el marcador de posición {id}. ERC-1155 permite que tu contrato devuelva una plantilla URI única como ipfs://CID/{id}.json, y los clientes sustituyen el ID del token. La especificación oficial de ERC-1155 requiere que el ID sustituido sea una cadena hexadecimal de 64 caracteres en minúsculas, rellenada con ceros y sin prefijo 0x. Así, el ID de token 1 se convierte en 0000000000000000000000000000000000000000000000000000000000000001.
En la práctica, OpenSea y la mayoría de los mercados son flexibles y también aceptan un ID decimal simple, pero si quieres cumplir con la especificación, rellénalo. Este detalle provoca horas de confusión del tipo "¿por qué no cargan mis metadatos 1155?" que ningún tutorial para principiantes advierte.
Los metadatos ERC-1155 también pueden incluir un campo decimals (para tokens semifungibles) y un objeto properties junto con attributes. Si estás creando artículos de juego o entradas en lugar de arte, lee ambos campos.
Generación de metadatos para una colección de 10,000 elementos#
Escribir un archivo JSON a mano es fácil. Escribir 10,000 con rasgos consistentes, tipos numéricos correctos y CIDs de imágenes coincidentes es donde los proyectos se rompen. Hacerlo manualmente garantiza errores tipográficos, y un error tipográfico en un archivo significa un NFT roto del que un comprador se quejará.
El enfoque confiable es tratar los metadatos como resultados generados, no como archivos editados a mano. Ya sea que uses un script o una herramienta, el proceso es el mismo.
Paso 1: Bloquea primero tu esquema de rasgos#
Antes de generar cualquier cosa, escribe cada trait_type y sus valores permitidos. "Background" siempre debe escribirse "Background", nunca "BG" en algunos archivos. Los nombres de rasgos inconsistentes dividen tus filtros de rareza en duplicados inútiles en el mercado. Una lista canónica evita eso.
Paso 2: Decide el alojamiento de imágenes y obtén tu CID#
Sube tu carpeta completa de imágenes a IPFS (a través de Pinata, NFT.Storage o similar) para obtener un CID base para el directorio. Tu campo image se convierte en ipfs://BASE_CID/042.png. Fijar toda la carpeta una vez mantiene cada URI consistente y evita cargas por archivo.
Paso 3: Genera un archivo JSON por token#
Para cada token, ensambla name, description, image (CID base más nombre de archivo) y el array attributes para esa combinación específica. Mantén los rasgos numéricos como números reales. La ruta más rápida sin código es pegar tus datos de rasgos en el generador de metadatos NFT, que construye archivos correctos según la especificación con el display_type y las URI ipfs:// adecuados, y luego exporta el lote.
Paso 4: Valida antes de subir#
Ejecuta cada archivo a través de un validador JSON para que una sola coma final no rompa un token. Pegar una muestra en un validador y formateador JSON detecta corchetes mal formados, comillas incorrectas y la coma extra que rompe JSON.parse. Haz esto en algunos archivos aleatorios del lote, no solo en el archivo #1.
Paso 5: Sube los metadatos y establece tu baseURI#
Sube la carpeta de metadatos a IPFS para obtener un segundo CID, luego establécelo como baseURI de tu contrato (para que tokenURI devuelva ipfs://METADATA_CID/{id}.json o URLs por token). Confirma que un token se resuelva de extremo a extremo en una testnet antes de acuñar el suministro completo.
Advertencia: los mercados almacenan en caché los metadatos de forma agresiva. Siempre verifica que tus metadatos se rendericen correctamente en una testnet (o con una acuñación) antes de comprometer toda la colección. Arreglar un CID después de una revelación de 10,000 acuñaciones es doloroso y a veces requiere que cada titular actualice manualmente.
Metadatos en cadena: cuando el JSON vive en el contrato#
Existe una variante completamente en cadena donde tokenURI devuelve un URI de datos codificado en base64 en lugar de un enlace IPFS, por lo que los metadatos (y a veces una imagen SVG) residen por completo en Ethereum. Así es como proyectos de arte generativo totalmente en cadena garantizan la permanencia sin dependencias externas.
El esquema de metadatos es idéntico. El único cambio es la entrega: en lugar de un enlace ipfs://, tokenURI devuelve:
data:application/json;base64,eyJuYW1lIjoiQ29zbWlj...
El navegador decodifica esa cadena base64 en el mismo objeto JSON descrito anteriormente. Si estás depurando uno de estos, puedes pegar la cadena codificada en un codificador y decodificador base64 para leer el JSON subyacente. El almacenamiento en cadena cuesta mucho más gas, por lo que se reserva para colecciones que consideran la permanencia como el objetivo principal. Para todo lo demás, IPFS con un archivo JSON limpio es el estándar.
Errores comunes que hacen que tu NFT se vea en blanco#
Una lista rápida de los fallos que explican la mayoría de los hilos de soporte "se acuñó pero se ve roto":
- Comas finales o claves sin comillas. Válidos en objetos JavaScript, inválidos en JSON. Una coma rompe todo el archivo.
- Valores de cadena donde van números.
"value": "7"condisplay_type: numberpuede eliminar el rasgo. Usa7. - Ortografía inconsistente de
trait_type. "Eye Color" en un archivo y "Eyes" en otro fragmenta tus filtros. - URL de imagen rota o privada. Localhost, un enlace caducado o un CID mal escrito muestra un espacio en blanco.
- ID de ERC-1155 sin relleno. Si un mercado es estricto, un
{id}sin relleno no se resuelve. - Olvidar actualizar los metadatos. Después de corregir un archivo, a menudo debes forzar una actualización de metadatos en el mercado debido al caché.
Si tu contrato está construido pero no estás seguro de que la interfaz estándar esté cableada correctamente, una revisión rápida con un verificador de contratos de token confirma que la función tokenURI / uri está expuesta como esperan los mercados antes de gastar gas en acuñar.
El estándar JSON de metadatos NFT en una frase#
El estándar JSON de metadatos NFT es un pequeño archivo JSON con name, description, image y un array attributes, servido desde tokenURI (ERC-721) o uri (ERC-1155), donde los rasgos numéricos usan un display_type con números reales y la imagen reside en una URL estable ipfs://. Sigue esa estructura, valida antes de subir y verifica en una testnet, y tu colección se renderizará como la diseñaste. Genera los archivos con el generador de metadatos NFT y te saltas la edición manual por completo.
Preguntas Frecuentes#
¿Qué es el estándar JSON de metadatos NFT?
Es el esquema JSON acordado que los mercados leen para mostrar un NFT. Como mínimo incluye name, description e image, además de un array attributes para los rasgos. El archivo se sirve desde la función tokenURI (ERC-721) o uri (ERC-1155) de tu contrato, y el superconjunto de este esquema de OpenSea es lo que la mayoría de las plataformas realmente renderizan.
¿Dónde se almacenan los metadatos NFT, en cadena o fuera de cadena?
Generalmente fuera de cadena. La blockchain suele almacenar solo un puntero (un enlace ipfs:// o una URL HTTPS) devuelto por tokenURI, y el JSON en sí reside en IPFS o en un servidor. Una variante totalmente en cadena devuelve una URI de datos codificada en base64 para que los metadatos vivan en el contrato, pero eso cuesta mucho más gas y es la excepción, no la norma.
¿Por qué mi NFT aparece en blanco en OpenSea?
Casi siempre es un problema de metadatos, no del contrato. Las causas habituales son una URL de image rota o privada, JSON mal formado (una coma final es el clásico), un error tipográfico en el CID o un ID de token ERC-1155 que no tiene relleno de ceros. Corrige el archivo y luego activa una actualización de metadatos, porque los mercados almacenan en caché de forma agresiva.
¿Cuál es la diferencia entre los metadatos ERC-721 y ERC-1155?
El esquema es casi idéntico, pero la entrega difiere. ERC-721 expone tokenURI y generalmente apunta a un archivo JSON por token. ERC-1155 expone uri y admite un marcador de posición {id}, donde la especificación requiere que el ID esté en minúsculas y con relleno de ceros hasta 64 caracteres hexadecimales. ERC-1155 también añade campos opcionales como decimals para tokens semisustituibles.
¿Cómo añado rasgos con rareza a los metadatos NFT?
Colócalos en el array attributes, cada uno como un objeto con trait_type y value. Los mercados calculan la rareza automáticamente contando la frecuencia de cada valor en toda la colección, por lo que la ortografía consistente es importante. Usa display_type de number, boost_number o boost_percentage para estadísticas numéricas y mantén esos valores como números reales en lugar de cadenas.
¿Necesito IPFS para los metadatos NFT? No, pero es muy recomendable. IPFS proporciona un alojamiento direccionado por contenido y a prueba de manipulaciones, para que los compradores sepan que el arte no puede intercambiarse ni eliminarse silenciosamente. Un servidor HTTPS normal funciona y los mercados lo leerán, pero la supervivencia del arte dependerá de que tu alojamiento permanezca en línea, que es el "riesgo de estafa" que preocupa a los compradores.
