# Gs1 key validate

`gs1-key-validate` · version 1.0.0 · Identifiers & check digits · free, no key needed

Validate a GTIN-8/12/13/14, GLN, SSCC or GSIN's GS1 mod-10 check digit and look up its 3-digit GS1 prefix meaning.

**Use when you need to: validate a gtin barcode number · check digit for an sscc pallet label · is this gln location number valid.**

## Decide before calling

Read the [versioned contract](/v1/tools/gs1-key-validate/versions/1.0.0) and the supported scope below. Reuse `gs1-key-validate@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `gs1-key-validate@1.0.0` for validate a gtin barcode number. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- validate a gtin barcode number
- check digit for an sscc pallet label
- is this gln location number valid
- gs1 mod 10 check digit validator
- what does this gtin prefix mean
- validate a gsin shipment number

## Not supported

- a bare gs1-mod10 algorithm over an arbitrary payload (use checkdigit-validate)
- converting between UPC/EAN/GTIN symbol formats (use upc-ean-convert)
- parsing a full GS1 AI element string (use gs1-element-string-parse)
- a live GEPIR company/product lookup

## Behavior

- key is taken exactly as given; no trimming. Allowed lengths per key_type: gtin -> 8, 12, 13 or 14; gln -> 13; sscc -> 18; gsin -> 17.
- A length outside those for key_type returns {valid:false, reason:'wrong_length'} with gtin14/gs1_prefix/prefix_usage/member_organisation null; a right-length non-digit value returns reason 'invalid_character' with the same null fields.
- gtin14 is key left-zero-padded to 14 characters when key_type is gtin, else null. gs1_prefix is a 3-digit slice: gtin14[1:4] for a gtin of length 12, 13 or 14; key[0:3] (the GS1-8 Prefix, never the zero padding) for a gtin of length 8; key[1:4] for sscc (skips the extension digit); key[0:3] for gln and gsin.
- prefix_usage and member_organisation use the GS1 central allocation snapshot dated 2026-10-01. A GTIN-8 whose GS1-8 Prefix starts with 0 or 2 is restricted_circulation (RCN-8); 050-059 -> reserved; GTIN-8 960, 961, 9620-9624 -> GS1 UK; 9625-9626 -> GS1 Poland; remaining 960-969 -> GS1 Global Office only for GTIN-8; 981-983 -> coupon. Otherwise the pinned prefix table applies: 950 -> GS1 Global Office, 951 -> epc, 952 -> demonstration, 977 -> issn, 978-979 -> bookland_isbn except 9790 -> ismn. Unlisted allocations return reserved in this snapshot, independent of check-digit validity.
- The check digit is the GS1 mod-10 check over key (weights 3,1 alternating from the rightmost digit); a mismatch returns reason check_digit_mismatch with all other fields still populated.
- data_version identifies the dated partial prefix-table audit and the explicitly unknown syntax-dictionary release, returned on every call.

## Input

- `key` (string, required): min length 1; max length 18
- `key_type` (one of "gtin", "gln", "sscc", "gsin", required)

## Output

- `valid` (boolean, required)
- `reason` (one of null, "wrong_length", "invalid_character", "check_digit_mismatch", required)
- `key_type` (one of "gtin", "gln", "sscc", "gsin", required)
- `length` (integer, required): min 1; max 18
- `gtin14` (string or null, required): pattern `^[0-9]{14}$`
- `gs1_prefix` (string or null, required): pattern `^[0-9]{3}$`
- `prefix_usage` (one of null, "member_organisation", "restricted_circulation", "coupon", "bookland_isbn", "ismn", "issn", "refund_receipt", "reserved", "demonstration", "epc", required)
- `member_organisation` (string or null, required)
- `data_version` (constant "gs1-central-prefix-snapshot-2026-10-01.gs1-syntax-dictionary-unknown-release", required)

## Limits

- max key bytes: 18

## Example

Request input:

```json
{
  "key": "4006381333931",
  "key_type": "gtin"
}
```

Response:

```json
{
  "result": {
    "valid": true,
    "reason": null,
    "key_type": "gtin",
    "length": 13,
    "gtin14": "04006381333931",
    "gs1_prefix": "400",
    "prefix_usage": "member_organisation",
    "member_organisation": "GS1 Germany",
    "data_version": "gs1-central-prefix-snapshot-2026-10-01.gs1-syntax-dictionary-unknown-release"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "gs1-key-validate",
  "version": "1.0.0",
  "input": {
    "key": "4006381333931",
    "key_type": "gtin"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/gs1-key-validate/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"key":"4006381333931","key_type":"gtin"}'
```

The machine-readable contract is at [/v1/tools/gs1-key-validate/versions/1.0.0](/v1/tools/gs1-key-validate/versions/1.0.0).

### CLI

```sh
node cli.mjs run gs1-key-validate 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Checkdigit validate](/tools/checkdigit-validate): Validate a full value's trailing check digit(s) against a named algorithm (Luhn, Verhoeff, Damm, ISO 7064, GS1, mod 10).
- [Isin validate](/tools/isin-validate): Validate a 12-character ISIN's ISO 6166 Luhn check digit and parse its country prefix, NSIN and NSIN scheme.
- [Imo number validate](/tools/imo-number-validate): Validate a 7-digit IMO ship identification number's weighted mod-10 check digit, with or without the 'IMO ' prefix.
- [Isbn validate](/tools/isbn-validate): Validate an ISBN-10 (mod 11, X allowed) or ISBN-13 (EAN mod 10) check digit and return the other form when it exists.
- [Ismn validate](/tools/ismn-validate): Validate an ISMN's EAN mod 10 check digit in M-form or 979-0 form and return the canonical 13-digit form.
- [Issn validate](/tools/issn-validate): Validate an 8-digit ISSN's mod 11 check digit (X allowed) and compute its 977-prefixed EAN-13 barcode form.