Fast and simple way to parse/format/validate ISBNs with the official ISBN ranges definition. The parser is optimized for speed, the ISBN class for simplicity.
This library can evaluate millions of ISBNs per second on a single CPU core.

fast-isbn – world's fastest ISBN range validation

A common issue in digital commerce systems is to validate article identifiers. In the publishing business there is the so-called ISBN standard¹, maintained by the International ISBN Agency. By using their official ISBN range definitions this library offers up-to-date ISBN validation beyond simply comparing the EAN-13 checkdigit, and adds ISO 2108¹ conform formatting for the extended² and compact form³.

All number ranges that are not yet assigned to a local ISBN agency group⁴ or whose publisher range⁵ is not defined will be treated as invalid. The dashes will be inserted automatically at the correct positions for grouping the isbn prefix⁶, agency group code⁴, publisher code⁵, title code⁷, and checkdigit⁸.

Examples:

• 😢 wrong grouping: 978-05-5750-469-5 or 978-0557504695 (e.g. on amazon.com)
• correct ISO 2108 grouping: 978-0-557-50469-5
• invalid ISBN-10 checksum: 9980-43-192-9
• correct ISBN-10 checksum: 9980-43-192-X

The ISBN domain object wraps the ISBN string representation efficiently to be used as identifier in your domain-driven code base. It normalizes and corrects the given string input with respect to hyphens/dashes, parsing both ISBN-10 and ISBN-13 numbers into the same object, the ISBN.

Usage (latest version "1.1.6")

You only need to install de.creativecouple.validation:fast-isbn as dependency in your Java/Kotlin/Scala project definition,

as Maven dependency in your pom.xml,

<dependencies>
    …
    <dependency>
        <groupId>de.creativecouple.validation</groupId>
        <artifactId>fast-isbn</artifactId>
        <version>1.1.6</version>
    </dependency>
</dependencies>

as Gradle dependency in your build.gradle,

implementation group: 'de.creativecouple.validation', name: 'fast-isbn', version: '1.1.6'

or as Scala dependency in your build.sbt.

libraryDependencies += "de.creativecouple.validation" % "fast-isbn" % "1.1.6"

Parsing

Now you can simply convert your strings into ISBN objects via:

  ISBN isbn = ISBN.valueOf(someString);

This will potentially throw a NumberFormatException if the input string is not a valid ISBN.

You can get different string representations to be used e.g. in your databases:

  ISBN isbn = ISBN.valueOf("978-0557504695"); // wrong hyphenation on amazon.com

  isbn.toString();        // standard representation = "978-0-557-50469-5"
  isbn.toCompactString(); // compact representation = "9780557504695"
  isbn.toIso2108();       // ISO-2108 representation = "ISBN 978-0-557-50469-5"
  
  isbn.getPrefix();          // EAN/UCC prefix = "978" 
  isbn.getPrefixName();      // EAN/UCC prefix's agency name = "International ISBN Agency" 
  isbn.getGroup();           // group code = "0" 
  isbn.getGroupPrefix();     // group's ISBN prefix = "978-0" 
  isbn.getGroupName();       // group's agency name = "English language" 
  isbn.getPublisher();       // publisher code = "557" 
  isbn.getPublisherPrefix(); // publisher's ISBN prefix = "978-0-557" 
  isbn.getTitle();           // title code = "50469" 
  isbn.getCheckdigit();      // checkdigit character = '5'

  isbn.toUri();              // URI("urn:isbn:9780557504695")

Validating

If you only want to work with Strings instead of the ISBN object you can simply use the ISBNValidator to check them against the chosen rules. This is one of the 12 combinations of ISBN length (ISBN-10 / ISBN-13 / both) and hyphenation style (any / correct / none / correct-or-none).

  ISBNValidator validator = ISBNValidator.isbn10().hyphenation(NONE);
        
  validator.isValid("978-0-557-50469-5"); // false
  validator.isValid("9780557504695"); // false
  validator.isValid("0-557-50469-4"); // false
  validator.isValid("0557504694"); // true

Runtime updates

Since version 1.1.* you can call the static method

ISBN.updateRangeDefinition();

to replace the built-in ISBN range definition with the latest version online. For that your application must be able to make outgoing https calls to raw.githubusercontent.com.

Javadoc

Read the full Java docs online at javadoc.io/…/fast-isbn/latest/.

Versioning

Our build pipeline regularly checks for new versions of the ISBN range definition provided by the International ISBN Agency. When there are changes then a new version of this library will be deployed.

Demo

You can find an online service using this validation at https://creativecouple.de/validation/isbn/ .

Contribute

You can clone this repository locally and build as a standard maven project. Feel free to open issues to this repository or create pull requests.

Disclaimer

The MIT License (MIT) Copyright (c) 2024 CreativeCouple

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Footnotes

1. International Standard Book Number (ISBN) ISO 2108:2017 ↩ ↩²

2. Human readable form of the ISBN uses the correct grouping together with the word "ISBN", example ISBN 978-90-70002-34-3 ↩

3. Alternative compact form of the ISBN, for data processing purposes, example 9789070002343 ↩

4. Registration group element, length-varying second part of the ISBN, also known as local agency group, allocated by the Registration Authority ↩ ↩²

5. Registrant element, length-varying third part of the ISBN, also known as publisher, allocated by the Registration Group (local agency) ↩ ↩²

6. GS1 prefix (formerly known as EAN/UCC prefix), first three digits of the ISBN, defined by the Registration Authority ↩

7. Publication element, length-varying fourth part of the ISBN, also known as book title number, assigned by the Registrant (publisher) ↩

8. Checkdigit, last digit of the ISBN, calculated using the "modulus 10" algorithm ↩