openapi.yaml

openapi: 3.0.1
info:
  title: OSRD Core
  description: OSRD backend api description
  termsOfService: http://swagger.io/terms/
  license:
    name: GNU GPLv3
    url: https://www.gnu.org/licenses/gpl-3.0.fr.html
  version: 0.1.0
servers:
  - url: http://gateway.dev.dgexsol.fr/osrd/
    description: Dev server
  - url: http://gateway.staging.dgexsol.fr/osrd/
    description: Staging server
tags:
  - name: health
    description: Check server health
  - name: pathfinding
    description: Execute pathfinding on the infrastructure
  - name: simulation
    description: Simulate a schedule on the infrastructure
paths:
  /health:
    get:
      tags:
        - health
      summary: Check server health
      operationId: health
      responses:
        200:
          description: The server is responding
  /version:
    get:
      responses:
        200:
          description: Return the service version
          content:
            application/json:
              schema:
                type: object
                properties:
                  git_describe:
                    type: string
                    nullable: true
                required:
                  - git_describe
  /infra_load:
    post:
      tags:
        - infra
      summary: load the infrastructure from editoast
      requestBody:
        description: Infrastructure id and its expected version
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InfraLoadRequest"
        required: true
      responses:
        204:
          description: No content
        400:
          description: The request body is invalid
  /pathfinding/routes:
    post:
      tags:
        - pathfinding
      summary: Find a path in the route graph that passes through waypoints.
      operationId: pathfinding_routes
      requestBody:
        description: Infrastructure id and waypoints
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PathfindingRequest"
        required: true
      responses:
        200:
          description: Path found
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/PathfindingRoutesResult"
        400:
          description: The request body is invalid
  /pathfinding/tracks:
    post:
      tags:
        - pathfinding
      summary: Find a path in the track section graph that passes through waypoints.
      operationId: pathfinding_tracks
      requestBody:
        description: Infrastructure id and waypoints
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PathfindingRequest"
        required: true
      responses:
        200:
          description: Path found
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/PathfindingTracksResult"
        400:
          description: The request body is invalid

  /stdcm:
    post:
      tags:
        - stdcm
      summary: Find a stdcm and return a simulation result
      requestBody:
        description: Infrastructure, waypoints and route occupancies
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/STDCMRequest"
      responses:
        200:
          description: Simulation result
          content:
            application/json:
              schema:
                oneOf:
                  - properties:
                      simulation:
                        $ref: "#/components/schemas/SimulationResult"
                      path:
                        $ref: "#/components/schemas/PathfindingRoutesResult"
                      departure_time:
                        type: number
                        format: double
                  - type: object
                    properties:
                      error:
                        type: string
                        description: Error message
                        example: No path could be found
        400:
          description: The request body is invalid

  /simulation:
    post:
      tags:
        - simulation
      summary: Simulate a scenario.
      operationId: simulation
      requestBody:
        description: Infra id, train rolling stocks and schedules.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SimulationRequest"
        required: true
      responses:
        200:
          description: List of infrastructure changes and train movements.
          content:
            application/json:
              schema:
                properties:
                  base_simulations:
                    type: array
                    items:
                      $ref: "#/components/schemas/SimulationTrainResult"
                  eco_simulations:
                    type: array
                    items:
                      $ref: "#/components/schemas/SimulationTrainResult"
                  speed_limits:
                    type: array
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          position:
                            type: number
                            format: double
                          speed:
                            type: number
                            format: double
                  electrification_ranges:
                    type: array
                    items:
                      $ref: "#/components/schemas/ElectrificationRange"
                    minItems: 1

                  neutral_sections_on_path:
                    type: array
                    items:
                      type: object
                      properties:
                        start:
                          type: number
                          format: double
                        stop:
                          type: number
                          format: double
                        lower_pantograph:
                          type: boolean
                  warnings:
                    type: array
        400:
          description: The request body is invalid

  /project_signals:
    post:
      tags:
        - simulation
      summary: Compute signal updates
      operationId: project_signals
      requestBody:
        description: Infra id, signal sightings and zone updates
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignalProjectionRequest"
        required: true
      responses:
        200:
          description: Signal updates
          content:
            application/json:
              schema:
                properties:
                  signal_updates:
                    type: array
                    items:
                      type: object
                      properties:
                        signal_id:
                          type: string
                        route_ids:
                          type: array
                          items:
                            type: string
                        time_start:
                          type: number
                          format: double
                        time_end:
                          type: number
                          format: double
                        color:
                          type: integer
                        blinking:
                          type: boolean
                        aspect_label:
                          type: string
                  warnings:
                    type: array
        400:
          description: The request body is invalid
