netex2-java-model

Java model classes generated from NeTEx (Network Timetable Exchange) XML Schema Definition (XSD) files using JAXB. Maintained by Entur AS.

Overview

This library downloads the NeTEx XSD files from the NeTEx repository and compiles them into JAXB-annotated Java model classes at build time. The generated classes support full marshalling and unmarshalling of NeTEx XML documents, including schema validation against multiple NeTEx versions. The legacy schemas used only for validation (1.04beta - 1.16.1) are downloaded from the Entur NeTEx fork.

• NeTEx version: 2.0 (model generation), with legacy validation support back to 1.04beta
• JAXB: Jakarta XML Bind 4.x (Jakarta EE 9+)
• Generated package: org.entur.netex2.model
• GML types package: net.opengis.gml._3
• SIRI types package: uk.org.siri.siri
• JPMS module: org.entur.netex2

Usage

Release (Maven Central)

<dependency>
    <groupId>org.entur</groupId>
    <artifactId>netex2-java-model</artifactId>
    <version>LATEST</version>
</dependency>

See Maven Central for the latest released version.

Snapshot

Snapshots are published to the Sonatype snapshot repository. Add the repository to your pom.xml:

<repositories>
    <repository>
        <id>sonatype-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

Then add the dependency with the snapshot version:

<dependency>
    <groupId>org.entur</groupId>
    <artifactId>netex2-java-model</artifactId>
    <version>LATEST-SNAPSHOT</version>
</dependency>

Building from Source

Prerequisites

• Java 21+
• Maven 3.x
• xmlstarlet (apt install xmlstarlet on Debian/Ubuntu, brew install xmlstarlet on macOS)

Build

# Full build: downloads XSD files, generates JAXB classes, compiles, runs tests
mvn clean install

# Run tests only
mvn test

# Package without running tests
mvn package -DskipTests

The XSD files are downloaded from GitHub during the generate-sources phase and placed under src/main/resources/xsd/. The JAXB model is generated into target/generated-sources/xjc/.

Project Structure

├── bin/
│   ├── netex-download-extract.sh   # Downloads NeTEx XSD from GitHub
│   ├── annotation-replacer.sh      # Post-processes generated Java files
│   ├── generate-dummy-bindings.py  # Regenerates the bindings hiding the _Dummy suffix
│   └── version_updater.sh          # Updates version references in bindings
├── bindings.xjb                    # JAXB customization bindings
├── src/main/java/org/entur/
│   └── netex2/                     # NeTEx utilities (validation, client, toString style)
│       └── util/                   # XML adapters for Java time types
├── src/main/resources/xsd/         # Downloaded NeTEx XSD files (build artifact)
└── src/test/                       # JUnit 5 marshalling/unmarshalling tests

Key Technical Details

JAXB customizations (bindings.xjb):

• Java time type adapters: LocalDateTime, LocalDate and LocalTime via adapters in org.entur.netex2.util, Duration via threeten-jaxb-core
• Fluent builder API (withX() methods) via jaxb-fluent-api
• Property name conflict resolution
• Package mapping to org.entur.netex2.model
• Hiding of the _Dummy suffix that NeTEx 2.0 puts on abstract substitution-group heads (DayType_Dummy is the head of DayType): containers expose getDayType() instead of getDayType_Dummy(), ObjectFactory exposes createDayType_(...) and the few classes generated for such heads keep a trailing underscore, as in netex-java-model 2.x. These bindings are generated by bin/generate-dummy-bindings.py and must be regenerated when the schema is upgraded.

Schema validation: NeTExValidator supports validation against NeTEx versions 1.04beta through 2.0. A version is validated against its latest patch schema: documents declaring 1.16 are validated against the 1.16.1 schema, which is backward compatible with 1.16.

Note on GML and SIRI types: This library generates classes under net.opengis.gml._3 and uk.org.siri.siri as part of the NeTEx model. These packages are the same as in netex-java-model 2.x, so both libraries can share a classpath but not a module path.

License

Licensed under the European Union Public Licence (EUPL) version 1.2.

Related Projects

• netex-protobuf — NeTEx XSD files converted to protobuf descriptors
• NeTEx (Entur fork) — NeTEx XSD source files used by this library