matsim-schemas

This repository is the source of truth for MATSim schema definitions and generated language bindings.

Repository Layout

proto/ contains the canonical Protocol Buffer definitions. It is also the public protobuf import root, so imports from other repositories should be resolved relative to proto/.

Language-specific packages are generated from those schemas:

• Java classes are generated by the Maven module in java/.
• Rust message types and downstream build helpers are provided by the Cargo crate declared in Cargo.toml.

Other repositories may still use proto/ directly for their own code generation when they need bindings for another language or a different build system.

Schema Compatibility

Buf checks protect the protobuf compatibility surface in proto/. Run these commands before changing published schemas:

buf build
buf lint
buf breaking --against '.git#branch=main,subdir=proto'

For releases, compare against the last published tag:

buf breaking --against '.git#tag=<last-release-tag>,subdir=proto'

Buf is used only for schema validation and compatibility checks. Java code generation remains in Maven, and Rust code generation remains in prost-build.

Compatible Schema Changes

Prefer additive protobuf evolution. Adding new messages, enum values, or new fields with new field numbers is the normal compatibility path.

Do not reuse field numbers or field names after removing a field. Reserve them instead:

message Example {
  reserved 4;
  reserved "old_field";
}

Avoid changing the type, meaning, package, file path, or field number of an existing schema element. Buf checks these compatibility rules with FILE breaking-change detection because individual .proto file paths are part of the public import surface.

Intentional Breaking Changes

When possible, introduce a parallel versioned schema instead of changing an existing wire contract. For example, add a new v2 package/path while keeping the existing schemas available for consumers that still depend on them.

If a breaking change is intentional and approved for a major release, maintainers may apply the schema-breaking-approved pull request label. That label skips only the buf breaking comparison in CI. buf build, buf lint, the Rust build, and the Java build must still pass.

Versioning

Use one Git tag per released schema version:

vX.Y.Z

Publish the Java artifact and Rust crate from the same tag with the same version number. Java development versions should use the next -SNAPSHOT version, while Rust should be set to the exact version that will be released before tagging.

After the first stable release the version number is <major>.<minor>.<patch>:

• PATCH: packaging, documentation, or build fixes without schema API changes.
• MINOR: backward-compatible schema additions.
• MAJOR: Buf-detected breaking changes or generated API breaks.

The first stable compatibility promise starts at v1.0.0. Published 0.x versions should still avoid unnecessary breaks because consumers are expected to pin released versions rather than depend on main.

Java Consumers

Once published, Java consumers should depend on:

<dependency>
  <groupId>org.matsim</groupId>
  <artifactId>matsim-schemas-java</artifactId>
  <version>...</version>
</dependency>

Consumers should pin released versions instead of depending on main.

Rust Consumers

Once published, Rust consumers should depend on the matsim-schemas crate. This crate generates plain protobuf message types with prost. It does not use tonic-build, and it does not generate gRPC service clients or servers.

For downstream protobuf or gRPC generation, add matsim-schemas as a build dependency with the build feature and map the MATSim protobuf package to the Rust types exported by matsim-schemas:

[dependencies]
matsim-schemas = "..."

[build-dependencies]
matsim-schemas = { version = "...", features = ["build"] }
prost-build = "..."
tonic-prost-build = "..."