Volver al blog PHP

JSON-LD: El lenguaje oculto que potencia nuestras APIs

JSON-LD da contexto semántico a los datos de nuestras APIs.

04 agosto 2025
symfony jsonld API Rest

📌 ¿Qué es JSON-LD?

JSON-LD (JavaScript Object Notation for Linked Data) es un formato de serialización de datos que sigue las reglas de Linked Data, pensado para que las máquinas puedan entender mejor la información que enviamos. En palabras simples: le da contexto a los datos.

Por ejemplo, si tenés:

{
  "nombre": "Juan Pérez",
  "email": "juan@example.com"
}

Para una máquina, eso son solo strings. Pero con JSON-LD podés decir explícitamente que nombre es un schema:Person y que email es un schema:email.

🛠 Implementación en API Platform (Symfony)

API Platform es prácticamente el paraíso del JSON-LD porque lo soporta out of the box. Cuando configurás tus entidades como recursos (@ApiResource), API Platform genera automáticamente endpoints con serialización JSON-LD.

Ejemplo con Symfony 7 + API Platform:

<?php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource(
    formats: ['jsonld' => ['application/ld+json']],
    normalizationContext: ['groups' => ['empleado:read']],
    denormalizationContext: ['groups' => ['empleado:write']]
)]
class Empleado
{
    #[ORM\Id, ORM\GeneratedValue, ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    private string $nombre;

    #[ORM\Column(length: 255, unique: true)]
    private string $email;

    // Getters y setters...
}

Con esta configuración, si accedés a /api/empleados/1, obtendrás algo así:

{
  "@context": "/api/contexts/Empleado",
  "@id": "/api/empleados/1",
  "@type": "Empleado",
  "id": 1,
  "nombre": "Juan Pérez",
  "email": "juan@example.com"
}

💡 Tips para optimizar JSON-LD en API Platform

Tip Descripción Beneficio
Usar normalizationContext con groups Solo exponer campos necesarios Reduce payload y mejora seguridad
Personalizar @context Definir tus propios contextos y vocabularios Hace la API más semántica
Cachear el contexto El endpoint /api/contexts/... puede cachearse Aumenta performance
Deshabilitar si no se usa Si tu cliente no lo necesita, desactivalo Menos overhead en serialización

Ejemplo para personalizar el contexto:

#[ApiResource(
    normalizationContext: [
        'groups' => ['empleado:read'],
        'jsonld_context' => [
            '@vocab' => 'https://schema.org/',
            'nombre' => 'givenName',
            'email' => 'email'
        ]
    ]
)]

Esto hará que tu JSON-LD sea más semántico y compatible con vocabularios estándar como schema.org.

✅ Pros y ❌ Contras de JSON-LD en APIs

Pros Contras
Facilita la interoperabilidad entre sistemas Payload más grande
Ayuda a que motores de búsqueda y crawlers entiendan mejor la data Curva de aprendizaje si no conocés Linked Data
API Platform lo soporta automáticamente Puede ser innecesario si no se consume de forma semántica
Ideal para integraciones con IA y conocimiento semántico Más complejidad en customización de contextos

📌 Conclusiones

JSON-LD no es solo un formato más de salida. Es un puente semántico entre tu API y el mundo de datos interconectados. Si trabajás con API Platform en Symfony, su implementación es prácticamente automática, y con algunos ajustes podés optimizarlo tanto para humanos como para máquinas.

Eso sí: no uses JSON-LD solo por moda. Evaluá si tu ecosistema lo necesita, y si sí, aprovechá su potencial para darle más significado a tus datos.

📖 Glosario

  • JSON-LD: Formato JSON para representar datos enlazados (Linked Data).
  • Contexto (@context): Define el significado de las propiedades en el JSON-LD.
  • API Platform: Framework sobre Symfony para construir APIs REST y GraphQL de forma rápida.
  • Vocabulario: Conjunto de términos definidos (como schema.org) para dar significado a los datos.
  • Payload: El contenido de una respuesta HTTP.
Ver más artículos