An open-source SDK and web application to build profiles for visibility event data (modeled as EPCIS events) and to validate EPCIS events against those profiles using JSON Schema.
EPCIS (Electronic Product Code Information Services) is a GS1 standard for supply chain visibility and traceability. It enables organisations to capture and share event data in 5 dimensions — WHAT, WHEN, WHERE, WHY and HOW — using a common language across enterprises.
An event profile is a set of machine-readable validation rules that define what a compliant EPCIS event must look like. While the EPCIS standard is deliberately flexible and open-ended, businesses and industry associations often need to enforce stricter, shared rules to ensure data quality and compliance.
Consider a supply chain where there is industry-wide agreement to capture and share EPCIS Shipping Events with downstream trading partners. An industry association could provide an actionable, machine-readable profile that formally defines the required rules. For example:
typeMUST beObjectEventbizStepMUST include eitherdepartingorshippingepcListMUST contain at least one SSCC (Serial Shipping Container Code)readPointMUST be a GLN (Global Location Number) without extension- All GS1 identifiers MUST be valid GS1 Digital Link URIs
- An extension field (ETA) MUST contain a valid date-time value
View the corresponding JSON Schema profile
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"allOf": [
{
"$ref": "https://ref.gs1.org/standards/epcis/epcis-json-schema.json"
},
{
"type": "object",
"properties": {
"@context": {
"contains": {
"type": "object",
"properties": {
"example": {
"const": "http://example.com/"
}
},
"required": [
"example"
]
}
},
"type": {
"const": "EPCISDocument"
},
"epcisBody": {
"type": "object",
"properties": {
"eventList": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"ObjectEvent"
]
},
"bizStep": {
"type": "string",
"enum": [
"departing",
"shipping"
]
},
"epcList": {
"type": "array",
"items": {
"type": "string",
"pattern": "^https?:\\/\\/([^\\/?#:]+)(:([0-9]*))?(\\/[^?#]*)*\\/00\\/\\d{18}$"
}
},
"readPoint": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^https?:\\/\\/([^\\/?#:]+)(:([0-9]*))?(\\/[^?#]*)*\\/414\\/\\d{13}(\\/254\\/([a-zA-Z0-9_\".-]|%2[a-cA-CfF15-9]|%3[a-fA-F]){1,20})?$"
}
},
"required": [
"id"
]
},
"example:estimatedTimeOfArrival": {
"type": "string",
"format": "date-time"
}
},
"required": [
"type",
"bizStep",
"epcList",
"readPoint",
"example:estimatedTimeOfArrival"
],
"additionalProperties": true
}
}
},
"required": [
"eventList"
]
}
},
"required": [
"epcisBody",
"type"
],
"additionalProperties": true
}
]
}Following is the corresponding EPCIS Document generated using OpenEPCIS Test Data Generator that matches the above profile:
View the corresponding EPCIS Document
{
"@context": [
{
"example": "http://example.com/"
},
"https://ref.gs1.org/standards/epcis/epcis-context.jsonld"
],
"type": "EPCISDocument",
"schemaVersion": "2.0",
"creationDate": "2026-04-02T12:43:58.63Z",
"epcisBody": {
"eventList": [
{
"type": "ObjectEvent",
"eventTime": "2026-04-02T14:42:36+02:00",
"eventTimeZoneOffset": "+02:00",
"epcList": [
"https://id.gs1.org/00/092567800000000018"
],
"action": "OBSERVE",
"bizStep": "shipping",
"readPoint": {
"id": "https://id.gs1.org/414/9520123456788"
},
"example:estimatedTimeOfArrival": "2026-04-02T14:30:00Z"
}
]
}
}This is exactly the type of use case the EPCIS Profile Checker is designed to support. It enables industry associations to define such profiles in a machine-readable form using JSON Schema, and allows these rules to be consistently enforced through automated validation.
Any member of the supply chain can use the same profile to independently verify whether their events comply with the agreed rules — before sharing them with trading partners. The result is:
- Higher and more consistent data quality
- Significantly reduced manual validation effort
- Faster onboarding and shorter time to market for new partners
- Validate events against custom JSON Schema profiles using AJV
- Detect document types — EPCISDocument or bare events
- Type checking utilities — verify event types (ObjectEvent, AggregationEvent, TransactionEvent, TransformationEvent, AssociationEvent)
- Profile rule schemas — built-in schemas for profile detection and validation rules
- Dual build targets — works in both Node.js and browser environments
A full-featured web UI is available as Web Application or source code at openepcis-snippet-web:
Profile Builder Visually create JSON Schema profiles for EPCIS document/event validation |
Event Validator Validate EPCIS events against profiles with instant compliance feedback |
Snippet Search Search and filter reusable EPCIS event snippets from the library |
The quickest way to get started. Pull and run the pre-built container:
# Docker
docker pull ghcr.io/openepcis/openepcis-snippet-web:latest
docker run -p 3000:3000 ghcr.io/openepcis/openepcis-snippet-web:latest
# Podman
podman pull ghcr.io/openepcis/openepcis-snippet-web:latest
podman run -p 3000:3000 ghcr.io/openepcis/openepcis-snippet-web:latestOpen http://localhost:3000 in your browser.
With Docker Compose:
services:
openepcis-snippet-web:
image: ghcr.io/openepcis/openepcis-snippet-web:latest
ports:
- "3000:3000"
environment:
- NUXT_PUBLIC_SNIPPET_API_URL=https://api.epcis.cloud
restart: unless-stoppeddocker-compose up -dFor more Docker options and environment variables, see the openepcis-snippet-web repository.
Requires Node.js 18+ and pnpm.
git clone https://github.com/openepcis/openepcis-snippet-web.git
cd openepcis-snippet-web
pnpm install
pnpm dev
Open http://localhost:3000 in your browser.
The examples/ directory contains paired EPCIS events and their corresponding validation profiles:
epcis-events/— Sample EPCIS event documentsepcis-profiles/— Matching JSON Schema profiles for validation
The json-schema-epcis-snippets/ directory contains reusable JSON Schema components for building custom profiles.
We welcome contributions! Here are ways to get involved:
- Bug Reports — identify and report issues
- Feature Requests — suggest improvements
- Pull Requests — submit code changes or new profiles
- Documentation — help improve guides and examples
Please review the Code of Conduct before contributing.