Traffic Situation Schema

A Traffic Situation defines a maritime scenario in JSON form. It typically consists of a single own ship and one or more target ships. The own ship must take appropriate actions to avoid collisions with target ships - that is the job of the collision avoidance system.

Full Schema Reference

Browse the complete auto-generated schema documentation or download the raw JSON schema file.

Open in New Tab Download JSON Schema

Top-Level Properties

The root TrafficSituation object has the following properties.

Property Type Required Description
version string Required maritime-schema version number, e.g. "0.2.0"
title string Optional The title of the traffic situation
description string Optional A description of the traffic situation
startTime date-time Optional Start time in ISO 8601 format YYYY-MM-DDThh:mm:ssZ
ownShip OwnShip Required Own Ship (OS) data — see Ship Object
targetShips TargetShip[] Optional Array of target ship objects
environment Environment Optional Environmental parameters (wind, current, waves, visibility)

Ship Object Structure

Own Ship data is stored under the ownShip key, while target ship data is stored under the targetShips array. Both share the same structure.

Property Type Required Description
waypoints Waypoint[] Required Array of waypoint objects (min 1). Defines the ship's route.
static ShipStatic Required Static ship information that does not change during a scenario (e.g. dimensions, ship type).
initial ShipState Optional Initial pose at scenario start. If omitted, initialised from the first waypoint.

Ship Static Properties

Static data that remains fixed throughout the scenario.

Property Type Required Description
id integer Required Ship identifier
mmsi integer Optional Maritime Mobile Service Identity (9 digits)
imo integer Optional IMO number (7 digits)
name string Optional Ship name
dimensions Dimensions Optional Key ship dimensions — see Dimensions
shipType string | int Optional AIS ship type (string enum or integer code)
stationType string | int Optional AIS station type
positionFixingDevice string | int Optional AIS position fixing device
pathType string Optional Control-point model: rtz (default), bezier, or linear
initDelay number Optional Delay in seconds before the ship is initialised (≥ 0)
sogMin number Optional Minimum speed over ground in knots (≥ 0)
sogMax number Optional Maximum speed over ground in knots (≥ 0)

Ship Initial State

Describes the ship's pose at the start of the scenario. The initial position, speed, and course can be omitted if they are the same as the first waypoint to avoid redundancy.

Property Type Required Description
position GeoPosition Optional WGS-84 longitude and latitude
sog number Optional Speed over ground in knots (≥ 0)
cog number Optional Course over ground in degrees (0–360)
heading number Optional Ship heading in degrees (0–360)
navStatus string | int Optional AIS Navigational Status

Waypoint Properties

Each waypoint defines a geographic control point along the ship's route. See the Trajectory page for more detail on how waypoints are interpreted.

Property Type Required Description
position GeoPosition Required A WGS-84 geographical coordinate (lon, lat)
turnRadius number Optional Orthodrome turn radius in nautical miles (as defined in RTZ). Defaults to 0.
leg Leg Optional Leg properties for the segment arriving at this waypoint — see Leg

Leg Properties

Leg data is placed on the destination waypoint of each segment. For example, the first leg (WP0→WP1) is defined in WP1.

Property Type Required Description
starboardXtd number Optional Starboard cross-track distance in nautical miles (RTZ)
portsideXtd number Optional Portside cross-track distance in nautical miles (RTZ)
sog number Optional Planned speed over ground in knots for this leg
data RouteData Optional Named data channels (e.g. sog, heading) with interpolation support

Ship Dimensions

All dimension values are in metres. Distances a, b, c, d are measured from the CCRP (Consistent Common Reference Point).

Property Type Description
length number Overall length (should equal a + b if both provided)
width number Overall width (should equal c + d if both provided)
height number Height of the ship
draught number Draught of the ship
a number CCRP to Bow
b number CCRP to Stern
c number CCRP to Port
d number CCRP to Starboard

Example

{
  "version": "0.2.0",
  "title": "Example Traffic Situation",
  "description": "An example traffic situation",
  "startTime": "2025-06-15T08:30:00Z",
  "ownShip": {
    "waypoints": [
      {
        "position": {
          "lon": 10.59,
          "lat": 58.61
        }
      },
      {
        "position": {
          "lon": 10.52,
          "lat": 58.52
        },
        "turnRadius": 0.3,
        "leg": {
Download JSON

Frequently Asked Questions (FAQ)