GBIF Name Parser API

The data model and parser contract for scientific names — ParsedName,
Authorship, Rank, NomCode, NameType, the NameParser interface and the
ParseResult it returns — plus name formatting and rank/unicode utilities.

As of 5.0.0 this repository is API-only: it ships the single
name-parser-api artifact. The parsing engine has been reimplemented in Rust
(with the full regression corpus), and is consumed through this interface via a
native binding. The previous Java implementation (NameParserImpl and the
name-parser / name-parser-cli modules) lives on the 4.x branch for
maintenance; see Migrating from 4.x to 5.0.

What's in here

Library use

<dependency>
  <groupId>org.gbif</groupId>
  <artifactId>name-parser-api</artifactId>
  <version>5.0.0</version>
</dependency>

parse(...) never throws — it returns a sealed, three-way ParseResult:

• Parsed — a fully structured ParsedName (its state() may be COMPLETE or PARTIAL).
• Informal — a semistructured name: a real supraspecific taxon carrying a provisional,
  non-code designation instead of a determined species epithet — a molecular provisional species
  (Rhizobium sp. RMCC TR1811), a numbered placeholder (Allium sp. 1), or an informal group
  (Bartonella group). It is a flat taxon / taxonRank / rank / phrase / code and carries
  no ParsedName — the anchor is unvalidated, so it is never mislabelled as a determined genus.
  Names that keep a species epithet — including cf./aff. and infraspecific-indeterminate ones —
  stay Parsed, so their specificAuthorship (which a flat anchor could not hold) survives.
• Unparsable — not a scientific name at all: a virus, a hybrid formula, a placeholder, or a
  machine identifier such as a BOLD BIN / UNITE SH / OTU / culture-collection accession. type()
  classifies it — FORMULA, PLACEHOLDER, IDENTIFIER, or OTHER.

type() and code() are available on all three variants, so you can classify without catching
anything:

NameParser parser = new NameParserRust(); // the native (Rust-backed) implementation — see below

switch (parser.parse("Rhizobium sp. RMCC TR1811", null, null, null)) {
  case ParseResult.Parsed p     -> index(p.name());                     // a full ParsedName
  case ParseResult.Informal i   -> indexInformal(i.taxon(), i.phrase()); // "Rhizobium" + "RMCC TR1811"
  case ParseResult.Unparsable u -> record(u.type(), u.code());          // type FORMULA/PLACEHOLDER/IDENTIFIER/OTHER, code e.g. VIRUS
}

Any variant round-trips back to a string via NameFormatter.canonical(result) — the reconstructed
name for Parsed, the informal name (Rhizobium sp. RMCC TR1811) for Informal, the verbatim
input for Unparsable — or call NameFormatter.canonical(informal) on an Informal directly.

It composes in streams:

List<ParsedName> parsed = names.stream()
    .map(n -> parser.parse(n, null, rank, code))
    .flatMap(r -> r.parsed().stream()) // keeps only Parsed; Informal + Unparsable have an empty parsed()
    .toList();

…and offers an opt-in fail-fast path for callers that want it:

ParsedName pn = parser.parse(name).orElseThrow(); // throws unchecked UnparsableNameException

Only need the model or the formatter (no parsing)? Depend on this artifact and
use ParsedName / NameFormatter directly — no implementation required.

The parsing engine (Rust)

From 5.0 the reference implementation lives in a separate project,
gbif/name-parser-rust. The
parser core is a Rust crate (nameparser), which also carries the full
regression corpus ported from the old Java suite, and is exposed through several
bindings — a C-ABI cdylib (nameparser-ffi) and a Python module
(nameparser-py).

Java callers get a NameParser from that project's Panama binding:
org.gbif.nameparser.rust.NameParserRust implements
org.gbif.nameparser.api.NameParser from this module by downcalling the Rust
cdylib in-process via java.lang.foreign (FFM/Panama, stable since JDK 22 — no
--enable-preview). Each parse marshals across the FFI boundary and rebuilds
a ParsedName from a flat binary struct. Because java.lang.foreign needs a
modern JDK, that binding targets JDK 25+ and is
built and released independently of this Java-17 API module — which is exactly
why the API stays on 17: model- and formatter-only consumers keep the broad
baseline, while only the native binding requires the newer JDK.

