openapi.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:
  /health/:
    get:
      responses:
        200:
          description: Check if Editoast is running correctly

  /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

  /search/:
    post:
      summary: Generic search endpoint
      requestBody:
        description: Search query
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                object:
                  type: string
                  example: "operationalpoint"
                query:
                  $ref: "#/components/schemas/SearchQuery"
                page:
                  type: integer
                  default: 1
                page_size:
                  type: integer
                  default: 25
      responses:
        200:
          description: Search results, the structure of the returned objects depend on their type
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - $ref: "#/components/schemas/SearchTrackResult"
                    - $ref: "#/components/schemas/SearchOperationalPointResult"
                    - $ref: "#/components/schemas/SearchSignalResult"
                    - $ref: "#/components/schemas/SearchStudyResult"
                    - $ref: "#/components/schemas/SearchProjectResult"
                    - $ref: "#/components/schemas/SearchScenarioResult"

  /layers/layer/{layer_slug}/mvt/{view_slug}/:
    get:
      tags:
        - layers
      summary: Mvt View Metadata
      parameters:
        - required: true
          schema:
            title: Layer Slug
            type: string
          name: layer_slug
          in: path
        - required: true
          schema:
            title: View Slug
            type: string
          name: view_slug
          in: path
        - required: true
          schema:
            title: Infra id
            type: integer
          name: infra
          in: query
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewMetadata"

  /layers/tile/{layer_slug}/{view_slug}/{z}/{x}/{y}/:
    get:
      tags:
        - layers
      summary: Mvt tile from the cache or the database, cache data in redis if needed
      parameters:
        - required: true
          schema:
            title: Layer Slug
            type: string
          name: layer_slug
          in: path
        - required: true
          schema:
            title: View Slug
            type: string
          name: view_slug
          in: path
        - required: true
          schema:
            title: Z
            type: integer
          name: z
          in: path
        - required: true
          schema:
            title: X
            type: integer
          name: x
          in: path
        - required: true
          schema:
            title: Y
            type: integer
          name: y
          in: path
        - required: true
          schema:
            title: Infra
            type: integer
          name: infra
          in: query
      responses:
        200:
          description: Successful Response
          content:
            application/x-octet-stream:
              schema:
                type: string

  /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"
                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/{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:
      tags:
        - infra
      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"]

  /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: 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:
                  allOf:
                    - $ref: "#/components/schemas/TrackLocation"
                    - type: object
                      properties:
                        direction:
                          $ref: "#/components/schemas/Direction"
                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

  /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 }

  /electrical_profile_set/:
    get:
      tags:
        - electrical_profiles
      summary: Retrieve the list of ids and names of electrical profile sets available
      responses:
        200:
          description: The list of ids and names of electrical profile sets available
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - id
                    - name
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                      example: "France 2023"

    post:
      tags:
        - electrical_profiles
      summary: import a new electrical profile set
      parameters:
        - in: query
          name: name
          required: true
          schema:
            type: string
      responses:
        200:
          description: The list of ids and names of electrical profile sets available
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ElectricalProfile"

  /electrical_profile_set/{id}/:
    get:
      tags:
        - electrical_profiles
      summary: Retrieve the set of electrical profiles with the given id
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Electrical profile set ID
          required: true
      responses:
        200:
          description: The list of electrical profiles in the set
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ElectricalProfile"

  /electrical_profile_set/{id}/level_order/:
    get:
      tags:
        - electrical_profiles
      summary: Retrieve the order of strength of the electrical profiles in the set with the given id
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Electrical profile set ID
          required: true
      responses:
        200:
          description: A dictionary mapping catenary modes to a list of electrical profiles ordered by decreasing strength
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
                example:
                  "1500": ["A", "B", "C"]
                  "25000": ["25000", "22500", "20000"]

  /documents/{key}/:
    get:
      tags:
        - documents
      summary: Retrieve a document binary content
      parameters:
        - in: path
          name: key
          schema:
            type: integer
          description: A key identifying the document
          required: true
      responses:
        200:
          description: A document of any type (can be an image, a pdf...)
    delete:
      tags:
        - documents
      summary: Delete a document
      parameters:
        - in: path
          name: key
          schema:
            type: integer
          description: A key identifying the document
          required: true
      responses:
        204:
          description: No content

  /documents/:
    post:
      tags:
        - documents
      summary: Add a document
      responses:
        201:
          description: The key of the added document
          content:
            application/json:
              schema:
                type: object
                properties:
                  document_key:
                    type: integer
                    example: 42

  /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"
                required:
                  - results

  /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 with their simplified effort curves
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LightRollingStock"

  /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

  /rolling_stock/:
    post:
      tags:
        - rolling_stock
      summary: Create a rolling stock
      parameters:
        - in: query
          name: locked
          description: whether or not the rolling_stock can be edited/deleted.
          schema:
            default: false
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RollingStockUpsertPayload"
      responses:
        200:
          description: The created rolling stock
          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"
    patch:
      tags:
        - rolling_stock
      summary: Patch a rolling stock
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Rolling Stock ID
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RollingStockUpsertPayload"
      responses:
        200:
          description: The updated rolling stock
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RollingStock"
    delete:
      tags:
        - rolling_stock
      summary: Delete a rolling_stock and all entities linked to it
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: rolling_stock id
          required: true
        - in: query
          name: force
          description: force the deletion even if it’s used
          schema:
            type: boolean
            default: false
      responses:
        204:
          description: No content
        409:
          description: Rolling stock is used in a train schedule.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RollingStockUsage"

  /rolling_stock/{id}/locked/:
    patch:
      tags:
        - rolling_stock
      summary: Update rolling_stock locked field
      parameters:
        - in: path
          name: id
          description: Rolling_stock id
          required: true
          schema:
            type: integer
      requestBody:
        description: New locked value
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                locked:
                  type: boolean
      responses:
        204:
          description: No content
        404:
          description: Not found

  /rolling_stock/{id}/livery/:
    post:
      tags:
        - rolling_stock
        - rolling_stock_livery
      summary: Create a rolling stock livery
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Rolling Stock ID
          required: true
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                images:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        200:
          description: The rolling stock livery
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RollingStockLivery"

  /projects/:
    post:
      tags:
        - projects
      summary: Create a new project
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectCreateRequest"
      responses:
        201:
          description: The created project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectResult"
    get:
      tags:
        - projects
      summary: Paginated list of projects
      parameters:
        - in: query
          name: ordering
          schema:
            type: string
            enum:
              [
                "NameAsc",
                "NameDesc",
                "CreationDateAsc",
                "CreationDateDesc",
                "LastModifiedAsc",
                "LastModifiedDesc",
              ]
        - in: query
          name: name
          schema:
            type: string
          description: Filter projects by name
        - in: query
          name: description
          schema:
            type: string
          description: Filter projects by description
        - in: query
          name: tags
          schema:
            type: string
          description: Filter projects by tags
        - 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 project list
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                  next: {}
                  previous: {}
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProjectResult"

  /projects/{project_id}/:
    get:
      tags:
        - projects
      summary: Retrieve a project
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          description: project id you want to retrieve
          required: true
      responses:
        200:
          description: The project info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectResult"
    patch:
      tags:
        - projects
      summary: Update a project
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          description: project id you want to update
          required: true
      requestBody:
        description: The fields you want to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectPatchRequest"
      responses:
        200:
          description: The project updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectResult"
    delete:
      tags:
        - projects
      summary: delete a project
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          description: project id you want to delete
          required: true
      responses:
        204:
          description: No content

  /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
                  train_schedules:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        train_name:
                          type: string
                        departure_time:
                          type: number
                        train_path:
                          type: number

  /timetable/{id}/conflicts/:
    get:
      tags:
        - timetable
      summary: Retrieve all conflicts for a specific timetable
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Timetable ID
          required: true
      responses:
        200:
          description: The timetable conflicts content
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    train_ids:
                      type: array
                      items:
                        type: number
                    train_names:
                      type: array
                      items:
                        type: string
                    start_time:
                      type: string
                    end_time:
                      type: string
                    conflict_type:
                      type: string
                  required:
                    [
                      train_ids,
                      train_names,
                      start_time,
                      end_time,
                      conflict_type,
                    ]

  /projects/{project_id}/studies/:
    post:
      tags:
        - studies
      summary: Create a new operational study
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StudyUpsertRequest"
      responses:
        201:
          description: The created operational study
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StudyResult"
    get:
      tags:
        - studies
      summary: Paginated list of operational studies
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          required: true
        - in: query
          name: ordering
          schema:
            type: string
            enum:
              [
                "NameAsc",
                "NameDesc",
                "CreationDateAsc",
                "CreationDateDesc",
                "LastModifiedAsc",
                "LastModifiedDesc",
              ]
        - in: query
          name: name
          schema:
            type: string
          description: Filter operational studies by name
        - in: query
          name: description
          schema:
            type: string
          description: Filter operational studies by description
        - in: query
          name: tags
          schema:
            type: string
          description: Filter operational studies by tags
        - 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 studies list
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                  next: {}
                  previous: {}
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/StudyResult"

  /projects/{project_id}/studies/{study_id}/:
    get:
      tags:
        - studies
      summary: Retrieve an operational study
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          description: project id refered to the operational study
          required: true
        - in: path
          required: true
          name: study_id
          schema:
            type: integer
          description: study id you want to retrieve
      responses:
        200:
          description: The operational study info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StudyResult"
    patch:
      tags:
        - studies
      summary: update an operational study
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          description: project id refered to the study
          required: true
        - in: path
          required: true
          name: study_id
          schema:
            type: integer
          description: study id you want to retrieve
      requestBody:
        description: The fields you want to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StudyUpsertRequest"
      responses:
        200:
          description: The operational study updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StudyResult"
    delete:
      tags:
        - studies
      summary: delete an operational study
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          description: project id refered to the operational study
          required: true
        - in: path
          required: true
          name: study_id
          schema:
            type: integer
          description: study id you want to delete
      responses:
        204:
          description: No content

  /projects/{project_id}/studies/{study_id}/scenarios/:
    post:
      tags:
        - scenarios
      summary: Create a new scenario
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          required: true
        - in: path
          required: true
          name: study_id
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScenarioRequest"
      responses:
        201:
          description: The created scenario
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScenarioResult"
    get:
      tags:
        - scenarios
      summary: Paginated list of scenarios
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          required: true
        - in: path
          required: true
          name: study_id
          schema:
            type: integer
        - in: query
          name: ordering
          schema:
            type: string
            enum:
              [
                "NameAsc",
                "NameDesc",
                "CreationDateAsc",
                "CreationDateDesc",
                "LastModifiedAsc",
                "LastModifiedDesc",
              ]
        - 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: list of scenarios
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                  next: {}
                  previous: {}
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/ScenarioListResult"

  /projects/{project_id}/studies/{study_id}/scenarios/{scenario_id}/:
    get:
      tags:
        - scenarios
      summary: Retrieve a scenario
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          description: project id refered to the scenario
          required: true
        - in: path
          required: true
          name: study_id
          schema:
            type: integer
        - in: path
          required: true
          name: scenario_id
          schema:
            type: integer
          description: scenario id you want to retrieve
      responses:
        200:
          description: The operational study info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScenarioResult"
    delete:
      tags:
        - scenarios
      summary: delete a scenario
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          description: project id refered to the scenario
          required: true
        - in: path
          required: true
          name: study_id
          schema:
            type: integer
          description: study id refered to the scenario
        - in: path
          required: true
          name: scenario_id
          schema:
            type: integer
          description: scenario id you want to delete
      responses:
        204:
          description: No content
    patch:
      tags:
        - scenarios
      summary: update a scenario
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
          description: project id refered to the scenario
          required: true
        - in: path
          required: true
          name: study_id
          schema:
            type: integer
          description: study refered to the scenario
        - in: path
          required: true
          name: scenario_id
          schema:
            type: integer
          description: scenario you want to update
      requestBody:
        description: The fields you want to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScenarioPatchRequest"
      responses:
        200:
          description: The scenario updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScenarioResult"

  /pathfinding/{path_id}/catenaries/:
    get:
      tags:
        - infra
      summary: Retrieve the modes of catenaries along a path
      parameters:
        - in: path
          name: path_id
          schema:
            type: integer
          description: The path's id
          required: true
      responses:
        200:
          description: A list of ranges associated to catenary modes. When a catenary overlapping another is found, a warning is added to the list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  catenary_ranges:
                    type: array
                    items:
                      $ref: "#/components/schemas/CatenaryRange"
                  warnings:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          enum: ["CatenaryOverlap"]
                        catenary_id:
                          type: string
                        overlapping_ranges:
                          type: array
                          items:
                            $ref: "#/components/schemas/TrackRange"

  /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 and run a simulation accordingly
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Train schedule ID
          required: true
      requestBody:
        description: Train schedule fields
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/TrainSchedule"
        required: true
      responses:
        200:
          description: The train schedule was updated successfully

  /train_schedule/{id}/result/:
    get:
      tags:
        - train_schedule
      summary: Retrieve a simulation result
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Train schedule ID
          required: true
        - in: query
          name: path_id
          schema:
            type: integer
          description: Path id used to project the train path
          required: true
      responses:
        200:
          description: The train schedule result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimulationReport"

  /train_schedule/results/:
    get:
      tags:
        - train_schedule
      summary: Retrieve the simulation result of multiple train schedules
      parameters:
        - in: query
          name: path_id
          schema:
            type: integer
          description: Path id used to project the train path
          required: true
        - in: query
          name: train_ids
          schema:
            type: string
            pattern: ^\d+(,\d+)*$
          description: List of train schedule ids to return the results of
          required: true
      responses:
        200:
          description: The train schedules results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SimulationReport"

  /train_schedule/standalone_simulation/:
    post:
      tags:
        - train_schedule
      summary: Create a batch of train schedule and run simulations accordingly
      requestBody:
        description: The list of train schedules to simulate
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                $ref: "#/components/schemas/TrainSchedule"
        required: true
      responses:
        201:
          description: The ids of the train_schedules created
          content:
            application/json:
              schema:
                type: array
                minItems: 1
                items:
                  type: number
                  format: integer

