JSON-LD за цифрови продуктови паспорти (и къде се вписва EPCIS 2.0)

Един цифров продуктов паспорт е предназначен да бъде четен от хора и от машини: приемната система на рециклатор, митническо API, обхождащ маркетплейс краулер, скрипт на одитор по устойчивост. HTML страница само за хора не е достатъчна. Паспортът трябва да бъде машинночетим — структуриран товар, който програма може да разбере, свърже и обработи логически, без да го извлича чрез скрейпинг.

Това ръководство е за разработчици, които задават очевидния следващ въпрос: след като вече имам DPP, как машината реално го прочита? Отговорът за qr3 е JSON-LD през публичния resolver. Ще покажем реалния отговор, ще обясним как един и същи URL обслужва хора и машини, и след това ще поставим EPCIS 2.0 — допълващия стандарт за събития на GS1 — в контекст.

Какво означава машинна четимост за един DPP

Машинна четимост е нещо повече от „връща JSON“. За един продуктов паспорт тя означава три неща:

Структуриран — полета, които парсер може да адресира (gtin, name, …), а не проза за скрейпинг.
Типизиран и свързан — термини, закотвени в споделени речници, така че Product да означава едно и също за всички. Това е Linked Data в JSON-LD.
Стабилен за извличане — един траен URL за всеки артикул, който скрипт може да GET-не през целия живот на продукта.

JSON-LD (JSON for Linking Data) осигурява и трите. Това е обикновен JSON плюс @context, който съпоставя всеки ключ с термин в публичен речник — тук schema.org и GS1 Web Vocabulary. Краулер, който вече разбира schema.org, разбира паспорта с нулева персонализирана интеграция.

DPP като JSON-LD (реален curl + проверен отговор)

Всеки паспорт на qr3 се разрешава на URL по GS1 Digital Link: https://qr3.app/dpp/{gtin}/{serial}. Добавете ?format=jsonld, за да поискате изгледа Linked Data. Срещу живото демо за батерия:

curl -s "https://qr3.app/dpp/04019999999902/DEMO-BAT-01?format=jsonld"

връща:

{
  "@context": ["https://schema.org", "https://gs1.org/voc/"],
  "@type": "Product",
  "gtin": "04019999999902",
  "name": "EcoMax 5000 (Demo)"
}

Три неща, които заслужават внимание:

@context е масив от два речника — schema.org за общата мрежа и gs1.org/voc/ за продуктовите термини на GS1. Ключовете се разрешават срещу и двата.
@type: "Product" казва на всеки потребител на Linked Data точно какъв тип същност е това.
Стойностите (gtin, name) са реални и живи — това е действителният товар, а не макет.

В това е целият смисъл: скриптът на рециклатор не се нуждае от специфичен за qr3 клиент. Той прави HTTP GET, разбира JSON-LD, който вече познава, и чете GTIN и името на продукта направо.

Един URL, две аудитории: договаряне на съдържанието

Един и същи URL https://qr3.app/dpp/{gtin}/{serial} обслужва удобен за хора HTML паспорт и машинния изглед — сървърът решава какво да върне въз основа на това, което поиска извикващият. Два начина да поискате:

Искате	Query параметър	Или Accept хедър
Човешка HTML страница	(по подразбиране)	`Accept: text/html`
JSON-LD (Linked Data)	`?format=jsonld`	`Accept: application/ld+json`
Обикновен JSON	`?format=json`	—
Linkset (свързани ресурси)	`?format=linkset`	—
DCAT-AP (метаданни за набор от данни)	`?format=dcat-ap`	—

Така камерата на телефон, която отваря QR кода, попада на четимия HTML паспорт, докато скрипт иска от идентичния URL application/ld+json и получава структурирани данни:

# Машинен изглед чрез договаряне с хедър — същият URL, без query string
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Един идентификатор, един URL, много представяния. GTIN/serial остава стабилен; изгледът се адаптира към извикващия. Точно това прави един DPP едновременно траен и оперативно съвместим.

Къде се вписва EPCIS 2.0 (събития срещу паспорт)

Често следва въпросът: а какво ще кажете за EPCIS — не е ли това стандартът на GS1 за това? Важно разграничение:

Един DPP е статичното описание на един продуктов артикул — неговата идентичност, материали, въглероден отпечатък, рециклируемост. Той отговаря на въпроса „какво е това нещо?“ JSON-LD по-горе е този моментен снимка.
EPCIS 2.0 е стандартът на GS1 за събития във веригата на доставки — данните за видимост на какво се е случило, къде, кога и защо: артикул е въведен в обращение, изпратен, получен, рециклиран. Той отговаря на въпроса „какво се случи с това нещо и къде е то?“

Те са допълващи се, а не конкуриращи се. Паспортът ви казва, че продуктът е батерия от 5,2 kWh с 35% рециклирано съдържание; верига от EPCIS събития би ви казала, че е произведена в Хамбург на дадена дата, изпратена през дистрибуционен център и пристигнала при рециклатор. Самият EPCIS 2.0 е дружелюбен към JSON/JSON-LD, така че двата споделят един и същи мироглед на Linked Data и едни и същи идентификатори на GS1 (GTIN + serial) като ключ за обединяване.

Обхват на qr3 (бъдете точни): qr3 извежда DPP като JSON-LD — точно това демонстрира тази публикация. qr3 не предоставя улавяне на EPCIS събития или EPCIS крайни точки. Третирайте EPCIS 2.0 тук като концептуалния, допълващ стандарт, който бихте възприели заедно с един DPP за пълна проследимост на веригата на доставки, а не като функция на qr3.

И така, мисловният модел е: DPP-то (qr3, JSON-LD) е листът с идентичността на продукта; EPCIS 2.0 (отделна система) е неговият дневник на пътуването. Едни и същи идентификатори, отговор на два въпроса.

Генериране на DPP, който предоставя JSON-LD

Не правите нищо специално, за да „активирате“ JSON-LD — създайте паспорта и resolver-ът обслужва всяко представяне автоматично:

import { QR3 } from "@qr3/sdk";

const client = new QR3({ apiKey: process.env.QR3_API_KEY! });

const passport = await client.dpp.create({
  gtin: "04019999999902",
  serial: "SN-00012345",
  product_name: "PowerCell 5 kWh LFP",
  manufacturer: "ExampleTech GmbH",
  origin_country: "DE",
  category: "battery",
  market_countries: ["DE", "FR", "AT"],
  status: "live",
  battery_data: {
    capacity_kwh: 5,
    carbon_footprint_kg: 62,
    recycled_content_pct: 12,
    recyclability_pct: 95,
  },
});

// The passport now resolves at https://qr3.app/dpp/04019999999902/SN-00012345
// Humans get HTML; machines append ?format=jsonld (or send Accept: application/ld+json).
console.log(passport.qr.svg); // QR encodes the GS1 Digital Link to the resolver

След като бъде създаден, URL-ът на артикула отговаря на двете аудитории незабавно — без допълнителна стъпка за публикуване за машинния изглед.

Често задавани въпроси

Защо JSON-LD, а не обикновен JSON? Обикновеният JSON е структуриран, но не е самоописващ се: потребителят трябва да научи имената на полетата ви. JSON-LD добавя @context, съпоставяйки всеки ключ с термини на schema.org / GS1, така че всеки потребител на Linked Data го разбира без персонализирана интеграция. Ако ви е нужно само бързо прочитане, ?format=json все още е наличен.

Реализира ли qr3 EPCIS 2.0? Не. qr3 извежда DPP като JSON-LD. EPCIS 2.0 е отделният, допълващ стандарт на GS1 за събития във веригата на доставки; бихте го пуснали успоредно, обединен чрез споделените GTIN + serial.

Как да получа машинния изглед? Добавете ?format=jsonld към URL-а на resolver-а или изпратете Accept: application/ld+json. И двата връщат един и същи товар Linked Data.

Стабилен ли е @context? Той фиксира schema.org плюс GS1 Web Vocabulary (gs1.org/voc/) — и двата публични, версионирани речника, така че потребителите могат да разчитат на значенията на термините.

Източници

Започнете безплатно и създайте DPP, който предоставя JSON-LD: app.qr3.app/sign-up