openapi_legacy.yaml

openapi: 3.0.2
info:
  title: OSRD Editoast
  description: OSRD Edition service description
  version: 0.1.0

tags:
  - name: infra
    description: Infra
  - name: routes
    description: Operations related to infra routes
  - name: timetable
    description: Timetable
  - name: pathfinding
    description: Pathfinding operations
  - name: layers
    description: Map layers
  - name: electrical_profiles
    description: Electrical profiles
  - name: train_schedule
    description: Train Schedule

paths:
  /infra/:
    get:
      tags:
        - infra
      summary: Paginated list of all available infras
      parameters:
        - description: Page number
          in: query
          name: page
          schema:
            default: 1
            minimum: 1
            type: integer
        - description: Number of elements by page
          in: query
          name: page_size
          schema:
            default: 25
            maximum: 10000
            minimum: 1
            type: integer
      responses:
        200:
          description: The infras list
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                  next: {}
                  previous: {}
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Infra"
                required: [count, next, previous]
    post:
      tags:
        - infra
      summary: Create an infra
      requestBody:
        description: Name of the infra to create
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        201:
          description: The created infra
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Infra"

  /infra/{id}/:
    get:
      tags:
        - infra
      summary: Retrieve a specific infra
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
      responses:
        200:
          description: Information about the retrieved infra
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Infra"
    delete:
      tags:
        - infra
      summary: Delete an infra and all entities linked to it
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
      responses:
        204:
          description: No content

    post:
      tags:
        - infra
      summary: Update/Create/Delete an object of the infra
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
      requestBody:
        description: Operations to do on the infra
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/Operation"
      responses:
        200:
          description: An array containing infos about the operations processed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/OperationResult"

    put:
      tags:
        - infra
      summary: Update an infrastructure name
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
      requestBody:
        description: the name we want to give to the infra
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        200:
          description: The updated infra
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Infra"

  /infra/{id}/load/:
    post:
      tags:
        - infra
      summary: Load an infra if not loaded
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
      responses:
        200:
          description: No content

  /infra/{id}/railjson/:
    get:
      tags:
        - infra
      summary: Serialize an infra to railjson
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Infra ID
          required: true
      responses:
        200:
          description: The infra in railjson format
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RailjsonFile"

  /infra/railjson/:
    post:
      tags:
        - infra
      summary: Import an infra from railjson
      parameters:
        - in: query
          name: name
          schema:
            type: string
          description: Infra name
          required: true
        - in: query
          name: generate_data
          schema:
            type: boolean
            description: whether the layer should be generated or no
            default: false
      requestBody:
        description: Railjson infra
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RailjsonFile"
        required: true
      responses:
        201:
          description: The imported infra id
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string

  /infra/{id}/errors/:
    get:
      tags:
        - infra
      summary: Retrieve a paginated list of errors
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: The page number
        - in: query
          name: page_size
          schema:
            type: integer
            default: 25
            minimum: 10
          description: The number of item per page
        - in: query
          name: error_type
          schema:
            $ref: "#/components/schemas/InfraErrorType"
          description: The type of error to filter on
        - in: query
          name: object_id
          schema:
            type: string
          description: errors and warnings that only part of a given object
        - in: query
          name: level
          schema:
            type: string
            enum: [errors, warnings, all]
            default: all
          description: Whether the response should include errors or warnings
      responses:
        200:
          description: A paginated list of errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of elements
                    example: 1
                  next:
                    type: integer
                    nullable: true
                    example: null
                    description: The index of the following page (null if no more pages available)
                  previous:
                    type: integer
                    nullable: true
                    example: null
                    description: The index of the previous page (null if requesting the first page)
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/InfraError"

  /infra/{id}/switch_types/:
    get:
      tags:
        - infra
      summary: Retrieve a list of switch types
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
      responses:
        200:
          description: A list of switch types
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: A switch type following Railjson spec
                  example:
                    id: Point
                    ports: [LEFT, RIGHT, BASE]
                    groups:
                      LEFT: { src: BASE, dst: LEFT }
                      RIGHT: { src: BASE, dst: RIGHT }

  /infra/refresh/:
    post:
      tags:
        - infra
      summary: Refresh the layers
      parameters:
        - in: query
          name: infras
          schema:
            type: array
            items:
              type: integer
            default: []
          description: A list of infra ID
        - in: query
          name: force
          schema:
            type: boolean
            default: false
          description: Force the refresh of the layers
      responses:
        200:
          description: A list thats contains the ID of the infras that were refreshed*
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer

  /infra/voltages/:
    get:
      tags:
        - infra
        - rolling_stock
      summary: List all voltages of all infras
      responses:
        200:
          description: Voltages list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: ["750", "1500", "2500.5"]

  /infra/{id}/lines/{line_code}/bbox/:
    get:
      tags:
        - infra
      summary: Returns the BBoxes (geo and schematic) of a line
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
        - in: path
          name: line_code
          schema:
            type: integer
          description: a line code
          required: true
      responses:
        200:
          description: The BBox of the line
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Zone"

  /infra/{id}/lock/:
    post:
      tags:
        - infra
      summary: Lock an infra from edition
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
      responses:
        204:
          description: No content

  /infra/{id}/unlock/:
    post:
      tags:
        - infra
      summary: Unlock an infra from edition
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
      responses:
        204:
          description: No content

  /infra/{id}/speed_limit_tags/:
    get:
      tags:
        - infra
      summary: List all speed limit tags
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Infra id
          required: true
      responses:
        200:
          description: Tags list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: ["freight", "heavy_load"]

  /infra/{id}/voltages/:
    get:
      tags:
        - infra
      summary: List all voltages
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Infra ID
          required: true
        - in: query
          name: include_rolling_stock_modes
          schema:
            type: boolean
          description: include rolling stocks modes or not
          required: false
      responses:
        200:
          description: Voltages list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: ["750", "1500", "2500.5"]

  /infra/{id}/attached/{track_id}/:
    get:
      summary: Retrieve all objects attached to a given track
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Infra ID
          required: true
        - in: path
          name: track_id
          schema:
            type: string
          description: Track ID
          required: true
      responses:
        200:
          description: All objects attached to the given track (arranged by types)
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
                    description: Object IDs
                example:
                  Switch: ["switch.0", "switch.1"]
                  Detector: ["detector.0"]
                  BufferStop: []

  /infra/{id}/routes/{waypoint_type}/{waypoint_id}/:
    get:
      tags:
        - infra
        - routes
      summary: Retrieve all routes that starting and ending by the given waypoint (detector or buffer stop)
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Infra ID
          required: true
        - in: path
          name: waypoint_type
          schema:
            type: string
            enum: [Detector, BufferStop]
          description: Type of the waypoint
          required: true
        - in: path
          name: waypoint_id
          schema:
            type: string
          description: The waypoint id
          required: true
      responses:
        200:
          description: All routes that starting and ending by the given waypoint
          content:
            application/json:
              schema:
                type: object
                properties:
                  starting:
                    type: array
                    items:
                      type: string
                    example: ["route1", "route2"]
                  ending:
                    type: array
                    items:
                      type: string
                    example: ["route3", "route4"]
                required: [starting, ending]

  /infra/{id}/routes/track_ranges/:
    get:
      tags:
        - infra
        - routes
      summary: Compute the track ranges through which routes passes.
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Infra ID
          required: true
        - in: query
          name: routes
          schema:
            type: array
            items:
              type: string
            description: A list of routes seperated by comma
            example: "route1,route2,route3"
          required: true
      responses:
        200:
          description: Foreach route, the track ranges through which it passes or an error
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - $ref: "#/components/schemas/RouteTrackRangesNotFoundError"
                    - $ref: "#/components/schemas/RouteTrackRangesCantComputePathError"
                    - $ref: "#/components/schemas/RouteTrackRangesComputed"

  /infra/{id}/pathfinding/:
    post:
      tags:
        - infra
        - pathfinding
      summary: Compute paths given starting and ending track location. Return shortest paths.
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Infra ID
          required: true
        - in: query
          name: number
          schema:
            type: number
            format: integer
            minimum: 1
            maximum: 5
            default: 5
          description: Maximum number of paths to return
      requestBody:
        description: Starting and ending track location
        content:
          application/json:
            schema:
              type: object
              properties:
                starting:
                  $ref: "#/components/schemas/TrackLocation"
                ending:
                  $ref: "#/components/schemas/TrackLocation"
      responses:
        200:
          description: Paths, containing track ranges, detectors and switches with their directions. If no path is found, an empty list is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    track_ranges:
                      type: array
                      minItems: 1
                      items:
                        $ref: "#/components/schemas/DirectionalTrackRange"
                    detectors:
                      type: array
                      items:
                        type: string
                        example: "detector1"
                    switches_directions:
                      type: object
                      example: { "switch1": "left", "switch2": "right" }
                      additionalProperties:
                        type: string
                  required: [track_ranges, detectors, switches_directions]

  /infra/{id}/objects/{object_type}/:
    post:
      tags:
        - infra
      summary: "Retrieve a list of specific objects in railjson format"
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Infra id
          required: true
        - in: path
          name: object_type
          schema:
            $ref: "#/components/schemas/ObjectType"
          description: The type of the object
          required: true
      requestBody:
        description: List of object id's
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        200:
          description: No content
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - railjson
                    - geographic
                    - schematic
                  properties:
                    railjson:
                      description: Object properties in railjson format
                      $ref: "#/components/schemas/Railjson"
                    geographic:
                      description: object's geographic in geojson format
                      $ref: "#/components/schemas/Geometry"
                    schematic:
                      description: object's schematic in geojson format
                      $ref: "#/components/schemas/Geometry"

  /infra/{id}/clone/:
    post:
      tags:
        - infra
      summary: Duplicate an infra
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Infra id
          required: true
        - in: query
          name: name
          schema:
            type: string
          description: New infra name
          required: true
      responses:
        201:
          description: The duplicated infra id
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: integer }

  /pathfinding/:
    post:
      summary: Create a Path
      requestBody:
        description: Path information
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PathQuery"
      responses:
        201:
          description: The created Path
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Path"

  /pathfinding/{id}/:
    get:
      tags:
        - pathfinding
      summary: Retrieve a Path
      parameters:
        - in: path
          name: id
          schema: { type: integer }
          description: Path ID
          required: true
      responses:
        200:
          description: The retrieved path
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Path"
    put:
      tags:
        - pathfinding
      summary: Update a path
      parameters:
        - in: path
          name: id
          schema: { type: integer }
          description: Path ID
          required: true
      requestBody:
        description: Updated Path
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PathQuery"
      responses:
        200:
          description: The updated path
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Path"
    delete:
      tags:
        - pathfinding
      summary: Delete a path
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Path ID
          required: true
      responses:
        204:
          description: No content

  /stdcm/:
    post:
      tags:
        - stdcm
      summary: Find a stdcm and return a simulation result
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                [
                  infra_id,
                  timetable_id,
                  steps,
                  rolling_stocks,
                  rolling_stock_id,
                  comfort,
                  maximum_departure_delay,
                ]
              properties:
                infra_id:
                  type: integer
                timetable_id:
                  type: integer
                  description: timetable ID
                start_time:
                  type: number
                  format: double
                end_time:
                  type: number
                  format: double
                steps:
                  type: array
                  minItems: 2
                  items:
                    type: object
                    properties:
                      duration:
                        type: number
                        format: float
                      waypoints:
                        $ref: "#/components/schemas/Waypoint"
                    required: [duration, waypoints]
                rolling_stocks:
                  type: array
                  items:
                    type: integer
                rolling_stock_id:
                  type: integer
                comfort:
                  $ref: "#/components/schemas/Comfort"
                maximum_departure_delay:
                  type: number
                  format: double
                  description: By how long we can shift the departure time (s). Defaults to 2h if unspecified.
                maximum_run_time:
                  type: number
                  format: double
                  description: |
                    Specifies how long the total run time can be in seconds.
                    Defaults to 43200s if unspecified, meaning that the result can't exceed 12h.
                speed_limit_tags:
                  type: string
                  description: Train category for speed limits
                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.
                  default: 0
                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.
                  default: 0
                standard_allowance:
                  $ref: "#/components/schemas/AllowanceValue"
      responses:
        200:
          description: Simulation result
          content:
            application/json:
              schema:
                oneOf:
                  - properties:
                      simulation:
                        $ref: "#/components/schemas/SimulationReport"
                      path:
                        $ref: "#/components/schemas/Path"
                    required: [simulation, path]
                  - type: object
                    properties:
                      error:
                        type: string
                        description: Error message
                        example: No path could be found
        400:
          description: The request body is invalid

  /single_simulation/:
    post:
      summary: Runs a simulation with a single train, does not write anything to the database
      requestBody:
        description: The details of the simulation
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SingleSimulationRequest"
        required: true
      responses:
        201:
          description: Data about the simulation produced
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SingleSimulationResponse"