Depending on the Rust binding (to actually parse)

This api artifact carries no parser on its own. For a working NameParser, add the native
binding — org.gbif.nameparser:name-parser-rust, from
gbif/name-parser-rust — which pulls this
name-parser-api in transitively. It ships as a thin main JAR plus one native classifier JAR per
platform (netty-tcnative style), so you download only your own architecture's cdylib. Requires
JDK 25+.

<build><extensions>
  <!-- resolves ${os.detected.classifier}: linux-x86_64, osx-aarch_64, windows-x86_64, … -->
  <extension>
    <groupId>kr.motd.maven</groupId>
    <artifactId>os-maven-plugin</artifactId>
    <version>1.7.1</version>
  </extension>
</extensions></build>

<dependencies>
  <dependency>                    <!-- thin main JAR: Java + FFM loader (brings name-parser-api) -->
    <groupId>org.gbif.nameparser</groupId>
    <artifactId>name-parser-rust</artifactId>
    <version>0.1.0-SNAPSHOT</version>
  </dependency>
  <dependency>                    <!-- your platform's native cdylib -->
    <groupId>org.gbif.nameparser</groupId>
    <artifactId>name-parser-rust</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <classifier>${os.detected.classifier}</classifier>
  </dependency>
</dependencies>

The binding is published to GBIF's Nexus; if your build doesn't already resolve from it, add:

<repositories>
  <repository>
    <id>gbif-all</id>
    <url>https://repository.gbif.org/content/groups/gbif</url>
  </repository>
</repositories>

0.1.0-SNAPSHOT is auto-deployed on every push to main (a released 0.1.0 will follow); the
binding tracks the Rust engine's own version line, independent of this api's 5.0.0. Then just
construct it — no other wiring, and the same NameParser interface as before:

NameParser parser = new org.gbif.nameparser.rust.NameParserRust();

Migrating from 4.x to 5.0

5.0 keeps the same model but changes the parser contract and drops the bundled
Java engine.

• parse(...) returns a three-way ParseResult, not ParsedName, and no longer throws.
  Replace try { ParsedName pn = parser.parse(…); } catch (UnparsableNameException e) { … }
  with a switch over Parsed | Informal | Unparsable, or parser.parse(…).parsed() /
  .orElseThrow(). type() and code() are on all three variants, so failure
  classification no longer needs the exception.
• Informal / semistructured names are now their own Informal result, not a ParsedName.
  Names that 4.x returned as a ParsedName with type = INFORMAL and no species epithet — a
  supraspecific taxon plus a provisional designation (Genus sp. <tag>, Bartonella group) — now
  come back as a flat ParseResult.Informal (taxon / taxonRank / rank / phrase / code)
  that carries no ParsedName. A switch that previously handled only Parsed and Unparsable
  must add the Informal arm. (Names that keep a species epithet — cf./aff., strain, infraspecific
  indet — stay Parsed as before.)
• parseAuthorship(...) returns Optional<ParsedAuthorship> instead of
  throwing.
• UnparsableNameException is now unchecked (extends RuntimeException) and
  is only raised by ParseResult.orElseThrow().
• The Java parser is gone from this repo. new NameParserImpl() no longer
  exists in 5.0 — obtain a NameParser from the native binding instead. If you
  need the pure-Java engine, stay on the 4.x branch (name-parser 4.2.x),
  which keeps the old throwing API and NameParserImpl.

Model/vocabulary changes introduced across the 4.x line (still current in 5.0)
are documented in the 4.x branch README — notably NameType.VIRUS/OTU
removal (viruses now carry code = VIRUS), Rank.DIVISION → DIVISION_ZOOLOGY
plus a new DIVISION_BOTANY, imprint years moving to Authorship, and the
CombinedAuthorshipIF / publishedInYear / generic-&-specific-authorship
additions.

Build

mvn install from the repo root — a single-module Java 17 build.

License

Apache 2.0.