openapi.yaml

openapi: 3.0.0
info:
  title: OSRD
  description: OSRD middleware api documentation
  version: 2.0.0
tags:
  - name: infra
    description: Infra
  - name: rolling_stock
    description: Rolling Stock
  - name: timetable
    description: Timetable
  - name: train_schedule
    description: Train Schedule
  - name: pathfinding
    description: Pathfinding
  - name: stdcm
    description: Short term DCM

paths:
  /infra/:
    get:
      tags:
        - infra
      summary: List all available infra
      responses:
        200:
          description: The infra list
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                  next: {}
                  previous: {}
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Infra"
    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 infra list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Infra"
  /infra/{id}/:
    get:
      tags:
        - infra
      summary: Retrieve an infra
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Infra ID
          required: true
      responses:
        200:
          description: The infra information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Infra"
    delete:
      tags:
        - infra
      summary: Delete an infra, his namespace and all entities linked to it
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Timetable ID
          required: true
      responses:
        204:
          description: No content
  /infra/railjson/:
    post:
      tags:
        - infra
      summary: Import an infra from railjson
      requestBody:
        description: Railjson infra
        content:
          application/json:
            schema:
              type: object
              example:
                version: 2.0.0
                operational_points: []
                routes: []
                switch_types: []
                switches: []
                track_section_links: []
                track_sections: []
                signals: []
                buffer_stops: []
                detectors: []
                tvd_sections: []
                script_functions: []
                aspects: []
        required: true
      responses:
        201:
          description: The imported infra id
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
  /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
        - in: query
          name: include_geom
          schema:
            type: boolean
            default: false
          description: Whether the railjson should contain geometry information
      responses:
        200:
          description: The infra in railjson format
          content:
            application/json:
              schema:
                type: object
                description: Follows railjson format
                example:
                  version: 2.0.0
                  operational_points: []
                  routes: []
                  switch_types: []
                  switches: []
                  track_section_links: []
                  track_sections: []
                  signals: []
                  buffer_stops: []
                  detectors: []
                  tvd_sections: []
                  script_functions: []
                  aspects: []
  /pathfinding/:
    post:
      tags:
        - pathfinding
      summary: Create a Path
      requestBody:
        description: Steps of the path
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PathQuery"
      responses:
        201:
          description: The path
          content:
            application/json:
              schema:
                type: array
                items:
                  $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 path
          content:
            application/json:
              schema:
                type: array
                items:
                  $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: Steps of the path
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PathQuery"
      responses:
        200:
          description: The 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
  /rolling_stock/:
    get:
      tags:
        - rolling_stock
      summary: Paginated list of rolling stock
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number
        - in: query
          name: page_size
          schema:
            type: integer
            maximum: 10000
            minimum: 1
            default: 100
          description: Number of elements by page
      responses:
        200:
          description: The rolling stock list
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                  next: {}
                  previous: {}
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/RollingStock"
    post:
      tags:
        - rolling_stock
      summary: Create a rolling stock
      responses:
        200:
          description: The rolling stock list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RollingStock"
  /rolling_stock/{id}/:
    get:
      tags:
        - rolling_stock
      summary: Retrieve a rolling stock
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Rolling Stock ID
          required: true
      responses:
        200:
          description: The rolling stock information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RollingStock"
  /light_rolling_stock/:
    get:
      tags:
        - rolling_stock
      summary: Paginated list of rolling stock with a lighter response
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number
        - in: query
          name: page_size
          schema:
            type: integer
            maximum: 10000
            minimum: 1
            default: 100
          description: Number of elements by page
      responses:
        200:
          description: The rolling stock list
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                  next: {}
                  previous: {}
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/LightRollingStock"
  /light_rolling_stock/{id}/:
    get:
      tags:
        - rolling_stock
      summary: Retrieve a rolling stock's light representation
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Rolling Stock ID
          required: true
      responses:
        200:
          description: The rolling stock without effort curves nor rolling resistance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LightRollingStock"
  /timetable/:
    get:
      tags:
        - timetable
      summary: Paginated list of timetable
      parameters:
        - in: query
          name: infra
          schema:
            type: integer
          description: Filter timetable by infra
        - in: query
          name: page
          schema:
            type: integer
            minimum: 0
          description: Page number
        - in: query
          name: page_size
          schema:
            type: integer
            maximum: 10000
            minimum: 1
            default: 100
          description: Number of elements by page
      responses:
        200:
          description: The timetable list
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                  next: {}
                  previous: {}
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        name:
                          type: string
                        infra:
                          type: number
    post:
      tags:
        - timetable
      summary: Create a timetable
      requestBody:
        description: Infrastructure id and waypoints
        content:
          application/json:
            schema:
              type: object
              properties:
                infra:
                  type: number
                name:
                  type: string
        required: true
      responses:
        201:
          description: The timetable created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: number
                  name:
                    type: string
                  infra:
                    type: number
  /timetable/{id}/:
    get:
      tags:
        - timetable
      summary: Retrieve a timetable and its train schedules
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Timetable ID
          required: true
      responses:
        200:
          description: The timetable content
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: number
                  name:
                    type: string
                  infra:
                    type: number
                  train_schedule:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        train_name:
                          type: string
                        departure_time:
                          type: number
                        train_path:
                          type: number
    delete:
      tags:
        - timetable
      summary: Delete a timetable and its train schedules
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Timetable ID
          required: true
      responses:
        204:
          description: No content
    put:
      tags:
        - timetable
      summary: Update a timetable
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Timetable ID
          required: true
      requestBody:
        description: Infrastructure id and waypoints
        content:
          application/json:
            schema:
              type: object
              properties:
                infra:
                  type: number
                name:
                  type: string
        required: true
      responses:
        200:
          description: The timetable updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: number
                  name:
                    type: string
                  infra:
                    type: number
  /train_schedule/standalone_simulation/:
    post:
      tags:
        - train_schedule
      summary: Create a batch of train schedule
      requestBody:
        description: Standalone simulation parameters
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StandaloneSimulationParameters"
        required: true
      responses:
        201:
          description: The id of the train_schedule created
          content:
            application/json:
              schema:
                type: object
                properties:
                  ids:
                    type: array
                    minItems: 1
                    items:
                      type: number
                      format: integer
  /train_schedule/{id}/:
    get:
      tags:
        - train_schedule
      summary: Retrieve a train schedule
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Train schedule ID
          required: true
      responses:
        200:
          description: The train schedule info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TrainSchedule"
    delete:
      tags:
        - train_schedule
      summary: Delete a train schedule and its result
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Train schedule ID
          required: true
      responses:
        204:
          description: No content
    patch:
      tags:
        - train_schedule
      summary: Update a train_schedule
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Train schedule ID
          required: true
      requestBody:
        description: Train schedule fields
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WritableTrainSchedule"
        required: true
      responses:
        200:
          description: The train schedule info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TrainSchedule"
  /train_schedule/{id}/result/:
    get:
      tags:
        - train_schedule
      summary: Compute and format the simulation result
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Train schedule ID
          required: true
        - in: query
          name: path
          schema:
            type: integer
          description: Path id used to project the train path
      responses:
        200:
          description: The train schedule result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TrainScheduleResult"
  /train_schedule/results/:
    get:
      tags:
        - train_schedule
      summary: Compute and format the simulation result of multiple train schedule
      parameters:
        - in: query
          name: path
          schema:
            type: integer
          description: Path id used to project the train path
        - in: query
          name: train_ids
          schema:
            type: array
            uniqueItems: true
            minItems: 1
            items:
              type: integer
          description: List of train schedule ids
          required: true
      responses:
        200:
          description: The train schedules results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TrainScheduleResult"
  /infra/{id}/speed_limit_tags/:
    get:
      tags:
        - infra
      summary: List all speed limit tags
      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
      responses:
        200:
          description: Voltages list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: number
                  format: float
                example: [750.0, 1500.0, 2500.50]
  /infra/schema/:
    get:
      tags:
        - infra
      summary: Current railjson schema
      responses:
        200:
          description: Json schema
          content:
            application/json:
              schema:
                type: object
                description: Railjson schema following json Schema specification
                example:
                  title: RailJsonInfra
                  type: object
                  properties: { ... }
                  required: [...]
                  definitions: { ... }
  /stdcm/:
    post:
      tags:
        - stdcm
      summary: Find a stdcm and return a simulation result
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/STDCMRequest"
      responses:
        200:
          description: Simulation result
          content:
            application/json:
              schema:
                oneOf:
                  - properties:
                      simulation:
                        $ref: "#/components/schemas/TrainScheduleResult"
                      path:
                        $ref: "#/components/schemas/Path"
                  - type: object
                    properties:
                      error:
                        type: string
                        description: Error message
                        example: No path could be found
        400:
          description: The request body is invalid
