GS1 JavaScript Library Usage Manual

Introduction

The GS1 library is a JavaScript tool designed for constructing and managing GS1 standard data structures, such as Application Identifiers (AIs) used in barcodes or RFID tags. It helps you encode product, logistics, and trade information into a standardized GS1 format.

Core Concepts

• Application Identifier (AI): A two to four-digit numeric prefix defined by GS1 that identifies the meaning and format of the data that follows it. For example, 01 represents the Global Trade Item Number (GTIN), and 10 represents the Batch Number.
• Element: A combination of an AI and its corresponding value, forming a complete GS1 data segment. For example, (01)12345678901231.
• FNC1 Separator: A special separator (often represented as an FNC1 character, ASCII 29, in barcodes) is required at the end of some GS1 elements to indicate the start of the next AI, especially after variable-length fields. This library's fullcode method currently simplifies the separator handling.

GS1.AI (Application Identifier Constants)

This is a static object containing common GS1 Application Identifiers and their corresponding codes. It's recommended to use these constants in the add method for better code readability and error reduction.

Category	AI Constant	GS1 AI Code	Description	Notes
Product ID	GTIN	01	Global Trade Item Number	14-digit, includes check digit
	CTN_GTIN	02	GTIN of contained trade items
	VAR	20	Product variant
Date/Time	PROD	11	Production Date (YYMMDD)
	EXP	17	Expiration Date (YYMMDD)
	PACK	13	Packaging Date (YYMMDD)
	BEST	15	Best Before Date (YYMMDD)
	SELL	16	Sell By Date (YYMMDD)
Batch/Serial	BATCH	10	Batch Number
	SERIAL	21	Serial Number
	CPV	22	Consumer Product Variant
	ADD_ID	240	Additional Product ID
	SERIAL_2	250	Secondary Serial Number
Logistic Unit	SSCC	00	Serial Shipping Container Code	18-digit, includes check digit
Quantity	QTY_VAR	30	Variable Quantity
	QTY_FIXED	37	Quantity
Weight/Dim.	NET_WT	310n	Net Weight (kg), n = decimals	e.g., 3102 for 2 decimal places
	LEN	311n	Length (m), n = decimals
	WIDTH	312n	Width (m), n = decimals
	HEIGHT	313n	Height (m), n = decimals
	AREA	314n	Area (m²), n = decimals
	VOL	315n	Net Volume (L), n = decimals
Location	DEST	410	GLN of Physical Location
	BILL_TO	415	GLN of Bill To
	SHIP_TO_LOC	420	Postal Code of Ship To
	ORIGIN	422	Country of Origin
Amount	AMOUNT	390n	Amount Payable, n = decimals
Internal Use	INTERNAL	90	Company Internal Information
	INT_91_99	91-99	Company Internal Use Range	Note: 91-99 is a range description, not a single AI

GS1.check_digit(s) (Static Method)

Calculates the GS1 check digit.

• Parameters:
  • s (String): The numeric string for which to calculate the check digit.
• Returns:
  • (Number): The calculated check digit.
• Usage: Use when generating codes like GTIN or SSCC that require a check digit.

1const checkDigit = GS1.check_digit('1234567890123'); // Calculate GTIN check digit
2console.log(checkDigit); // Outputs the check digit

new GS1() (Constructor)

Creates a new GS1 instance. Each instance can contain a set of GS1 elements.

1const myGs1Data = new GS1();

gs1.add(ai, value) (Instance Method)

Adds a GS1 element to the GS1 instance.

• Parameters:
  • ai (String): The Application Identifier (AI), which can be a constant from GS1.AI or a custom 2-4 digit string.
  • value (String): The data value associated with the AI.
• Returns:
  • this (GS1 instance): Allows for method chaining.
• Throws Errors:
  • If ai format is incorrect.
  • If attempting to add a duplicate ai.
  • For GTIN and SSCC, if the value length or check digit does not comply with specifications.
• Special Handling:
  • GTIN (AI '01') / CTN_GTIN (AI '02'): If the provided value is less than 14 digits, it will automatically pad with leading zeros and calculate the check digit. If a 14-digit value is provided, it will validate if the 14th digit is the correct check digit.
  • SSCC (AI '00'): If the provided value is 17 digits, it will automatically calculate and append the check digit to make it 18 digits. If an 18-digit value is provided, it will validate if the 18th digit is the correct check digit.

 1const gs1 = new GS1();
 2
 3gs1.add(GS1.AI.GTIN, '0123456789012') // Auto-pads to 14 digits and calculates check digit
 4   .add(GS1.AI.BATCH, 'A123B')
 5   .add(GS1.AI.EXP, '251231'); // Expiration date, e.g., December 31, 2025
 6
 7// Trying to add a duplicate AI will throw an error
 8try {
 9    gs1.add(GS1.AI.BATCH, 'C456D');
10} catch (e) {
11    console.error(e.message); // AI duplicate: (10)
12}
13
14// SSCC example
15const gs1Sscc = new GS1();
16gs1Sscc.add(GS1.AI.SSCC, '01234567890123456'); // Auto-pads to 18 digits and calculates check digit

