gs1.org.ai

GS1 supply chain standards, product identification, and EPCIS (Electronic Product Code Information Services) vocabulary for tracking goods through the supply chain.

Overview

The gs1.org.ai package provides TypeScript types and semantic definitions for GS1 standards including EPCIS events, barcodes, and supply chain data models.

Installation

pnpm add gs1.org.ai

Quick Start

import { EPCIS, Event } from 'gs1.org.ai'

// Create object event
const event: EPCIS.ObjectEvent = {
  type: 'ObjectEvent',
  action: 'OBSERVE',
  bizStep: 'receiving',
  disposition: 'in_progress',
  epcList: ['urn:epc:id:sgtin:0614141.107346.2017'],
  eventTime: new Date().toISOString(),
  readPoint: { id: 'urn:epc:id:sgln:0614141.07346.0' },
}

EPCIS Events

Object Event

Track individual products or cases:

import { ObjectEvent } from 'gs1.org.ai'

const shipping: ObjectEvent = {
  type: 'ObjectEvent',
  action: 'OBSERVE',
  bizStep: 'shipping',
  disposition: 'in_transit',
  epcList: ['urn:epc:id:sgtin:0614141.107346.2017', 'urn:epc:id:sgtin:0614141.107346.2018'],
  eventTime: '2025-01-01T00:00:00Z',
  readPoint: { id: 'urn:epc:id:sgln:0614141.07346.1' },
}

Aggregation Event

Track parent-child relationships:

import { AggregationEvent } from 'gs1.org.ai'

const pallet: AggregationEvent = {
  type: 'AggregationEvent',
  action: 'ADD',
  parentID: 'urn:epc:id:sscc:0614141.1234567890',
  childEPCs: ['urn:epc:id:sgtin:0614141.107346.2017', 'urn:epc:id:sgtin:0614141.107346.2018'],
  bizStep: 'packing',
  eventTime: '2025-01-01T00:00:00Z',
}

Transaction Event

Link events to business transactions:

import { TransactionEvent } from 'gs1.org.ai'

const po: TransactionEvent = {
  type: 'TransactionEvent',
  action: 'ADD',
  bizStep: 'shipping',
  epcList: ['urn:epc:id:sgtin:0614141.107346.2017'],
  bizTransactionList: [
    {
      type: 'po',
      bizTransaction: 'urn:epc:id:gdti:0614141.06789.987',
    },
  ],
  eventTime: '2025-01-01T00:00:00Z',
}

Transformation Event

Track product transformations:

import { TransformationEvent } from 'gs1.org.ai'

const manufacturing: TransformationEvent = {
  type: 'TransformationEvent',
  inputEPCList: [
    'urn:epc:id:sgtin:0614141.107346.1001', // Raw material
    'urn:epc:id:sgtin:0614141.107346.1002',
  ],
  outputEPCList: [
    'urn:epc:id:sgtin:0614141.107346.2017', // Finished product
  ],
  bizStep: 'commissioning',
  eventTime: '2025-01-01T00:00:00Z',
}

Identifiers

GTIN (Global Trade Item Number)

import { GTIN } from 'gs1.org.ai'

// Encode GTIN
const gtin = GTIN.encode({
  companyPrefix: '0614141',
  itemReference: '107346',
  checkDigit: '2',
})
// '06141411073462'

// Decode GTIN
const decoded = GTIN.decode('06141411073462')
// { companyPrefix: '0614141', itemReference: '107346', checkDigit: '2' }

SSCC (Serial Shipping Container Code)

import { SSCC } from 'gs1.org.ai'

const sscc = SSCC.encode({
  extensionDigit: '0',
  companyPrefix: '0614141',
  serialReference: '1234567890',
})
// '006141411234567890'

GLN (Global Location Number)

import { GLN } from 'gs1.org.ai'

const locationId = GLN.encode({
  companyPrefix: '0614141',
  locationReference: '07346',
})

