← Volver al listado de tecnologías ← Índice de EPCIS

Capítulo 6: Formatos XML vs JSON-LD

21 de marzo de 2026 Por: Artiko

epcisxmljson-ldformatointeroperabilidadepcis-2.0contexto-jsonld

Historia de los formatos

EPCIS 1.x (2007-2021) solo soportaba XML. Cada implementación tenía que parsear documentos XML con namespaces complejos. Con EPCIS 2.0 (2022), GS1 agregó JSON-LD como formato alternativo oficial, reconociendo que la mayoría de sistemas modernos trabajan con JSON.

Ambos formatos son semánticamente equivalentes: el mismo evento se puede representar en XML o en JSON-LD sin pérdida de información.

El mismo ObjectEvent en XML

Formato XML compatible con EPCIS 1.2 y 2.0:

<?xml version="1.0" encoding="UTF-8"?>
<epcis:EPCISDocument xmlns:epcis="urn:epcglobal:epcis:xsd:2"
                     schemaVersion="2.0"
                     creationDate="2026-03-21T10:00:00Z">
  <EPCISBody>
    <EventList>
      <ObjectEvent>
        <eventTime>2026-03-21T09:00:00Z</eventTime>
        <eventTimeZoneOffset>-03:00</eventTimeZoneOffset>
        <epcList>
          <epc>urn:epc:id:sgtin:0614141.107340.2026001</epc>
        </epcList>
        <action>OBSERVE</action>
        <bizStep>urn:epcglobal:cbv:bizstep:shipping</bizStep>
        <disposition>urn:epcglobal:cbv:disp:in_transit</disposition>
        <readPoint>
          <id>urn:epc:id:sgln:0614141.07346.1234</id>
        </readPoint>
      </ObjectEvent>
    </EventList>
  </EPCISBody>
</epcis:EPCISDocument>

El mismo ObjectEvent en JSON-LD

Formato JSON-LD exclusivo de EPCIS 2.0:

{
  "@context": "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
  "type": "EPCISDocument",
  "schemaVersion": "2.0",
  "creationDate": "2026-03-21T10:00:00Z",
  "epcisBody": {
    "eventList": [
      {
        "type": "ObjectEvent",
        "eventTime": "2026-03-21T09:00:00Z",
        "eventTimeZoneOffset": "-03:00",
        "epcList": ["urn:epc:id:sgtin:0614141.107340.2026001"],
        "action": "OBSERVE",
        "bizStep": "shipping",
        "disposition": "in_transit",
        "readPoint": { "id": "urn:epc:id:sgln:0614141.07346.1234" }
      }
    ]
  }
}

Diferencias clave

bizStep y disposition: URIs vs valores cortos

La diferencia más visible:

Campo	XML	JSON-LD
bizStep	`urn:epcglobal:cbv:bizstep:shipping`	`"shipping"`
disposition	`urn:epcglobal:cbv:disp:in_transit`	`"in_transit"`

En JSON-LD, el contexto (@context) contiene las reglas de expansión. Cuando un sistema procesa "shipping", el contexto lo resuelve automáticamente a la URI completa urn:epcglobal:cbv:bizstep:shipping.

En XML, no existe este mecanismo de resolución automática, por lo que se deben usar las URIs completas.

Nombres de campos

Concepto	XML	JSON-LD
Documento raíz	`<EPCISDocument>`	`"type": "EPCISDocument"`
Cuerpo	`<EPCISBody>`	`"epcisBody"`
Lista de eventos	`<EventList>`	`"eventList"`
Tipo de evento	`<ObjectEvent>` (tag XML)	`"type": "ObjectEvent"`
Lista de EPCs	`<epcList><epc>...</epc></epcList>`	`"epcList": [...]`
Punto de lectura	`<readPoint><id>...</id></readPoint>`	`"readPoint": { "id": "..." }`

XML usa PascalCase para elementos raíz y camelCase para propiedades. JSON-LD usa camelCase consistentemente.

Estructura del documento

XML requiere namespaces y declaraciones de schema:

<epcis:EPCISDocument xmlns:epcis="urn:epcglobal:epcis:xsd:2"
                     xmlns:cbvmda="urn:epcglobal:cbv:mda"
                     schemaVersion="2.0">

JSON-LD resuelve todo con una sola línea de contexto:

"@context": "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld"

El rol del contexto JSON-LD

El archivo de contexto en https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld es un documento JSON que contiene mapeos como:

{
  "@context": {
    "epcis": "https://ref.gs1.org/standards/epcis/",
    "cbv": "https://ref.gs1.org/standards/cbv/",
    "ObjectEvent": "epcis:ObjectEvent",
    "bizStep": { "@id": "epcis:bizStep", "@type": "@vocab" },
    "shipping": "cbv:BizStep-shipping",
    "in_transit": "cbv:Disp-in_transit"
  }
}

Esto permite que los valores cortos se expandan a URIs completas cuando se procesan con un parser JSON-LD. Es lo que hace posible la interoperabilidad semántica: dos sistemas pueden intercambiar datos JSON-LD y entender exactamente el mismo significado.

Contextos personalizados

Puedes extender el contexto con tu propio vocabulario:

{
  "@context": [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      "miempresa": "https://miempresa.com/epcis/",
      "miempresa:lotNumber": { "@type": "xsd:string" },
      "miempresa:temperature": { "@type": "xsd:decimal" }
    }
  ]
}

Esto permite agregar campos custom sin romper la compatibilidad con el estándar.

Conversión entre formatos

Herramientas de conversión

OpenEPCIS Converter: herramienta online y librería Java que convierte XML ↔ JSON-LD de forma bidireccional
epcis2.js: SDK JavaScript que puede serializar eventos en ambos formatos
Reglas manuales: la conversión es determinística, se puede implementar con un mapper

Consideraciones al convertir

Pérdida de formato, no de datos: la conversión es lossless en términos de semántica, pero el formato cambia
Namespaces XML → prefijos JSON-LD: los namespaces custom en XML deben mapearse a prefijos en el contexto JSON-LD
Extensiones: las extensiones de usuario (userExtension en XML) se mapean a campos con prefijo en JSON-LD

Cuándo usar cada formato

Usar XML cuando:

Integras con sistemas legacy que solo entienden EPCIS 1.x
Tus socios comerciales aún usan XML (farmacia regulada, industria tradicional)
Necesitas conformidad con regulaciones antiguas que especifican XML
Tu stack tecnológico está basado en Java/SOAP/WSDL

Usar JSON-LD cuando:

Construyes sistemas nuevos sin restricciones legacy
Tu stack es JavaScript/TypeScript, Python o cualquier lenguaje con buen soporte JSON
Necesitas APIs REST (el estándar EPCIS 2.0 REST API usa JSON-LD)
Quieres máxima interoperabilidad semántica (linked data, grafos de conocimiento)
Priorizas legibilidad y facilidad de debugging

Recomendación práctica

Si empiezas un proyecto nuevo, usa JSON-LD. Es más conciso, más fácil de debuggear y está alineado con la dirección futura del estándar. Solo usa XML si un socio comercial o regulación lo requiere.

Content-Type HTTP

Al enviar eventos por API REST, el header Content-Type indica el formato:

Formato	Content-Type
XML	`application/xml`
JSON-LD	`application/ld+json; profile="https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld"`

El header Accept del cliente indica qué formato prefiere recibir. Un servidor EPCIS 2.0 bien implementado debería soportar content negotiation entre ambos formatos.

Validación

XML Schema (XSD)

GS1 publica schemas XSD oficiales para validar documentos EPCIS XML:

EPCISDocument.xsd — estructura del documento
EPCISQueryDocument.xsd — respuestas de consulta

JSON Schema

Para JSON-LD, GS1 publica JSON Schemas que validan la estructura del documento sin necesidad de un parser JSON-LD completo.

Ambos schemas están disponibles en el repositorio GitHub de GS1.

Próximo capítulo

En el capítulo 7 exploraremos la API REST de EPCIS 2.0: los endpoints estándar para captura y consulta de eventos.