gs1.fullcode() (Instance Method)

Generates the complete encoded string containing all added GS1 elements.

• Returns:
  • (String): A string formatted as (AI)VALUE(AI)VALUE....
• Note: In the current implementation, each AI and its value are enclosed in parentheses, but no FNC1 (ASCII 29) separator character is added. In actual GS1 barcode or RFID applications, FNC1 is usually required after variable-length fields. If you need to generate a string containing FNC1, you may need to modify the _requiresSeparator and fullcode methods.

1const gs1 = new GS1();
2gs1.add(GS1.AI.GTIN, '0123456789012')
3   .add(GS1.AI.BATCH, 'BATCHABC');
4
5console.log(gs1.fullcode()); // Output: (01)01234567890123(10)BATCHABC

gs1._requiresSeparator(ai) (Internal Method)

This method is for internal use and generally not recommended for direct calling. Determines if a given AI requires an FNC1 separator character after its value. In the current implementation, it checks against the separatorsNeeded array.

gs1.get(ai) (Instance Method)

Retrieves the value corresponding to a specified AI.

• Parameters:
  • ai (String): The Application Identifier to query.
• Returns:
  • (String|null): Returns the corresponding value if found; otherwise, returns null.

1const gs1 = new GS1();
2gs1.add(GS1.AI.GTIN, '0123456789012');
3
4console.log(gs1.get(GS1.AI.GTIN)); // Output: 01234567890123
5console.log(gs1.get(GS1.AI.BATCH)); // Output: null

gs1.clear() (Instance Method)

Clears all added elements from the GS1 instance.

• Returns:
  • this (GS1 instance): Allows for method chaining.

1const gs1 = new GS1();
2gs1.add(GS1.AI.GTIN, '123').add(GS1.AI.BATCH, 'XYZ');
3console.log(gs1.getAIs()); // ['01', '10']
4
5gs1.clear();
6console.log(gs1.getAIs()); // []

gs1.getAIs() (Instance Method)

Retrieves a list of all Application Identifiers currently added to the GS1 instance.

• Returns:
  • (Array): An array containing all added AIs.

1const gs1 = new GS1();
2gs1.add(GS1.AI.GTIN, '123').add(GS1.AI.EXP, '251231');
3
4console.log(gs1.getAIs()); // Output: ['01', '17']

gs1.has(ai) (Instance Method)

Checks if the GS1 instance contains the specified Application Identifier.

• Parameters:
  • ai (String): The Application Identifier to check.
• Returns:
  • (Boolean): Returns true if it contains the AI, otherwise false.

1const gs1 = new GS1();
2gs1.add(GS1.AI.GTIN, '123');
3
4console.log(gs1.has(GS1.AI.GTIN));    // Output: true
5console.log(gs1.has(GS1.AI.BATCH));   // Output: false

Complete Usage Example

 1// Assume gs1_check_digit function is defined globally or imported
 2function gs1_check_digit(s) {
 3    let sum = 0;
 4    for (let i = 0; i < s.length; i++) {
 5        const digit = parseInt(s[s.length - 1 - i], 10);
 6        sum += (i % 2 === 0) ? digit * 3 : digit;
 7    }
 8    const remainder = sum % 10;
 9    return (remainder === 0) ? 0 : 10 - remainder;
10}
11
12
13const myProductGs1 = new GS1();
14
15try {
16    myProductGs1.add(GS1.AI.GTIN, '0123456789012') // 13-digit GTIN, auto-pads with 0 and check digit
17                .add(GS1.AI.BATCH, 'LotX-789')    // Batch Number
18                .add(GS1.AI.PROD, '231026')       // Production Date: October 26, 2023
19                .add(GS1.AI.EXP, '251026')        // Expiration Date: October 26, 2025
20                .add(GS1.AI.QTY_FIXED, '100')     // Quantity: 100
21                .add('90', 'InternalRefABC');     // Internal Use Information
22
23    console.log("All added AIs:", myProductGs1.getAIs());
24    console.log("GTIN Value:", myProductGs1.get(GS1.AI.GTIN));
25    console.log("Full GS1 Code:", myProductGs1.fullcode());
26
27    // Try adding a 17-digit SSCC without a check digit
28    const ssccGs1 = new GS1();
29    ssccGs1.add(GS1.AI.SSCC, '00012345678901234'); // 17-digit SSCC, auto-adds check digit
30    console.log("SSCC Value:", ssccGs1.get(GS1.AI.SSCC));
31    console.log("Full SSCC Code:", ssccGs1.fullcode());
32
33    // Check if an AI exists
34    console.log("Contains Batch Number:", myProductGs1.has(GS1.AI.BATCH)); // true
35    console.log("Contains Net Weight:", myProductGs1.has(GS1.AI.NET_WT)); // false
36
37    // Clear the instance
38    myProductGs1.clear();
39    console.log("All added AIs after clearing:", myProductGs1.getAIs()); // []
40
41} catch (e) {
42    console.error("An error occurred:", e.message);
43}

---

`