Barcode Generation

GS1-128

import { GS1_128 } from 'gs1.org.ai'

const barcode = GS1_128.encode({
  gtin: '06141411073462',
  serial: '2017',
  lot: 'LOT123',
  expiryDate: '2026-12-31',
})

DataMatrix

import { DataMatrix } from 'gs1.org.ai'

const datamatrix = DataMatrix.encode({
  gtin: '06141411073462',
  serial: '2017',
})

Business Steps

Common business step values:

const bizSteps = {
  accepting: 'urn:epcglobal:cbv:bizstep:accepting',
  arriving: 'urn:epcglobal:cbv:bizstep:arriving',
  assembling: 'urn:epcglobal:cbv:bizstep:assembling',
  commissioning: 'urn:epcglobal:cbv:bizstep:commissioning',
  decommissioning: 'urn:epcglobal:cbv:bizstep:decommissioning',
  departing: 'urn:epcglobal:cbv:bizstep:departing',
  destroying: 'urn:epcglobal:cbv:bizstep:destroying',
  dispensing: 'urn:epcglobal:cbv:bizstep:dispensing',
  packing: 'urn:epcglobal:cbv:bizstep:packing',
  receiving: 'urn:epcglobal:cbv:bizstep:receiving',
  shipping: 'urn:epcglobal:cbv:bizstep:shipping',
  unpacking: 'urn:epcglobal:cbv:bizstep:unpacking',
}

Dispositions

Common disposition values:

const dispositions = {
  active: 'urn:epcglobal:cbv:disp:active',
  available: 'urn:epcglobal:cbv:disp:available',
  damaged: 'urn:epcglobal:cbv:disp:damaged',
  destroyed: 'urn:epcglobal:cbv:disp:destroyed',
  expired: 'urn:epcglobal:cbv:disp:expired',
  in_progress: 'urn:epcglobal:cbv:disp:in_progress',
  in_transit: 'urn:epcglobal:cbv:disp:in_transit',
  recalled: 'urn:epcglobal:cbv:disp:recalled',
  reserved: 'urn:epcglobal:cbv:disp:reserved',
  sold: 'urn:epcglobal:cbv:disp:sold',
}

Example: Complete Supply Chain

import { ObjectEvent, AggregationEvent, TransactionEvent } from 'gs1.org.ai'

// 1. Manufacturing
await db.create('events', {
  type: 'ObjectEvent',
  action: 'ADD',
  bizStep: 'commissioning',
  epcList: ['urn:epc:id:sgtin:0614141.107346.2017'],
})

// 2. Packing into case
await db.create('events', {
  type: 'AggregationEvent',
  action: 'ADD',
  parentID: 'urn:epc:id:sscc:0614141.1234567890',
  childEPCs: ['urn:epc:id:sgtin:0614141.107346.2017'],
})

// 3. Shipping with PO
await db.create('events', {
  type: 'TransactionEvent',
  action: 'ADD',
  bizStep: 'shipping',
  epcList: ['urn:epc:id:sscc:0614141.1234567890'],
  bizTransactionList: [{ type: 'po', bizTransaction: 'PO-12345' }],
})

// 4. Receiving at destination
await db.create('events', {
  type: 'ObjectEvent',
  action: 'OBSERVE',
  bizStep: 'receiving',
  epcList: ['urn:epc:id:sscc:0614141.1234567890'],
})

Query Events

// Get product history
const events = await db.list('events', {
  where: {
    epcList: { contains: 'urn:epc:id:sgtin:0614141.107346.2017' },
  },
  sort: 'eventTime',
})

// Track shipment
const shipmentEvents = await db.list('events', {
  where: {
    'bizTransactionList.bizTransaction': 'PO-12345',
  },
})

Documentation

schema.org.ai - Schema.org vocabulary
products.org.ai - Product catalog
events - Event system

gs1.org.ai

On this page