components:
  schemas:
    Infra:
      properties:
        id:
          type: integer
        name:
          type: string
        owner:
          type: string
          format: uuid
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    TrainScheduleResultData:
      properties:
        speeds:
          type: array
          minItems: 1
          items:
            type: object
            properties:
              time: { type: number, format: float }
              position: { type: number, format: float }
              speed: { type: number, format: float }
        head_positions:
          type: array
          minItems: 1
          items:
            type: array
            minItems: 1
            items:
              type: object
              properties:
                time: { type: number, format: float }
                position: { type: number, format: float }
        tail_positions:
          type: array
          minItems: 1
          items:
            type: array
            minItems: 1
            items:
              type: object
              properties:
                time: { type: number, format: float }
                position: { type: number, format: float }
        route_begin_occupancy:
          type: array
          minItems: 1
          items:
            type: array
            minItems: 1
            items:
              type: object
              properties:
                time: { type: number, format: float }
                position: { type: number, format: float }
        route_end_occupancy:
          type: array
          minItems: 1
          items:
            type: array
            minItems: 1
            items:
              type: object
              properties:
                time: { type: number, format: float }
                position: { type: number, format: float }
        stops:
          type: array
          items:
            type: object
            properties:
              id:
                type: number
                description: Can be null if it's not an operational point
              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 }
        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
        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
    TrainScheduleResult:
      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 }
        slopes:
          type: array
          minItems: 2
          items:
            type: object
            properties:
              position: { type: number }
              gradient: { type: number }
        curves:
          type: array
          minItems: 2
          items:
            type: object
            properties:
              position: { type: number }
              radius: { type: number }
        base:
          $ref: "#/components/schemas/TrainScheduleResultData"
        eco:
          oneOf:
            - $ref: "#/components/schemas/TrainScheduleResultData"
            - type: object
              properties:
                error: { type: string }
    PathQuery:
      properties:
        infra:
          type: integer
        rolling_stocks:
          type: array
          items:
            type: integer
        steps:
          type: array
          minItems: 2
          items:
            type: object
            properties:
              duration:
                type: number
                format: float
              waypoints:
                $ref: "#/components/schemas/Waypoint"
    Waypoint:
      type: array
      items:
        type: object
        properties:
          track_section:
            type: integer
          geo_coordinate:
            type: array
            items: { type: number, format: float }
            minItems: 2
            maxItems: 2
    STDCMRequest:
      properties:
        infra:
          type: integer
        rolling_stock:
          type: integer
        timetable:
          type: integer
          description: timetable ID
        start_time:
          type: number
          format: double
        end_time:
          type: number
          format: double
        start_points:
          type: array
          items:
            $ref: "#/components/schemas/Waypoint"
            minimum: 1
        end_points:
          type: array
          items:
            $ref: "#/components/schemas/Waypoint"
            minimum: 1
    Path:
      properties:
        id:
          type: integer
        owner:
          type: string
          format: uuid
        created:
          type: string
          format: date-time
        geographic:
          type: object
          description: GeoJson format
        schematic:
          type: object
          description: GeoJson format
        slopes:
          description: Slopes on the path
          type: array
          items:
            type: object
            properties:
              gradient: { type: number, format: float }
              position: { type: number, format: float }
        curves:
          description: Curves on the path
          type: array
          items:
            type: object
            properties:
              radius: { type: number, format: float }
              position: { type: number, format: float }
        steps:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
              suggestion: { type: boolean }
              duration: { type: number, format: float }
              track:
                type: object
                properties:
                  id: { type: string }
                  type: { enum: ["TrackSection"] }
              position: { type: number, format: float }
              sch:
                type: array
                items: { type: number, format: float }
                minItems: 2
                maxItems: 2
              geo:
                type: array
                items: { type: number, format: float }
                minItems: 2
                maxItems: 2
    RollingStock:
      allOf:
        - $ref: "#/components/schemas/LightRollingStock"
        - type: object
          properties:
            effort_curve:
              type: object
              properties:
                speeds:
                  type: array
                  minItems: 2
                  items:
                    type: number
                    format: float
                max_efforts:
                  type: array
                  minItems: 2
                  items:
                    type: number
                    format: float
    LightRollingStock:
      properties:
        version:
          type: string
          example: "2.1"
        name:
          type: string
        length:
          type: number
          format: float
        max_speed:
          type: number
          format: float
        startup_time:
          type: number
          format: float
        startup_acceleration:
          type: number
          format: float
        comfort_acceleration:
          type: number
          format: float
        gamma:
          type: object
          properties:
            type:
              type: string
              enum: ["CONST", "MAX"]
            value:
              type: number
              format: float
        inertia_coefficient:
          type: number
          format: float
        power_class:
          type: number
        features:
          type: array
          items:
            type: string
        mass:
          type: number
          format: float
        rolling_resistance:
          type: object
          properties:
            A:
              type: number
            B:
              type: number
            C:
              type: number
            type:
              type: string
              enum: ["davis"]
        loading_gauge:
          type: string
          enum:
            - "G1"
            - "G2"
            - "GA"
            - "GB"
            - "GB1"
            - "GC"
            - "FR3.3"
            - "FR3.3/GB/G2"
            - "GLOTT"
    TrainSchedule:
      allOf:
        - type: object
          properties:
            id:
              type: integer
        - $ref: "#/components/schemas/WritableTrainSchedule"
    StandaloneSimulationParameters:
      properties:
        timetable:
          type: integer
        path:
          type: integer
        schedules:
          type: array
          minItems: 1
          items:
            type: object
            properties:
              train_name:
                type: string
              rolling_stock:
                type: integer
              departure_time:
                type: number
                format: float
              initial_speed:
                type: number
                format: float
              labels:
                type: array
                items:
                  type: string
              allowances:
                type: array
                items:
                  $ref: "#/components/schemas/Allowance"
              speed_limit_category:
                description: Train category for speed limits
                type: string
    WritableTrainSchedule:
      properties:
        train_name:
          type: string
        timetable:
          type: integer
        rolling_stock:
          type: integer
        departure_time:
          type: number
          format: float
        path:
          type: integer
        initial_speed:
          type: number
          format: float
        labels:
          type: array
          items:
            type: string
        allowances:
          type: array
          items:
            $ref: "#/components/schemas/Allowance"
    Allowance:
      oneOf:
        - $ref: "#/components/schemas/EngineeringAllowance"
        - $ref: "#/components/schemas/StandardAllowance"
      discriminator:
        propertyName: allowance_type
    StandardAllowance:
      properties:
        allowance_type:
          type: string
          enum: ["standard"]
        default_value:
          $ref: "#/components/schemas/AllowanceValue"
        ranges:
          type: array
          items:
            $ref: "#/components/schemas/RangeAllowance"
        distribution:
          type: string
          enum: ["MARECO", "LINEAR"]
        capacity_speed_limit:
          type: number
          format: double
    EngineeringAllowance:
      allOf:
        - type: object
          properties:
            allowance_type:
              type: string
              enum: ["engineering"]
            distribution:
              type: string
              enum: ["MARECO", "LINEAR"]
            capacity_speed_limit:
              type: number
              format: double
        - $ref: "#/components/schemas/RangeAllowance"
    RangeAllowance:
      properties:
        begin_position:
          type: number
        end_position:
          type: number
          example: 1000.0
        value:
          $ref: "#/components/schemas/AllowanceValue"
    AllowanceValue:
      oneOf:
        - $ref: "#/components/schemas/AllowanceTimePerDistanceValue"
        - $ref: "#/components/schemas/AllowanceTimeValue"
        - $ref: "#/components/schemas/AllowancePercentValue"
      discriminator:
        propertyName: value_type
    AllowanceTimePerDistanceValue:
      properties:
        value_type:
          type: string
          enum: ["time_per_distance"]
        minutes:
          type: number
          example: 5.0
          description: Minutes per 100k
    AllowanceTimeValue:
      properties:
        value_type:
          type: string
          enum: ["time"]
        seconds:
          type: number
          example: 180.0
    AllowancePercentValue:
      properties:
        value_type:
          type: string
          enum: ["percentage"]
        percentage:
          type: number
          example: 15.0