components:
  schemas:
    InfraLoadRequest:
      required:
        - infra
        - expected_version
      properties:
        infra:
          type: string
        expected_version:
          type: string
    Waypoint:
      required:
        - track_section
        - direction
        - offset
      properties:
        track_section:
          type: string
        direction:
          type: string
          enum:
            - START_TO_STOP
            - STOP_TO_START
        offset:
          type: number
          format: double
          minimum: 0
    PathfindingRoutesResult:
      required:
        - track_sections
        - routes
      properties:
        routes:
          type: array
          minItems: 2
          items:
            type: string
        track_sections:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/TrackSectionRange"
      example:
        routes: ["route_foo", "route_bar"]
        track_sections:
          - track_section: "track_foo"
            begin_position: 4.2
            end_position: 178.3
    PathfindingTracksResult:
      required:
        - track_sections
      properties:
        track_sections:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/TrackSectionRange"
      example:
        track_sections:
          - track_section: "track_foo"
            begin_position: 4.2
            end_position: 178.3
    TrackLocation:
      required:
        - track_section
        - offset
      properties:
        track_section:
          type: string
        offset:
          type: number
          format: double
          minimum: 0
    TrackSectionRange:
      required:
        - track_section
        - begin_position
        - end_position
      properties:
        track_section:
          type: string
        begin_position:
          type: number
          format: double
          minimum: 0
        end_position:
          type: number
          format: double
          minimum: 0
    RollingStock:
      required:
        - name
        - length
        - mass
        - inertia_coefficient
        - rolling_resistance
        - max_speed
        - startup_time
        - startup_acceleration
        - comfort_acceleration
        - gamma
        - loading_gauge
        - effort_curves
        - power_class
      properties:
        name:
          type: string
        length:
          type: number
          format: double
          minimum: 0
          example: 400
        mass:
          type: number
          format: double
          minimum: 0
          example: 900000
        inertia_coefficient:
          type: number
          format: double
          minimum: 0
          example: 1.05
        max_speed:
          type: number
          format: double
          minimum: 0
          example: 80
        startup_time:
          type: number
          format: double
        startup_acceleration:
          type: number
          format: double
          example: 0.05
        comfort_acceleration:
          type: number
          format: double
          example: 0.25
        gamma:
          type: number
          format: double
          example: 0.5
        loading_gauge:
          type: string
          enum:
            - G1
            - G2
            - GA
            - GB
            - GB1
            - GC
            - FR3_3
            - FR3_3_GB_G2
        features:
          type: array
          items:
            type: string
            example: "protecting systems"
        power_class:
          type: string
          example: "5"
        effort_curves:
          $ref: "#/components/schemas/EffortCurves"
    EffortCurves:
      required:
        - speeds
        - max_efforts
      properties:
        speeds:
          type: array
          items:
            type: number
            format: double
        max_efforts:
          type: array
          items:
            type: number
            format: double
    TrainSchedule:
      required:
        - id
        - rolling_stock
        - initial_speed
        - allowances
        - stops
        - tag
        - comfort
      properties:
        id:
          type: string
          example: "TrainID"
        rolling_stock:
          type: string
          example: "RollingStockID"
        initial_speed:
          description: Speed in m/s
          type: number
          format: double
        allowances:
          type: array
          items:
            $ref: "#/components/schemas/Allowance"
        scheduled_points:
          type: array
          items:
            type: object
            required:
              - position
              - time
            properties:
              path_offset:
                type: number
                format: double
                description: Position in meters from the start of the path at which the train must be.
              time:
                type: number
                format: double
                description: Time in seconds (elapsed since the train's departure) at which the train must be.
        stops:
          type: array
          items:
            type: object
            properties:
              position:
                type: number
                format: double
              location:
                $ref: "#/components/schemas/TrackLocation"
              duration:
                type: number
                format: double
        tag:
          type: string
          example: "V200"
          description: "The category this train belongs to. Used when applying speed limits by category."
        comfort:
          type: string
          enum:
            - STANDARD
            - AC
            - HEATING
        power_restriction_ranges:
          type: array
          items:
            $ref: "#/components/schemas/PowerRestrictionRange"
          default: []
        options:
          type: object
          nullable: true
          properties:
            ignore_electrical_profiles:
              type: boolean
              default: false
    PowerRestrictionRange:
      description: A range along the train path where a power restriction is applied.
      type: object
      properties:
        begin_position:
          description: Offset from the start of the path, in meters.
          type: number
          format: float
        end_position:
          description: Offset from the start of the path, in meters.
          type: number
          format: float
        power_restriction_code:
          description: The power restriction code to apply.
          type: string
      example:
        begin_position: 0.0
        end_position: 1000.0
        power_restriction_code: "C1US"
    Routes:
      properties:
        entry_point:
          $ref: "#/components/schemas/Waypoint"
        exit_point:
          $ref: "#/components/schemas/Waypoint"
        entry_point_direction:
          type: string
          enum:
            - 0
            - 1
        release_detectors:
          type: array
          items:
            type: string
    SimulationTrainResult:
      properties:
        speeds:
          type: array
          items:
            type: object
            properties:
              time:
                type: number
                format: double
              position:
                type: number
                format: double
              speed:
                type: number
                format: double
            example:
              time: 0
              position: 0
              speed: 0
        head_positions:
          type: array
          items:
            type: object
            properties:
              time:
                type: number
                format: double
              path_offset:
                type: number
                format: double
              track_section:
                type: string
              offset:
                type: number
                format: double
            example:
              time: 0
              path_offset: 0
              track_section: "track_section_id"
              offset: 0
        stops:
          type: array
          items:
            type: object
            properties:
              time:
                type: number
                format: double
              position:
                type: number
                format: double
              duration:
                type: number
                format: double
            example:
              time: 0
              position: 0
              duration: 0
        route_occupancies:
          type: object
          additionalProperties:
            type: object
            properties:
              time_head_occupy:
                type: number
                format: double
              time_head_free:
                type: number
                format: double
              time_tail_occupy:
                type: number
                format: double
              time_tail_free:
                type: number
                format: double
        signal_sightings:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/SignalSighting"
        zone_updates:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/ZoneUpdate"
        spacing_requirements:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/SpacingRequirement"
        tag:
          type: string
          example: "tag"
    SimulationResult:
      oneOf:
        - $ref: "#/components/schemas/SimulationResultRouteStatus"
        - $ref: "#/components/schemas/SimulationResultTrainLocation"
        - $ref: "#/components/schemas/SimulationResultSignalChange"
      discriminator:
        propertyName: type
        mapping:
          route_status: "#/components/schemas/SimulationResultRouteStatus"
          train_location: "#/components/schemas/SimulationResultTrainLocation"
          signal_change: "#/components/schemas/SimulationResultSignalChange"
    SimulationResultRouteStatus:
      required:
        - type
        - time
        - id
        - status
      properties:
        type:
          type: string
          example: "route_status"
        time:
          type: number
          format: double
        id:
          type: string
          example: "routeID"
        status:
          type: string
          enum:
            - FREE
            - RESERVED
            - OCCUPIED
            - CONFLICT
            - REQUESTED
    SimulationResultTrainLocation:
      required:
        - type
        - time
        - train_name
        - track_section
        - offset
      properties:
        type:
          type: string
          example: "train_location"
        time:
          type: number
          format: double
        train_name:
          type: string
          example: "trainID"
        track_section:
          type: string
          example: "trackSectionID"
        offset:
          type: number
          format: double
          minimum: 0
          example: 42
    SimulationResultSignalChange:
      required:
        - type
        - time
        - signal
        - aspects
      properties:
        type:
          type: string
          example: "signal_change"
        time:
          type: number
          format: double
        signal:
          type: string
          example: "signalID"
        aspects:
          type: array
          items:
            type: string
            example: "AspectID"
    PathfindingRequest:
      required:
        - infra
        - waypoints
        - rolling_stocks
      properties:
        infra:
          type: string
          example: "infraID"
        waypoints:
          type: array
          minItems: 2
          items:
            type: array
            minItems: 1
            items:
              $ref: "#/components/schemas/Waypoint"
          example:
            - - track_section: "track_departure"
                direction: "START_TO_STOP"
                offset: 4.2
              - track_section: "track_departure_bis"
                direction: "START_TO_STOP"
                offset: 14.2
            - - track_section: "track_destination"
                direction: "STOP_TO_START"
                offset: 138.32
        rolling_stocks:
          $ref: "#/components/schemas/RollingStock"
    STDCMRequest:
      properties:
        infra:
          type: string
          example: "infraID"
        rolling_stocks:
          $ref: "#/components/schemas/RollingStock"
        spacing_requirements:
          type: array
          items:
            $ref: "#/components/schemas/SpacingRequirement"
        start_time:
          type: number
          format: double
        end_time:
          type: number
          format: double
        steps:
          type: array
          minimum: 2
          items:
            type: object
            properties:
              waypoints:
                type: array
                items:
                  $ref: "#/components/schemas/Waypoint"
                minimum: 1
              stop:
                type: boolean
              stop_duration:
                type: number
                format: double
        speed_limit_tags:
          type: string
          description: Train composition used for speed limit
        margin_before:
          type: number
          format: double
          description: |
            Margin of x seconds before the train passage, which means that the path used by the train should
            be free and available at least x seconds before its passage.
        margin_after:
          type: number
          format: double
          description: |
            Margin of y seconds after the train passage, which means that the path used by the train should
            be free and available at least y seconds after its passage.
    SimulationRequest:
      required:
        - infra
        - time_step
        - rolling_stocks
        - train_schedules
        - trains_path
      properties:
        infra:
          type: string
          example: "infraID"
        time_step:
          type: number
          format: double
        rolling_stocks:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/RollingStock"
        train_schedules:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/TrainSchedule"
        electrical_profile_set:
          type: string
          example: "ID"
        trains_path:
          properties:
            track:
              type: string
              example: "track"
            begin:
              type: number
              format: double
              description: begin offset of the track range
            end:
              type: number
              format: double
              description: end offset of the track range
    SignalProjectionRequest:
      required:
        - infra
        - train_path
        - signal_sightings
        - zone_updates
      properties:
        infra:
          type: string
          example: "infraID"
        signal_sightings:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/SignalSighting"
        train_schedules:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/ZoneUpdate"
        trains_path:
          properties:
            track:
              type: string
              example: "track"
            begin:
              type: number
              format: double
              description: begin offset of the track range
            end:
              type: number
              format: double
              description: end offset of the track range
    Allowance:
      oneOf:
        - $ref: "#/components/schemas/StandardAllowance"
        - $ref: "#/components/schemas/EngineeringAllowance"
      discriminator:
        propertyName: allowance_type
        mapping:
          standard: "#/components/schemas/StandardAllowance"
          engineering: "#/components/schemas/EngineeringAllowance"
    BaseAllowance:
      properties:
        value_type:
          type: string
        distribution:
          type: string
          enum: ["MARECO", "LINEAR"]
        capacity_speed_limit:
          type: number
          format: double
          default: -1
    StandardAllowance:
      description: An allowance which will affect the whole path. It represents the additional time given to a train to fulfill its schedule. Only one can be applied by TrainSchedule.
      allOf:
        - $ref: "#/components/schemas/BaseAllowance"
        - type: object
          properties:
            ranges:
              description: A list of ranges where different values are applied. Ranges cannot overlap.
              type: array
              items:
                type: object
                properties:
                  begin_position:
                    type: number
                    format: double
                    description: begin offset on the path
                  end_position:
                    type: number
                    format: double
                    description: end offset on the path
                  value:
                    $ref: "#/components/schemas/AllowanceValue"
            value:
              $ref: "#/components/schemas/AllowanceValue"
    EngineeringAllowance:
      description: An allowance which represents portions of the path where the train has to slow down in order to avoid conflicts. Several can be applied by TrainSchedule, and they can overlap other allowances.
      allOf:
        - $ref: "#/components/schemas/BaseAllowance"
        - type: object
          properties:
            begin_position:
              type: number
              format: double
              description: begin offset on the path
            end_position:
              type: number
              format: double
              description: end offset on the path
            value:
              $ref: "#/components/schemas/AllowanceValue"
    AllowanceValue:
      oneOf:
        - $ref: "#/components/schemas/TimePerDistanceAllowanceValue"
        - $ref: "#/components/schemas/TimeAllowanceValue"
        - $ref: "#/components/schemas/PercentageAllowanceValue"
      discriminator:
        propertyName: value_type
    TimePerDistanceAllowanceValue:
      properties:
        value_type:
          type: string
          enum: ["time_per_distance"]
        minutes:
          type: number
          format: double
          description: time to add per 100km in minutes
    TimeAllowanceValue:
      properties:
        value_type:
          type: string
          enum: ["time"]
        seconds:
          type: number
          format: double
          description: time to add over the whole range in seconds
    PercentageAllowanceValue:
      properties:
        value_type:
          type: string
          enum: ["percentage"]
        percentage:
          type: number
          format: double
          description: in %, how much time do we add compared to the fastest run time
    ZoneUpdate:
      properties:
        zone:
          type: string
        time:
          type: number
          format: double
        offset:
          type: number
          format: double
          description: the offset of the zone on the current path
        is_entry:
          type: boolean
    SpacingRequirement:
      properties:
        zone:
          type: string
        begin_time:
          type: number
          format: double
        end_time:
          type: number
          format: double
    SignalSighting:
      properties:
        signal:
          type: string
        time:
          type: number
          format: double
        offset:
          type: number
          format: double
          description: The offset of the sighting on the current path
        state:
          type: string
          description: The expected state of the signal, if the train is alone in the infra
    ElectrificationRange:
      properties:
        start:
          type: number
          format: double
        stop:
          type: number
          format: double
        electrification:
          oneOf:
            - $ref: "#/components/schemas/Electrified"
            - $ref: "#/components/schemas/Neutral"
            - $ref: "#/components/schemas/NonElectrified"
          discriminator:
            propertyName: object_type
      required: [start, stop, is_electrified, electrification]
    Electrified:
      properties:
        mode:
          type: string
        mode_handled:
          type: boolean
        profile:
          type: string
          nullable: true
        profile_handled:
          type: boolean
      required: [mode, mode_handled, profile_handled]
    Neutral:
      properties:
        lower_pantograph:
          type: boolean
      required: [lower_pantograph]
    NonElectrified:
      type: object