components:
  schemas:
    Battery:
      description: energy source for a rolling stock representing a battery
      type: object
      required:
        [
          energy_source_type,
          max_input_power,
          max_output_power,
          energy_storage,
          efficiency,
        ]
      properties:
        energy_source_type:
          type: string
          enum: ["Battery"]
        max_input_power:
          $ref: "#/components/schemas/SpeedDependantPower"
        max_output_power:
          $ref: "#/components/schemas/SpeedDependantPower"
        energy_storage:
          $ref: "#/components/schemas/EnergyStorage"
        efficiency:
          type: number
          format: float
          minimum: 0
          maximum: 1

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

    Catenary:
      description: energy source for a rolling stock representing a catenary
      type: object
      required:
        [energy_source_type, max_input_power, max_output_power, efficiency]
      properties:
        energy_source_type:
          type: string
          enum: ["Catenary"]
        max_input_power:
          $ref: "#/components/schemas/SpeedDependantPower"
        max_output_power:
          $ref: "#/components/schemas/SpeedDependantPower"
        efficiency:
          type: number
          format: float
          minimum: 0
          maximum: 1

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

    ConditionalEffortCurve:
      type: object
      properties:
        cond:
          type: object
          nullable: true
          properties:
            comfort:
              $ref: "#/components/schemas/Comfort"
              nullable: true
            electrical_profile_level:
              type: string
              nullable: true
            power_restriction_code:
              type: string
              nullable: true
        curve:
          $ref: "#/components/schemas/EffortCurve"

    EffortCurve:
      type: object
      properties:
        speeds:
          type: array
          example: [0.0, 2.958, 46.719]
          minItems: 2
          items:
            type: number
            format: float
        max_efforts:
          type: array
          example: [23500.0, 23200.0, 21200.0]
          minItems: 2
          items:
            type: number
            format: float

    EnergySource:
      description: enery source of a rolling stock
      oneOf:
        - $ref: "#/components/schemas/Catenary"
        - $ref: "#/components/schemas/PowerPack"
        - $ref: "#/components/schemas/Battery"
      discriminator:
        propertyName: energy_source_type

    EnergyStorage:
      description: energy storage of an energy source (of a rolling stock, can be a electrical battery or a hydrogen/fuel powerPack)
      type: object
      required: [capacity, soc, soc_min, soc_max, refill_law]
      properties:
        capacity:
          type: number
          format: float
        soc:
          type: number
          format: float
          minimum: 0
          maximum: 1
        soc_min:
          type: number
          format: float
          minimum: 0
          maximum: 1
        soc_max:
          type: number
          format: float
          minimum: 0
          maximum: 1
        refill_law:
          description: physical law defining how the storage can be refilled
          nullable: true
          type: object
          properties:
            tau:
              type: number
              format: float
              minimum: 0
            soc_ref:
              type: number
              format: float
              minimum: 0
              maximum: 1
          required: [tau, soc_ref]

    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
        - TrackSectionLink
        - 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_section_links:
          type: array
        track_sections:
          type: array
        signals:
          type: array
        buffer_stops:
          type: array
        speed_sections:
          type: array
        catenaries:
          type: array
        detectors:
          type: array

    Operation:
      oneOf:
        - $ref: "#/components/schemas/RailjsonObject"
        - $ref: "#/components/schemas/DeleteOperation"
        - $ref: "#/components/schemas/UpdateOperation"

    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

    ViewMetadata:
      properties:
        type:
          type: string
          example: vector
        name:
          type: string
          example: track_sections
        promotedId:
          type: object
          example: { track_sections: "id" }
        scheme:
          type: string
          example: "xyz"
        tiles:
          type: array
          items:
            type: string
            example: http://localhost:7070/tile/track_sections/geo/{z}/{x}/{y}/?infra=1
        attribution:
          type: string
        minzoom:
          type: integer
        maxzoom:
          type: integer
          example: 18

    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_track_links
        - 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

    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]

    TrackRange:
      type: object
      description: Track range
      properties:
        track:
          type: string
          example: 01234567-89ab-cdef-0123-456789abcdef
        begin:
          type: number
          format: float
        end:
          type: number
          format: float
          example: 100

    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"

    LightRollingStock:
      allOf:
        - $ref: "#/components/schemas/RollingStockBase"
        - type: object
          properties:
            id:
              type: number
            liveries:
              type: array
              items:
                $ref: "#/components/schemas/RollingStockLivery"
            effort_curves:
              type: object
              properties:
                default_mode:
                  type: string
                modes:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      is_electric:
                        type: boolean
                    required: [is_electric]
              required: [default_mode, modes]
          required: [id, liveries, effort_curves]

    Path:
      properties:
        id: { type: integer }
        owner:
          type: string
          format: uuid
        created:
          type: string
          format: date-time
        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, 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 }
        track: { type: string }
        position: { type: number, format: float }
        sch:
          $ref: "#/components/schemas/GeoJsonPosition"
        geo:
          $ref: "#/components/schemas/GeoJsonPosition"
      required: [id, name, suggestion, duration, track, position, 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]

    PowerPack:
      description: energy source for a rolling stock representing a power pack (hydrogen, fuel...)
      type: object
      required:
        [
          energy_source_type,
          max_input_power,
          max_output_power,
          energy_storage,
          efficiency,
        ]
      properties:
        energy_source_type:
          type: string
          enum: ["PowerPack"]
        max_input_power:
          $ref: "#/components/schemas/SpeedDependantPower"
        max_output_power:
          $ref: "#/components/schemas/SpeedDependantPower"
        energy_storage:
          $ref: "#/components/schemas/EnergyStorage"
        efficiency:
          type: number
          format: float
          minimum: 0
          maximum: 1

    RollingStock:
      allOf:
        - $ref: "#/components/schemas/RollingStockUpsertPayload"
        - type: object
          properties:
            id:
              type: number
            liveries:
              type: array
              items:
                $ref: "#/components/schemas/RollingStockLivery"
          required: [id, liveries]

    RollingStockUpsertPayload:
      allOf:
        - $ref: "#/components/schemas/RollingStockBase"
        - type: object
          properties:
            effort_curves:
              type: object
              properties:
                default_mode:
                  type: string
                modes:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      curves:
                        type: array
                        items:
                          $ref: "#/components/schemas/ConditionalEffortCurve"
                      default_curve:
                        $ref: "#/components/schemas/EffortCurve"
                      is_electric:
                        type: boolean
                    required: [curves, default_curve, is_electric]
              required: [default_mode, modes]
          required: [effort_curves]

    RollingStockBase:
      properties:
        version:
          type: string
          example: "3.0"
        name:
          type: string
        locked:
          type: boolean
          default: false
          description: Whether the rolling stock can be edited/deleted or not.
        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
          required: [type, value]
        inertia_coefficient:
          type: number
          format: float
        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"]
          required: [A, B, C, type]
        loading_gauge:
          type: string
          enum:
            - "G1"
            - "G2"
            - "GA"
            - "GB"
            - "GB1"
            - "GC"
            - "FR3.3"
            - "FR3.3/GB/G2"
            - "GLOTT"
        base_power_class:
          type: string
          example: "5"
        power_restrictions:
          type: object
          description: Mapping of power restriction code to power class
          additionalProperties:
            type: string
          example:
            "C1US": "4"
            "C2US": "3"
        energy_sources:
          type: array
          items:
            $ref: "#/components/schemas/EnergySource"
        electrical_power_startup_time:
          type: number
          nullable: true
          format: float
          description: The time the train takes before actually using electrical power (in seconds). Is null if the train is not electric.
          example: 5.0
        raise_pantograph_time:
          type: number
          nullable: true
          format: float
          description: The time it takes to raise this train's pantograph in seconds. Is null if the train is not electric.
          example: 15.0
        metadata:
          type: object
          properties:
            detail:
              type: string
            family:
              type: string
            grouping:
              type: string
            number:
              type: string
            reference:
              type: string
            series:
              type: string
            subseries:
              type: string
            type:
              type: string
            unit:
              type: string
          example:
            detail: "BB 7200"
            family: "LOCOMOTIVES"
            grouping: "Locomotives électriques courant continu"
            number: "1"
            reference: "7200"
            series: "BB 7200"
            subseries: "GV"
            type: "Locomotives électriques"
            unit: "US"
          required:
            [
              detail,
              family,
              grouping,
              number,
              reference,
              series,
              subseries,
              type,
              unit,
            ]
      required:
        - version
        - name
        - length
        - max_speed
        - startup_time
        - startup_acceleration
        - comfort_acceleration
        - gamma
        - inertia_coefficient
        - features
        - mass
        - rolling_resistance
        - loading_gauge
        - base_power_class
        - power_restrictions
        - metadata
        - energy_sources
        - electrical_power_startup_time
        - raise_pantograph_time

    RollingStockLivery:
      properties:
        id:
          type: number
        name:
          type: string
        compound_image_id:
          type: number
          nullable: true
      required: [id, name, compound_image_id]

    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

    SpeedDependantPower:
      description: power-speed curve (in an energy source)
      type: object
      required: [speeds, powers]
      properties:
        speeds:
          type: array
          items:
            type: number
            format: float
        powers:
          type: array
          items:
            type: number
            format: float

    ElectricalProfile:
      type: object
      properties:
        value:
          type: string
          example: "A"
        power_class:
          type: string
          example: "1"
        track_ranges:
          type: array
          items:
            $ref: "#/components/schemas/TrackRange"

    CatenaryRange:
      type: object
      properties:
        begin:
          type: number
          format: float
          example: 0.0
        end:
          type: number
          format: float
          example: 100.0
        mode:
          type: string
          example: "25000"

    SearchQuery:
      type: array
      minItems: 1
      nullable: true
      items:
        oneOf:
          - type: boolean
          - type: number
          - type: integer
          - type: string
          - $ref: "#/components/schemas/SearchQuery"
      example:
        [
          "and",
          [
            "or",
            ["search", ["name"], "mich st"],
            ["search", ["trigram"], null],
          ],
          ["=", ["infra_id"], 2],
        ]

    SearchOperationalPointResult:
      required:
        - obj_id
        - name
        - geographic
        - ch
        - schematic
        - trigram
        - track_sections
      properties:
        obj_id:
          type: string
        infra_id:
          type: string
        name:
          type: string
        uic:
          type: integer
        trigram:
          type: string
        ch:
          type: string
        track_sections:
          type: array
          items:
            type: object
            required:
              - track
              - position
            properties:
              track:
                type: string
              position:
                type: integer
        geographic:
          $ref: "#/components/schemas/MultiPoint"
        schematic:
          $ref: "#/components/schemas/MultiPoint"

    SearchTrackResult:
      required:
        - infra_id
        - line_code
        - line_name
      properties:
        infra_id:
          type: integer
        line_code:
          type: integer
        line_name:
          type: string

    SearchSignalResult:
      required:
        - label
        - geographic
        - schematic
        - line_code
        - line_name
      properties:
        label:
          type: string
        infra_id:
          type: integer
        aspects:
          type: array
          items:
            type: string
        systems:
          type: array
          items:
            type: string
        type:
          type: string
        line_code:
          type: integer
        line_name:
          type: string
        geographic:
          $ref: "#/components/schemas/Point"
        schematic:
          $ref: "#/components/schemas/Point"

    SearchProjectResult:
      required:
        - id
        - name
        - description
        - last_modification
      properties:
        id:
          type: integer
        image:
          type: integer
        name:
          type: string
        studies_count:
          type: integer
        description:
          type: string
        last_modification:
          type: string
          format: date-time
        tags:
          type: array

    SearchStudyResult:
      required:
        - id
        - name
        - project_id
        - last_modification
      properties:
        id:
          type: integer
        project_id:
          type: integer
        name:
          type: string
        scenarios_count:
          type: integer
        description:
          type: string
        last_modification:
          type: string
          format: date-time
        tags:
          type: array
          items:
            type: string

    SearchScenarioResult:
      required:
        - id
        - name
        - study_id
        - last_modification
        - infra_id
        - timetable_id
      properties:
        id:
          type: integer
        study_id:
          type: integer
        electrical_profile_set_id:
          type: integer
        name:
          type: string
        trains_count:
          type: integer
        description:
          type: string
        last_modification:
          type: string
          format: date-time
        infra_id:
          type: integer
        infra_name:
          type: string
        tags:
          type: array
          items:
            type: string

    ProjectCreateRequest:
      properties:
        name:
          type: string
          maxLength: 128
        objectives:
          type: string
          maxLength: 4096
          default: ""
        description:
          type: string
          maxLength: 1024
          default: ""
        funders:
          type: string
          maxLength: 1024
          default: ""
        budget:
          type: integer
        image:
          type: integer
          description: The id of the image in the document table
        tags:
          type: array
          items:
            type: string
            maxLength: 255
      required:
        - name

    ProjectPatchRequest:
      properties:
        name:
          type: string
          maxLength: 128
        objectives:
          type: string
          maxLength: 4096
        description:
          type: string
          maxLength: 1024
        funders:
          type: string
          maxLength: 1024
        budget:
          type: integer
        image:
          type: integer
          description: The id of the image in the document table
        tags:
          type: array
          items:
            type: string
            maxLength: 255

    ProjectResult:
      properties:
        id:
          type: integer
        name:
          type: string
        objectives:
          type: string
        description:
          type: string
        funders:
          type: string
        budget:
          type: integer
        image:
          type: integer
          nullable: true
          description: the image id
        creation_date:
          type: string
          format: date-time
        last_modification:
          type: string
          format: date-time
        studies_count:
          type: integer
        tags:
          type: array
          items:
            type: string

    StudyUpsertRequest:
      properties:
        name:
          type: string
          maxLength: 128
        service_code:
          type: string
          maxLength: 128
        business_code:
          type: string
          maxLength: 128
        description:
          type: string
          maxLength: 1024
        budget:
          type: integer
        tags:
          type: array
          items:
            type: string
            maxLength: 255
        start_date:
          type: string
          nullable: true
          format: date-time
        expected_end_date:
          type: string
          nullable: true
          format: date-time
        actual_end_date:
          type: string
          nullable: true
          format: date-time
        state:
          type: string
          enum: ["started", "inProgress", "finish"]
        study_type:
          type: string
          enum:
            [
              "timeTables",
              "flowRate",
              "parkSizing",
              "garageRequirement",
              "operationOrSizing",
              "operability",
              "strategicPlanning",
              "chartStability",
              "disturbanceTests",
            ]
      required: [name, tags]

    StudyResult:
      properties:
        id:
          type: integer
        name:
          type: string
        project_id:
          type: integer
        description:
          type: string
        budget:
          type: integer
        tags:
          type: array
          items:
            type: string
        service_code:
          type: string
        business_code:
          type: string
        creation_date:
          type: string
          format: date-time
        last_modification:
          type: string
          format: date-time
        scenarios_count:
          type: integer
        start_date:
          type: string
          nullable: true
          format: date-time
        expected_end_date:
          type: string
          nullable: true
          format: date-time
        actual_end_date:
          type: string
          nullable: true
          format: date-time
        state:
          type: string
          enum: ["started", "inProgress", "finish"]
        study_type:
          type: string
          enum:
            [
              "timeTables",
              "flowRate",
              "parkSizing",
              "garageRequirement",
              "operationOrSizing",
              "operability",
              "strategicPlanning",
              "chartStability",
              "disturbanceTests",
            ]
      required:
        - id
        - name
        - project_id
        - description
        - budget
        - tags
        - service_code
        - business_code
        - creation_date
        - last_modification
        - scenarios_count
        - start_date
        - expected_end_date
        - actual_end_date

    ScenarioRequest:
      properties:
        name:
          type: string
          maxLength: 128
        description:
          type: string
          maxLength: 1024
        tags:
          type: array
          items:
            type: string
            maxLength: 255
        infra_id:
          type: integer
        electrical_profile_set_id:
          type: number
          description: Electrical profile set id (if any)
      required:
        - "name"
        - "infra_id"

    ScenarioPatchRequest:
      properties:
        name:
          type: string
          maxLength: 128
        description:
          type: string
          maxLength: 1024
        tags:
          type: array
          items:
            type: string
            maxLength: 255

    ScenarioResult:
      properties:
        id:
          type: integer
        name:
          type: string
        study_id:
          type: integer
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        infra_id:
          type: integer
        infra_name:
          type: string
        electrical_profile_set_id:
          type: integer
          nullable: true
        electrical_profile_set_name:
          type: string
          nullable: true
        creation_date:
          type: string
          format: date-time
        last_modification:
          type: string
          format: date-time
        timetable_id:
          type: integer
        trains_count:
          type: integer
        trains_schedules:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              train_name:
                type: string
              departure_time:
                type: string
              train_path:
                type: integer

    ScenarioListResult:
      properties:
        id:
          type: integer
        name:
          type: string
        study_id:
          type: integer
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        infra_id:
          type: integer
        infra_name:
          type: string
        electrical_profile_set_id:
          type: integer
          nullable: true
        electrical_profile_set_name:
          type: string
          nullable: true
        creation_date:
          type: string
          format: date-time
        last_modification:
          type: string
          format: date-time
        timetable_id:
          type: integer
        trains_count:
          type: integer

    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"

    TrainSchedule:
      type: object
      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
        scheduled_points:
          type: array
          items:
            type: object
            required: [position, time]
            properties:
              position:
                type: number
                format: float
                description: Position 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:
          type: array
          items:
            $ref: "#/components/schemas/Allowance"
        speed_limit_tags:
          description: Train category for speed limits
          type: string
        comfort:
          $ref: "#/components/schemas/Comfort"
        options:
          allOf:
            - $ref: "#/components/schemas/TrainScheduleOptions"
          nullable: true
        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
    TrainScheduleOptions:
      description: Options for the standalone simulation
      type: object
      properties:
        ignore_electrical_profiles:
          type: boolean
          nullable: true

    RollingStockUsage:
      type: object
      properties:
        rolling_stock_id:
          type: integer
        usage:
          type: object
          properties:
            train_schedule_id:
              type: integer
            train_name:
              type: string
            project_id:
              type: integer
            project_name:
              type: string
            study_id:
              type: integer
            study_name:
              type: string
            scenario_id:
              type: integer
            scenario_name:
              type: string
          required:
            - train_schedule_id
            - train_name
            - project_id
            - project_name
            - study_id
            - study_name
            - scenario_id
            - scenario_name
      required:
        - rolling_stock_id
        - usage
    
    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"
      required: [begin_position, end_position, power_restriction_code]

    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
      required:
        [
          allowance_type,
          default_value,
          ranges,
          distribution,
          capacity_speed_limit,
        ]

    EngineeringAllowance:
      allOf:
        - type: object
          properties:
            allowance_type:
              type: string
              enum: ["engineering"]
            distribution:
              type: string
              enum: ["MARECO", "LINEAR"]
            capacity_speed_limit:
              type: number
              format: double
          required: [allowance_type, distribution, capacity_speed_limit]
        - $ref: "#/components/schemas/RangeAllowance"

    RangeAllowance:
      properties:
        begin_position:
          type: number
        end_position:
          type: number
          example: 1000.0
        value:
          $ref: "#/components/schemas/AllowanceValue"
      required: [begin_position, end_position, value]

    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
      required: [value_type, minutes]

    AllowanceTimeValue:
      properties:
        value_type:
          type: string
          enum: ["time"]
        seconds:
          type: number
          example: 180.0
      required: [value_type, seconds]

    AllowancePercentValue:
      properties:
        value_type:
          type: string
          enum: ["percentage"]
        percentage:
          type: number
          example: 15.0
      required: [value_type, percentage]

    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: 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 }
              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_conditions:
          type: array
          items:
            description: The catenary mode, electrical profile and power restriction encountered along the path. <*_seen> variables are filled only when they differ from the ones <*_used>.
            type: array
            items:
              type: object
              properties:
                start:
                  type: number
                  format: double
                stop:
                  type: number
                  format: double
                mode_used:
                  type: string
                profile_used:
                  type: string
                  nullable: true
                restriction_used:
                  type: string
                  nullable: true
                mode_seen:
                  type: string
                  nullable: true
                profile_seen:
                  type: string
                  nullable: true
                restriction_seen:
                  type: string
                  nullable: true
              required: [start, stop, mode_used]
      required:
        - id
        - name
        - labels
        - path
        - vmax
        - slopes
        - curves
        - base
        - electrification_conditions