[FEATURE] Add travel_time property to water segments

[Alex Iannicelli (atiannicelli)]

Description

Adds an optional travel_time property to subtype=water transportation segments. The property is a positive integer number of seconds capturing the scheduled end-to-end crossing time for the full segment — including time spent docking, loading, and unloading — matching the semantics of the OSM duration tag on ferry routes it is sourced from.

Without it, routers consuming Overture fall back to a default ferry speed (~5 km/h), so car ferries are either avoided or produce wildly inflated ETAs.

Design choices follow the suggestions in the issue (open for working group review on this draft):

• Type/units: integer seconds (minimum: 1) — simplest for consumers.
• Scoping: flat value, no rules container — a single scheduled duration suffices for ferry crossings; linear referencing seems unnecessary.
• Applicability: water-only for now, defined inline on the water branch rather than as a reusable container in defs.yaml.

Changes

• packages/overture-schema-theme-transportation/.../segment/water.py: new TravelTime type (int32, ge=1) and optional travel_time field on WaterSegment.
• schema/transportation/segment.yaml: new travelTime property definition and reference from the water oneOf branch (replacing the placeholder).
• Regenerated segment_baseline_schema.json via make update-baselines.
• New example water-ferry.yaml and counterexamples (bad-travel-time-zero, bad-travel-time-type, bad-travel-time-wrong-subtype) in both examples/+counterexamples/ and reference/examples/+reference/counterexamples/.
• Changelog fragment changelog.d/711.feature.md (transportation theme package).
• Docs note in docs/schema/reference/transportation/segment.mdx water subtype tab.

Reference

1. Closes [FEATURE] Add travel_time property to water segments #711
2. Parent issue: OvertureMaps/tf-data-platform#5067

Testing

• YAML JSON Schema: validated all examples/transportation (pass, including new water-ferry.yaml) and counterexamples/transportation (all fail as expected, including the three new water counterexamples) against schema/schema.yaml with a draft 2020-12 validator.
• Pydantic: pytest packages/overture-schema-theme-transportation packages/overture-schema-validation — 474 passed (includes the JSON Schema baseline test and the reference examples/counterexamples).
• Full suite: pytest -W error packages/ tests/ — 3550 passed; PySpark suite (regenerated expressions including the new field) — 3151 passed under JDK 17.
• Gates: lint-only, mypy-only, docformat-only, doctest-only, check-namespace all pass.

Checklist

1. Add relevant examples.
2. Add relevant counterexamples.
3. Update any counterexamples that became obsolete. (None became obsolete — the water branch was previously a placeholder.)
4. Update in-schema documentation using plain English written in complete sentences.
5. Update Docusaurus documentation.
6. Review change with Overture technical writer to ensure any advanced documentation needs will be taken care of.

Documentation website

Docs preview for this PR.

[github-actions]

🗺️ Schema reference docs preview is live!

🌍 Preview	https://staging.overturemaps.org/schema/pr/712/schema/index.html
🕐 Updated	Sep 02, 2026 18:13 UTC
📝 Commit	de839bd
🔧 env SCHEMA_PREVIEW	true

Note

♻️ This preview updates automatically with each push to this PR.

[Copilot]

🟢 Approval recommended

The schemas, documentation, generated baseline, and positive and negative examples consistently implement the requested behavior.

Pull request overview

Adds optional ferry crossing duration metadata to water segments so routers can calculate realistic ETAs.

Changes:

• Adds positive integer travel_time validation to both schemas.
• Documents the property and supplies examples/counterexamples.
• Regenerates the schema baseline and adds a changelog entry.

File summaries

File	Description
schema/transportation/segment.yaml	Defines water-only travel_time.
packages/.../segment/water.py	Adds the Pydantic field and type.
packages/.../segment_baseline_schema.json	Updates the generated schema baseline.
docs/schema/reference/transportation/segment.mdx	Documents water travel time.
packages/.../changelog.d/711.feature.md	Records the feature.
examples/.../water-ferry.yaml	Adds a valid schema example.
reference/examples/.../water-ferry.yaml	Adds a valid Pydantic example.
counterexamples/.../bad-travel-time-zero.yaml	Tests the positive-value constraint.
counterexamples/.../bad-travel-time-type.yaml	Tests integer typing.
counterexamples/.../bad-travel-time-wrong-subtype.yaml	Tests water-only applicability.
reference/counterexamples/.../bad-travel-time-zero.yaml	Tests Pydantic positivity validation.
reference/counterexamples/.../bad-travel-time-type.yaml	Tests Pydantic integer validation.
reference/counterexamples/.../bad-travel-time-wrong-subtype.yaml	Tests Pydantic subtype validation.

Review details

• Files reviewed: 13/13 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Eric Godwin (ericgodwin)]

I believe this should be an extension instead of part of the base schema. My thinking is that we really only have one source for this data that I am aware of, OSM. I would like to see us examine multiple sources and ensure that our schema selection aligns before bringing this in.