components:
  schemas:
    BoundingBox:
      description: A bounding box
      type: array
      minItems: 2
      maxItems: 2
      items:
        type: array
        minItems: 2
        maxItems: 2
        items:
          type: integer

    Comfort:
      description: Train comfort that will be used for the simulation
      type: string
      enum: ["AC", "HEATING", "STANDARD"]
      default: "STANDARD"

    GeoJsonObject:
      type: object
      description: GeoJson format
      properties:
        coordinates:
          type: array
          items:
            type: array
            items: { type: number, format: float }
        type: { type: string }
      required: [coordinates, type]

    GeoJsonPosition:
      type: object
      properties:
        coordinates:
          type: array
          items: { type: number, format: float }
          minItems: 2
          maxItems: 2
        type: { type: string }
      required: [coordinates, type]

    Infra:
      properties:
        id:
          type: integer
        name:
          type: string
        version:
          type: string
          example: "1"
        railjson_version:
          type: string
          example: "3.3.1"
        generated_version:
          type: string
          nullable: true
          example: "1"
        created:
          type: string
          format: date
        modified:
          type: string
          format: date
        locked:
          type: boolean
        state:
          type: string
          enum:
            - NOT_LOADED
            - INITIALIZING
            - DOWNLOADING
            - PARSING_JSON
            - PARSING_INFRA
            - ADAPTING_KOTLIN
            - LOADING_SIGNALS
            - BUILDING_BLOCKS
            - CACHED
            - TRANSIENT_ERROR
            - ERROR
      required:
        [
          id,
          name,
          version,
          railjson_version,
          generated_version,
          created,
          modified,
          locked,
          state,
        ]

    Zone:
      type: object
      properties:
        geo:
          $ref: "#/components/schemas/BoundingBox"
        sch:
          $ref: "#/components/schemas/BoundingBox"

    ObjectType:
      type: string
      description: Type of the object
      enum:
        - TrackSection
        - Signal
        - SpeedSection
        - Detector
        - Switch
        - SwitchType
        - BufferStop
        - Route
        - OperationalPoint
        - Catenary

    RailjsonFile:
      properties:
        version:
          type: string
        operational_points:
          type: array
        routes:
          type: array
        switch_types:
          type: array
        switches:
          type: array
        track_sections:
          type: array
        signals:
          type: array
        buffer_stops:
          type: array
        speed_sections:
          type: array
        catenaries:
          type: array
        detectors:
          type: array

    OperationResult:
      oneOf:
        - $ref: "#/components/schemas/DeleteOperation"
        - $ref: "#/components/schemas/OperationObject"

    RailjsonObject:
      required:
        - operation_type
        - obj_type
        - railjson
      properties:
        operation_type:
          type: string
          enum:
            - CREATE
        obj_type:
          $ref: "#/components/schemas/ObjectType"
        railjson:
          $ref: "#/components/schemas/Railjson"

    DeleteOperation:
      required:
        - operation_type
        - obj_type
        - obj_id
      properties:
        operation_type:
          type: string
          enum:
            - DELETE
        obj_type:
          $ref: "#/components/schemas/ObjectType"
        obj_id:
          type: string
          example: bd840b06-84ba-4566-98c1-ccf0196c5f16

    UpdateOperation:
      required:
        - operation_type
        - obj_type
        - railjson_patch
      properties:
        operation_type:
          type: string
          enum:
            - UPDATE
        obj_type:
          $ref: "#/components/schemas/ObjectType"
        obj_id:
          type: string
          example: bd840b06-84ba-4566-98c1-ccf0196c5f16
        railjson_patch:
          $ref: "#/components/schemas/Patches"

    OperationObject:
      required:
        - operation_type
        - obj_type
        - railjson
      properties:
        operation_type:
          type: string
          enum:
            - CREATE
            - UPDATE
        obj_type:
          $ref: "#/components/schemas/ObjectType"
        railjson:
          $ref: "#/components/schemas/Railjson"

    Patch:
      description: A JSONPatch document as defined by RFC 6902
      required:
        - "op"
        - "path"
      properties:
        op:
          type: string
          description: The operation to be performed
          enum:
            - "add"
            - "remove"
            - "replace"
            - "move"
            - "copy"
            - "test"
        path:
          type: string
          description: A JSON-Pointer
        value:
          type: object
          description: The value to be used within the operations.
        from:
          type: string
          description: A string containing a JSON Pointer value.

    Patches:
      type: array
      description: A list of Patch
      items:
        $ref: "#/components/schemas/Patch"

    Railjson:
      type: object
      description: This field follows railjson format
      additionalProperties: true
      required:
        - id
      properties:
        id:
          type: string
      example:
        id: bd840b06-84ba-4566-98c1-ccf0196c5f16
        geo:
          type: LineString
          coordinates:
            - - 1.0
              - 41.0
            - - 2.0
              - 42.0
        sch:
          type: LineString
          coordinates:
            - - 1.0
              - 41.0
            - - 2.0
              - 42.0
        curves: []
        length: 1000
        slopes:
          - end: 500
            begin: 250
            gradient: -1
        line_code: 1
        line_name: my line
        track_name: track name
        navigability: BOTH
        track_number: 1

    InfraErrorType:
      type: string
      description: Type of the infra error
      enum:
        - duplicated_group
        - empty_object
        - invalid_group
        - invalid_reference
        - invalid_route
        - invalid_switch_ports
        - missing_route
        - missing_buffer_stop
        - object_out_of_path
        - odd_buffer_stop_location
        - out_of_range
        - overlapping_speed_sections
        - overlapping_switches
        - overlapping_catenaries
        - unknown_port_name
        - unused_port

    InfraError:
      type: object
      description: An infra error or warning
      required: [information]
      properties:
        geographic:
          nullable: true
          description: Geojson of the geographic geometry of the error
          $ref: "#/components/schemas/Geometry"
        schematic:
          nullable: true
          type: object
          description: Geojson of the schematic geometry of the error
        information:
          type: object
          description: Information about the error (check schema documentation for more details)
          required: [obj_id, obj_type, error_type, is_warning]
          properties:
            obj_id:
              type: string
            obj_type:
              type: string
              enum:
                - TrackSection
                - Signal
                - BufferStop
                - Detector
                - Switch
                - Route
            error_type:
              $ref: "#/components/schemas/InfraErrorType"
            field:
              type: string
            is_warning:
              type: boolean

    TrackSectionLocation:
      type: object
      description: A track location (track section and offset)
      properties:
        track_section:
          type: string
          description: The track section ID
          example: 61205924-6667-11e3-81ff-01f464e0362d
        offset:
          type: number
          format: float
          description: The offset on the track section
          example: 42.
      required: [track_section, offset]

    TrackLocation:
      type: object
      description: A track location (track section and offset)
      properties:
        track:
          type: string
          description: The track section ID
          example: 61205924-6667-11e3-81ff-01f464e0362d
        offset:
          type: number
          format: float
          description: The offset on the track section
          example: 42.

    Direction:
      type: string
      enum: [START_TO_STOP, STOP_TO_START]

    DirectionalTrackRange:
      type: object
      description: Track range associated with a direction
      required:
        - track
        - begin
        - end
        - direction
      properties:
        track:
          type: string
          example: 01234567-89ab-cdef-0123-456789abcdef
        begin:
          type: number
          format: float
        end:
          type: number
          format: float
          example: 100.
        direction:
          $ref: "#/components/schemas/Direction"

    Path:
      properties:
        id: { type: integer }
        owner:
          type: string
          format: uuid
        created:
          type: string
          format: date-time
        length:
          type: number
          format: float
          description: Length of the path
        geographic:
          $ref: "#/components/schemas/GeoJsonObject"
        schematic:
          $ref: "#/components/schemas/GeoJsonObject"
        slopes:
          description: Slopes on the path
          type: array
          items:
            type: object
            properties:
              gradient: { type: number, format: float }
              position: { type: number, format: float }
            required: [gradient, position]
        curves:
          description: Curves on the path
          type: array
          items:
            type: object
            properties:
              radius: { type: number, format: float }
              position: { type: number, format: float }
            required: [radius, position]
        steps:
          type: array
          items:
            $ref: "#/components/schemas/PathStep"
      required:
        [
          id,
          owner,
          created,
          length,
          geographic,
          schematic,
          slopes,
          curves,
          steps,
        ]

    PathQuery:
      type: object
      properties:
        infra:
          type: number
        steps:
          type: array
          minItems: 2
          items:
            type: object
            properties:
              duration: { type: number, format: float }
              waypoints:
                type: array
                items:
                  $ref: "#/components/schemas/PathWaypoint"
            required: [duration, waypoints]
        rolling_stocks:
          description: List of rolling stocks that must be able to use this path
          type: array
          items: { type: integer }
      required: [infra, steps, rolling_stocks]

    PathStep:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        suggestion: { type: boolean }
        duration: { type: number, format: float }
        path_offset:
          type: number
          format: float
          description: Offset of the step in the path
        location:
          $ref: "#/components/schemas/TrackSectionLocation"
        sch:
          $ref: "#/components/schemas/GeoJsonPosition"
        geo:
          $ref: "#/components/schemas/GeoJsonPosition"
      required: [suggestion, duration, path_offset, location, sch, geo]

    PathWaypoint:
      type: object
      properties:
        track_section:
          description: track section ID of the waypoint
          type: string
        geo_coordinate:
          type: array
          items: { type: number, format: float }
          minItems: 2
          maxItems: 2
        offset:
          type: number
      required: [track_section, geo_cordinate]


    RouteTrackRangesComputed:
      type: object
      description: Route track ranges successfully computed
      required:
        - type
        - track_ranges
      properties:
        type:
          type: string
          enum:
            - Computed
        track_ranges:
          type: array
          items:
            $ref: "#/components/schemas/DirectionalTrackRange"

    RouteTrackRangesNotFoundError:
      type: object
      description: Error when the route id couldn't be found
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - NotFound

    RouteTrackRangesCantComputePathError:
      type: object
      description: Error when the route path couldn't be computed
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - CantComputePath

    Geometry:
      type: object
      description: Definition of a GeoJSON geometry
      oneOf:
        - $ref: "#/components/schemas/Point"
        - $ref: "#/components/schemas/LineString"
        - $ref: "#/components/schemas/Polygon"
        - $ref: "#/components/schemas/MultiPoint"
        - $ref: "#/components/schemas/MultiLineString"
        - $ref: "#/components/schemas/MultiPolygon"

    Point3D:
      type: array
      description: Point in 3D space
      minItems: 2
      maxItems: 3
      items:
        type: number

    Point:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - Point
        coordinates:
          $ref: "#/components/schemas/Point3D"

    LineString:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - LineString
        coordinates:
          type: array
          items:
            $ref: "#/components/schemas/Point3D"

    Polygon:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - Polygon
        coordinates:
          type: array
          items:
            type: array
            items:
              $ref: "#/components/schemas/Point3D"

    MultiPoint:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - MultiPoint
        coordinates:
          type: array
          items:
            $ref: "#/components/schemas/Point3D"

    MultiLineString:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - MultiLineString
        coordinates:
          type: array
          items:
            type: array
            items:
              $ref: "#/components/schemas/Point3D"

    MultiPolygon:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - MultiPolygon
        coordinates:
          type: array
          items:
            type: array
            items:
              type: array
              items:
                $ref: "#/components/schemas/Point3D"


    SimulationReportByTrain:
      properties:
        speeds:
          type: array
          minItems: 1
          items:
            allOf:
              - $ref: "#/components/schemas/SpaceTimePosition"
              - type: object
                properties:
                  speed:
                    type: number
                    format: float
                required: [speed]
        head_positions:
          type: array
          minItems: 1
          items:
            type: array
            minItems: 1
            items:
              $ref: "#/components/schemas/SpaceTimePosition"
        tail_positions:
          type: array
          minItems: 1
          items:
            type: array
            minItems: 1
            items:
              $ref: "#/components/schemas/SpaceTimePosition"
        stops:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Can be null if it's not an operational point
                nullable: true
              name:
                type: string
                description: Can be 'Unknown' if it's not an operational point
              time: { type: number, format: float }
              position: { type: number, format: float }
              duration: { type: number, format: float }
              line_code: { type: number }
              track_number: { type: number }
              line_name: { type: string }
              track_name: { type: string }
            required:
              [
                id,
                name,
                time,
                position,
                duration,
                line_code,
                track_number,
                line_name,
                track_name,
              ]
        route_aspects:
          type: array
          items:
            type: object
            properties:
              signal_id:
                type: string
                description: id of the updated signal
              route_id:
                type: string
                description: id of the affected route on the train path
              time_start:
                type: number
                format: float
                description: the aspect starts being displayed at this time
              time_end:
                type: number
                format: float
                description: the aspect stops being displayed at this time
              position_start:
                type: number
                format: float
                description: the route starts at this position on the train path
              position_end:
                type: number
                format: float
                description: the route ends at this position on the train path
              color:
                type: number
                format: float
                description: color of the aspect (Bits 24-31 are alpha, 16-23 are red, 8-15 are green, 0-7 are blue)
              blinking:
                type: boolean
                description: true if the signal is blinking
              aspect_label:
                type: string
                description: label of the new signal aspect
            required:
              - signal_id
              - route_id
              - time_start
              - time_end
              - position_start
              - position_end
              - color
              - blinking
              - aspect_label
        signals:
          type: array
          items:
            type: object
            properties:
              signal_id: { type: integer }
              aspects:
                type: array
                items:
                  type: string
              geo_position:
                type: array
                items: { type: number, format: float }
                minItems: 2
                maxItems: 2
              schema_position:
                type: array
                items: { type: number, format: float }
                minItems: 2
                maxItems: 2
            required: [signal_id, aspects, geo_position, schema_position]
        mechanical_energy_consumed:
          type: number
          format: float
      required:
        - speeds
        - head_positions
        - tail_positions
        - stops
        - route_aspects
        - signals
        - mechanical_energy_consumed

    SpaceTimePosition:
      type: object
      properties:
        time: { type: number, format: float }
        position: { type: number, format: float }
      required: [time, position, speed]

    SimulationReport:
      properties:
        id:
          type: integer
        name:
          type: string
        labels:
          type: array
          items:
            type: string
        path:
          type: integer
          description: id of the path used for projection
        vmax:
          type: array
          minItems: 2
          items:
            type: object
            properties:
              position: { type: number }
              speed: { type: number }
            required: [position, speed]
        slopes:
          type: array
          minItems: 2
          items:
            type: object
            properties:
              position: { type: number }
              gradient: { type: number }
            required: [position, gradient]
        curves:
          type: array
          minItems: 2
          items:
            type: object
            properties:
              position: { type: number }
              radius: { type: number }
            required: [position, radius]
        base:
          $ref: "#/components/schemas/SimulationReportByTrain"
        eco:
          $ref: "#/components/schemas/SimulationReportByTrain"
        speed_limit_tags:
          type: string
        electrification_ranges:
          description: A list of ranges which should be contiguous and which describe the electrification on the path and if it is handled by the train
          type: array
          items:
            $ref: "#/components/schemas/ElectrificationRange"
          minItems: 1
        power_restriction_ranges:
          description: The list of ranges where power restrictions are applied
          type: array
          items:
            $ref: "#/components/schemas/PowerRestrictionRangeItem"

      required:
        - id
        - name
        - labels
        - path
        - vmax
        - slopes
        - curves
        - base
        - electrification_ranges
        - power_restriction_ranges

    PowerRestrictionRangeItem:
      properties:
        start:
          type: number
          format: double
        stop:
          type: number
          format: double
        code:
          type: string
        handled:
          type: boolean
      required: [start, stop, code, handled]

    ElectrificationRange:
      properties:
        start:
          type: number
          format: double
        stop:
          type: number
          format: double
        electrificationUsage:
          oneOf:
            - $ref: "#/components/schemas/Electrified"
            - $ref: "#/components/schemas/Neutral"
            - $ref: "#/components/schemas/NonElectrified"
          discriminator:
            propertyName: object_type
      required: [start, stop, is_electrified, electrificationUsage]

    Electrified:
      properties:
        mode:
          type: string
        mode_handled:
          type: boolean
        object_type:
          type: string
          enum: ["Electrified"]
        profile:
          type: string
          nullable: true
        profile_handled:
          type: boolean
      required: [mode, mode_handled, object_type, profile_handled]
    Neutral:
      properties:
        lower_pantograph:
          type: boolean
        object_type:
          type: string
          enum: ["Neutral"]
      required: [lower_pantograph, object_type]
    NonElectrified:
      properties:
        object_type:
          type: string
          enum: ["NonElectrified"]
      required: [object_type]

    Waypoint:
      type: array
      items:
        type: object
        properties:
          track_section:
            type: string
          geo_coordinate:
            type: array
            items: { type: number, format: float }
            minItems: 2
            maxItems: 2

    SingleSimulationRequest:
      type: object
      required: [rolling_stock_id, path_id]
      properties:
        rolling_stock_id:
          type: integer
        path_id:
          type: integer
        electrical_profile_set_id:
          type: integer
        initial_speed:
          type: number
          format: float
          default: 0
        scheduled_points:
          default: []
          type: array
          items:
            type: object
            required: [path_offset, time]
            properties:
              path_offset:
                type: number
                format: float
                description: Offset in meters from the start of the path at which the train must be.
              time:
                type: number
                format: float
                description: Time in seconds (elapsed since the train's departure) at which the train must be.
        allowances:
          default: []
          type: array
          items:
            $ref: "#/components/schemas/Allowance"
        stops:
          default: []
          type: array
          items:
            type: object
            properties:
              position:
                type: number
                format: float
              location:
                $ref: "#/components/schemas/TrackLocation"
              duration:
                type: number
                format: float
        tag:
          type: string
        comfort:
          $ref: "#/components/schemas/Comfort"
        power_restriction_ranges:
          description: A list of ranges along the train path where power restrictions apply.
          type: array
          items:
            $ref: "#/components/schemas/PowerRestrictionRange"
          nullable: true
        options:
          allOf:
            - $ref: "#/components/schemas/TrainScheduleOptions"
          nullable: true

    SingleSimulationResponse:
      type: object
      required:
        [
          base_simulation,
          eco_simulation,
          speed_limits,
          warnings,
          electrification_ranges,
          power_restriction_ranges,
        ]
      properties:
        base_simulation:
          $ref: "#/components/schemas/SimulationReportByTrain"
        eco_simulation:
          allOf:
            - $ref: "#/components/schemas/SimulationReportByTrain"
          nullable: true
        speed_limits:
          type: array
          minItems: 2
          items:
            type: object
            properties:
              position: { type: number }
              speed: { type: number }
            required: [position, speed]
        warnings:
          type: array
          items:
            type: string
        electrification_ranges:
          description: A list of ranges which should be contiguous and which describe the electrification on the path and if it is handled by the train
          type: array
          items:
            $ref: "#/components/schemas/ElectrificationRange"
          minItems: 1
        power_restriction_ranges:
          description: The list of ranges where power restrictions are applied
          type: array
          items:
            $ref: "#/components/schemas/PowerRestrictionRangeItem"