openapi: "3.0.0"
info:
  version: 0.25.0
  title: Snapshots API
  license:
    name: MIT
servers:
  - url: "https://snapshots-rest-api.aptivcs.com"
    description: "Prod - US"
  - url: "https://snapshots-rest-api.eu.aptivcs.com"
    description: "Prod - EU"
  - url: "http://localhost:8080"
    description: "Local development"
  - url: "https://snapshots-rest-api.qa.aptivcs.com"
    description: "QA environment"
  - url: "https://snapshots-rest-api.aptivcs.cn"
    description: "Prod - China"
paths:
  /healthz:
    get:
      summary: Get the health of the application
      operationId: getHealth
      tags:
        - Health
      responses:
        "200":
          description: Healthy server
          content:
            text/plain:
              schema:
                type: string
  /snapshotanalysis:
    post:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/snapshot-analysis.write
      summary: Create SnapshotAnalysis
      description: |
        Asynchronously processes Snapshot data based on the input defined in the SnapshotAnalysisTemplate.
        Results in a SnapshotAnalysis resource that contains a reference to a SignalAnalysis resource.
        Poll for the processing status using `/snapshotanalysis/{id}/processingState`. Once `SnapshotAnalysis.processingState.status` is 'done', the SnapshotAnalysis.signalAnalysisId property will contain a reference to the SignalAnalysis resource. This resource can be used to retrieve the computed data or create a SignalAnalysisExport resource through POST /signalanalysisexports.
      operationId: createNewSnapshotAnalysis
      tags:
        - Snapshot Analysis
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
      requestBody:
        description: | 
          # Snapshot parameters
          SnapshotParameters are objects that represent a Signal. Each SnapshotParameter has an id which can be used to reference the Signal in an expression. SnapshotParameter.name is a name given to the Signal.

          # SignalExpression
          A SignalExpression is a keyed mathematical formula that contains an expression. These SignalExpression(s) are evaluated at run time in order to compute keyed synthetic data. The Synthetic data is a result of computing the expression against the set of Signals at a given epoch time.

          # Expression
          Mathematical formula that references SnapshotParameters(signals) through their ids.

          ### Syntax: c123
          Adding two Signals together at a single epoch.

          - `c{SnapshotParameter.id} + c{SnapshotParameter.id}`
          - `c1 + c2` add signal 1 and signal 2 together.

          # SnapshotAnalysisTemplate
          The SnapshotAnalysisTemplate contains important input used in the processing of a SnapshotAnalysis resource.

          # SnapshotAnalysisTemplate.signalExpressions
          SnapshotAnalysisTemplate.signalExpressions will be used to synthesize Signal data into Synthetics results.

          # SnapshotAnalysisTemplate.sections
          QNG specific input used to define charting information.

          # SnapshotAnalysisTemplate.criteria
          Criteria used to select Snapshot data. Contains vehicle filters and Snapshot filters. Vehicle filters are used to select Signal data related to the vehicles that match the filter.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SnapshotAnalysisTemplate"
      responses:
        "201":
          description: SnapshotAnalysis created. SnapshotAnalysis.processingState.status represents the current process' status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SnapshotAnalysis"
    get:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/snapshot-analysis.read
      summary: Search SnapshotAnalysis resources
      operationId: searchSnapshotAnalysis
      tags:
        - Snapshot Analysis
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
        - in: query
          name: pageNumber
          description: 1-indexed page number for the current page.
          required: true
          schema:
            type: integer
        - in: query
          name: pageSize
          description: Size of each page in the results.
          required: true
          schema:
            type: integer
        - in: query
          name: ownerId
          description: Filter results by ownerId. Admins can see all ownerIds, non-admins can only see their own.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: The SnapshotAnalysis resources in the tenant matching pagination query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SnapshotAnalysisSearchResults"
  /snapshotanalysis/{id}:
    get:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/snapshot-analysis.read
      summary: Get SnapshotAnalysis
      operationId: getSnapshotAnalysisById
      tags:
        - Snapshot Analysis
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
        - in: path
          name: id
          description: The ID of the SnapshotAnalysis resource
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The SnapshotAnalysis resources specified by unique id in path
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SnapshotAnalysis"
  /snapshotanalysis/{id}/processingState:
    get:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/snapshot-analysis.read
      summary: Get SnapshotAnalysis processingState
      description: |
        Often used for polling the processingState of the resource to check whether the resource is done processing.
      operationId: getSnapshotAnalysisProcessingState
      tags:
        - Snapshot Analysis
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
        - in: path
          name: id
          description: The ID of the SnapshotAnalysis resource
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Get the ProcessingState of the SnapshotAnalysis
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessingState"
  /signalanalysis/{id}/data:
    get:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/signal-analysis.read
      summary: Get JSON SignalAnalysis data
      operationId: getSignalAnalysisData
      tags:
        - Signal Analysis
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
        - in: path
          name: id
          description: The ID of the Signal Analysis
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The data for a Signal Analysis
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignalData"
            text/csv:
              schema:
                type: string
                format: binary
  /templates/{id}:
    get:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/snapshot-analysis-templates.read
      summary: Get SnapshotAnalysisTemplate
      operationId: getSnapshotAnalysisTemplateById
      tags:
        - Snapshot Analysis
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
        - in: path
          name: id
          description: The ID of the SnapshotAnalysisTemplate resource
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The SnapshotAnalysisTemplate resources specified by unique id in path
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SnapshotAnalysisTemplate"
    put:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/snapshot-analysis-templates.write
      summary: Update SnapshotAnalysisTemplate
      operationId: updateSnapshotAnalysisTemplate
      tags:
        - Snapshot Analysis
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
        - in: path
          name: id
          description: The ID of the SnapshotAnalysisTemplate resource
          required: true
          schema:
            type: string
      requestBody:
        description: The SnapshotAnalysisTemplate data to save
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSnapshotAnalysisTemplate"
      responses:
        "200":
          description: A new SnapshotAnalysisTemplate object that is persisted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SnapshotAnalysisTemplate"
  /templates:
    post:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/snapshot-analysis-templates.write
      summary: Create new SnapshotAnalysisTemplate
      operationId: createNewSnapshotAnalysisTemplate
      tags:
        - Snapshot Analysis
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
      requestBody:
        description: The SnapshotAnalysisTemplate data to save
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSnapshotAnalysisTemplate"
      responses:
        "201":
          description: A new SnapshotAnalysisTemplate object that is persisted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SnapshotAnalysisTemplate"
    get:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/snapshot-analysis-templates.read
      summary: Search SnapshotAnalysisTemplates
      operationId: searchSnapshotAnalysisTemplates
      tags:
        - Snapshot Analysis
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
        - in: query
          name: allQuery
          description: All query for the templates.
          required: false
          schema:
            type: string
        - in: query
          name: pageNumber
          description: 1-indexed page number for the current page.
          required: true
          schema:
            type: integer
        - in: query
          name: pageSize
          description: Size of each page in the results.
          required: true
          schema:
            type: integer
      responses:
        "201":
          description: The SnapshotAnalysisTemplates matching query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SnapshotAnalysisTemplatesSearchResults"
  /snapshotevents/{id}/parameters:
    get:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/snapshot-events.read
      summary: Paginate SnapshotEvent parameters
      operationId: getSnapshotEventParameters
      tags:
        - Snapshots Events
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
        - in: path
          name: id
          description: The ID of the Snapshot Event to query SnapshotParameter(s)
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: The set of SnapshotParameter(s) matching the pagination query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSnapshotParametersResults"
  /signalanalysisexports:
    post:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/signal-analysis-exports.write
      summary: Create SignalAnalysisExport
      description: Creates SignalAnalysisExport resource from a SignalAnalysis reference.
      operationId: createSignalAnalysisExport
      tags:
        - Signal Analysis Exports
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
      requestBody:
        description: |
          Signal analysis ID to export as CSV.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSignalAnalysisExportRequest"
      responses:
        "202":
          description: Export job created (instant, uses existing data)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignalAnalysisExport"
        "400":
          description: Bad request
        "404":
          description: Signal analysis not found
  /signalanalysisexports/{id}/processingState:
    get:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/signal-analysis-exports.read
      summary: Get SignalAnalysisExport processingState
      description: |
        Often used for polling the processingState of the resource to check whether the export job is done processing and the CSV data is ready for download.
      operationId: getSignalAnalysisExportProcessingState
      tags:
        - Signal Analysis Exports
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
        - in: path
          name: id
          description: The ID of the export job
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Get the ProcessingState of the SignalAnalysisExport
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessingState"
        "404":
          description: Export not found
  /signalanalysisexports/{id}/data:
    get:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/signal-analysis-exports.read
      summary: Download SignalAnalysisExport CSV
      description: Streams CSV data for a given SignalAnalysisExport
      operationId: downloadSignalAnalysisExportData
      tags:
        - Signal Analysis Exports
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
        - in: path
          name: id
          description: The ID of the export job
          required: true
          schema:
            type: string
      responses:
        "200":
          description: CSV data ready for download
          content:
            text/csv:
              schema:
                type: string
                format: binary
        "404":
          description: Export not found
        "500":
          description: Export failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignalAnalysisExport"
  /statisticalanalysis:
    post:
      operationId: createStatisticalAnalysis
      summary: Create new StatisticalAnalysis
      tags:
        - Statistics
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
      requestBody:
        description: The information used to create a Statistical Analysis
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateStatisticalAnalysisRequest"
      responses:
        '201':
          description: A new StatisticalAnalysis request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatisticalAnalysis"
  /subsystemanalysis:
    post:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/subsystem-analysis.write
      summary: Create SubsystemAnalysis
      description: |
        Aggregates data for all the signals for a given SnapshotEvent that match the vehicle criteria.
        Internally formulates a SnapshotAnalysis with all the signals for a given SnapshotEvent's subsystem.
        Provide `snapshotCriteria.idSnapshot` in the request; the service will look up the referenced SnapshotEvent and derive the associated subsystem
        to determine which subsystem's signals should be analyzed. Returns SubsystemAnalysis with embedded SnapshotAnalysis. Inside this SnapshotAnalysis is a reference to a SignalAnalysis.
      operationId: createSubsystemAnalysis
      tags:
        - Subsystem Analysis
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
      requestBody:
        description: Criteria to create subsystem analysis. Triggers fresh signal analysis computation (creates new signalAnalysis.id).
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSubsystemAnalysisRequest"
      responses:
        "201":
          description: Subsystem analysis created with reference to a SnapshotAnalysis.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubsystemAnalysis"
        "400":
          description: Bad request
        "403":
          description: Forbidden
        "404":
          description: Snapshot event not found for provided snapshotCriteria.idSnapshot
        "500":
          description: Internal server error
    get:
      security:
        - OAuth2:
            - api://snapshots-rest-api/.default
            - api://snapshots-rest-api/subsystem-analysis.read
      summary: Search SubsystemAnalysis
      description: Paginate SubsystemAnalysis resources
      operationId: searchSubsystemAnalysis
      tags:
        - Subsystem Analysis
      parameters:
        - in: header
          name: tenant-id
          description: The tenant id
          required: true
          schema:
            type: string
        - in: query
          name: pageNumber
          description: 1-indexed page number for the current page.
          required: true
          schema:
            type: integer
        - in: query
          name: pageSize
          description: Size of each page in the results.
          required: true
          schema:
            type: integer
        - in: query
          name: ownerId
          description: Filter results by ownerId. Admins can see all ownerIds, non-admins can only see their own.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: The SubsystemAnalysis resources in the tenant matching pagination query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubsystemAnalysisSearchResults"
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: "https://stackoverflow.com/a/54368785, Client credentials is not available through the swagger-ui"
      flows:
        clientCredentials: # <---- OAuth flow(authorizationCode, implicit, password or clientCredentials)
          tokenUrl: https://login.microsoftonline.com/4ea0a50e-341e-4eb1-9c44-88b724ac50c4/oauth2/v2.0/token
          authorizationUrl: https://login.microsoftonline.com/4ea0a50e-341e-4eb1-9c44-88b724ac50c4/oauth2/v2.0/authorize
          scopes:
            api://snapshots-rest-api/.default: Get the default permissions granted to the client application.
            api://snapshots-rest-api/signal-analysis.read: Create and update Signal Analysis resources
            api://snapshots-rest-api/snapshot-analysis.write: Create new Snapshot Analysis resources from a template
            api://snapshots-rest-api/snapshot-analysis-templates.write: Create new Snapshot Analysis Template resources
            api://snapshots-rest-api/snapshot-analysis-templates.read: Search and query Snapshot Analysis Template resources
            api://snapshots-rest-api/snapshot-events.read: Read data about a Snapshot Event
            api://snapshots-rest-api/signal-analysis-exports.write: Create signal analysis export jobs
            api://snapshots-rest-api/signal-analysis-exports.read: Download export data
            api://snapshots-rest-api/statisticalanalysis.write: Create new StatisticalAnalysis resources
            api://snapshots-rest-api/subsystem-analysis.write: Create new SubsystemAnalysis resources
            api://snapshots-rest-api/subsystem-analysis.read: Read and search SubsystemAnalysis resources
  schemas:
    CreateSnapshotAnalysisTemplate:
      type: object
      required:
        - template
      properties:
        template:
          $ref: "#/components/schemas/SnapshotAnalysisTemplate"
    SnapshotAnalysisTemplatesSearchResults:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SnapshotAnalysisTemplate"
        pagination:
          $ref: "#/components/schemas/SearchPagination"
    SearchSnapshotParametersResults:
      type: object
      required:
        - parameters
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SnapshotParameter"
    SnapshotParameter:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          description: Unique key within the tenant for the Parameter
          format: int64
        name:
          description: The name of the parameter.
          type: string
    SearchPagination:
      type: object
      required:
        - pageCount
        - pageNumber
        - pageSize
        - totalCount
      properties:
        pageCount:
          type: integer
          format: int32
        pageNumber:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        totalCount:
          type: integer
          format: int32
    SnapshotAnalysisSearchResults:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SnapshotAnalysis"
        pagination:
          $ref: "#/components/schemas/SearchPagination"
    SnapshotAnalysis:
      type: object
      description: |
        A composition of a SnapshotAnalysisTemplate and a SignalAnalysis. 
        The template defines the analysis structure, and the SignalAnalysis contains **already computed data** 
        from the template (no reprocessing). Use signalAnalysis.id for CSV exports - it references existing 
        template data that was already loaded.
      required:
        - id
        - template
        - processingState
      properties:
        id:
          type: string
        template:
          $ref: "#/components/schemas/SnapshotAnalysisTemplate"
        signalAnalysis:
          $ref: "#/components/schemas/SignalAnalysis"
        processingState:
          $ref: "#/components/schemas/ProcessingState"
    ProcessingState:
      type: object
      description: "The processing status of a SnapshotAnalysis or SignalAnalysis. Since SnapshotAnalysis created from templates use existing data, they should typically be 'done' upon creation."
      required:
        - status
        - errorMessage
      properties:
        status:
          type: string
          enum: [submitted, pending, done, error]
          description: "The current processing status. 'submitted' means the SnapshotAnalysis request has been received but not yet processed. 'pending' means processing is underway. 'done' means processing is complete and data is ready. 'error' means there was an error during processing."
        errorMessage:
          type: string
          description: "If status == error, this field contains details about the error, else value will be N/A"
    SnapshotAnalysisTemplate:
      type: object
      description: An object to organize criteria and charts for a SnapshotSignalAnalysis
      required:
        - id
        - name
        - public
        - signalExpressions
        - sections
        - criteria
      properties:
        id:
          type: string
          description: "Empty string means there is no resource persisted but the model can still be used"
        name:
          type: string
        public:
          type: boolean
          description: "Whether or not the template is public and other users are allowed to use it."
        signalExpressions:
          $ref: "#/components/schemas/SignalExpressions"
        sections:
          description: "An array of SnapshotAnalysisSection objects, each one holds charting information"
          type: array
          items:
            $ref: "#/components/schemas/SnapshotAnalysisSection"
        criteria:
          $ref: "#/components/schemas/SnapshotAnalysisCriteria"
        createdBy:
          type: string
          nullable: true
        lastUpdate:
          type: integer
          format: int64
          nullable: true
        subsystem:
          type: string
          description: "The subsystem associated with the template."
    SnapshotAnalysisSection:
      type: object
      required:
        - name
        - singleChart
        - xAxis
        - yAxis
      properties:
        name:
          type: string
        singleChart:
          type: boolean
        xAxis:
          type: object
          required:
            - timestamp
          properties:
            timestamp:
              type: boolean
              description: "Whether to use epochMs in the data as the values for the x-axis or not"
            parameter:
              $ref: "#/components/schemas/Parameter"
        yAxis:
          type: array
          description: "A set of expression keys designated to the right axis of this chart."
          items:
            $ref: "#/components/schemas/YAxis"
    YAxis:
      type: object
      required:
        - chartType
        - parameter
        - isLeft
      properties:
        chartType:
          type: string
          enum: [histogram, scatter, line]
          example: scatter
        parameter:
          $ref: "#/components/schemas/Parameter"
        isLeft:
          type: boolean
    Parameter:
      type: object
      required:
        - snapshotParameter
      properties:
        snapshotParameter:
          $ref: "#/components/schemas/SnapshotParameter"
        signalValueKey:
          description: Calculated value mapping to expression key of the signal analysis data.
          type: string
    SnapshotAnalysisCriteria:
      type: object
      description: "The Criteria the processes will filter Snapshot Data on when creating a new SnapshotAnalysis resource"
      required:
        - vehicleCriteria
        - snapshotCriteria
      properties:
        vehicleCriteria:
          $ref: "#/components/schemas/VehicleCriteria"
        snapshotCriteria:
          $ref: "#/components/schemas/SnapshotCriteria"
    SnapshotCriteria:
      type: object
      required:
        - idSnapshot
        - minEpochMs
        - maxEpochMs
      properties:
        idSnapshot:
          description: idEvent of the SnapshotEvent resource
          type: integer
          format: int64
        minEpochMs:
          type: integer
          format: int64
        maxEpochMs:
          type: integer
          format: int64
    VehicleCriteria:
      type: object
      required:
        - idPackages
        - idVins
        - fleets
      properties:
        idPackages:
          type: array
          items:
            type: integer
            format: int64
        idVins:
          type: array
          items:
            type: integer
            format: int64
        fleets:
          type: array
          items:
            type: string
    SignalAnalysis:
      type: object
      description: |
        Holds SignalExpressions and related computed data.
      required:
        - id
        - name
        - ownerId
        - publicFlag
        - processingState
        - signalExpressions
      properties:
        id:
          type: string
          description: |
            Unique identifier for the signal analysis.
        name:
          type: string
        ownerId:
          type: string
        publicFlag:
          type: boolean
        processingState:
          $ref: "#/components/schemas/ProcessingState"
        signalExpressions:
          $ref: "#/components/schemas/SignalExpressions"
    SignalExpressions:
      type: object
      required:
        - expressions
      properties:
        expressions:
          description: "Expressions to create SignalData"
          example:
            [
              { key: "s1", name: "signal1", expression: "c1" },
              { key: "s2", name: "signal2", expression: "c2" },
            ]
          type: array
          items:
            $ref: "#/components/schemas/SignalExpression"
    SignalExpression:
      type: object
      description: "A keyed expression used to model an expression to be evaluated against a frame of SignalData"
      required:
        - key
        - name
        - expression
      properties:
        key:
          type: string
          example: "s1"
        name:
          type: string
          example: "parameter 1"
        expression:
          type: string
          example: "c123"
    SignalData:
      type: object
      description: "An aggregation of SignalSnapshot objects which contain Signals and their evaluated expressions, with separate vehicle metadata lookup"
      required:
        - signalAnalysis
        - error
        - data
      properties:
        signalAnalysis:
          $ref: "#/components/schemas/SignalAnalysis"
        data:
          type: array
          description: "Array of signal snapshots"
          items:
            $ref: "#/components/schemas/SignalSnapshot"
        error:
          type: string
          description: "If error == EOF, That means all the data from the stream was processed properly and there isn't any error"
        vehicleMetadata:
          type: object
          description: "Map of idVin (as string keys) to vehicle metadata objects - use snapshot.idVin to lookup vehicle details"
          additionalProperties:
            $ref: "#/components/schemas/VehicleMetadata"
    SignalSnapshot:
      type: object
      description: "A single frame of data that contains SignalValues. Use idVin to lookup vehicle metadata from the separate vehicleMetadata map."
      required:
        - idFile
        - idVin
        - idPackage
        - epochMs
        - idTrip
        - signalValues
      properties:
        idFile:
          type: integer
          format: int64
        idVin:
          type: integer
          format: int64
        idPackage:
          type: integer
          format: int64
        epochMs:
          type: integer
          format: int64
        idTrip:
          type: integer
          format: int64
        signalValues:
          type: object
          example:
            {
              "c1":
                {
                  "key": "c1",
                  "dataType": "f",
                  "doubleValue": 1.2938,
                  "stringValue": "",
                },
              "s1":
                {
                  "key": "s1",
                  "dataType": "f",
                  "doubleValue": 1.28,
                  "stringValue": "",
                },
            }
          additionalProperties:
            $ref: "#/components/schemas/SignalValue"
    SignalValue:
      type: object
      description: "Hold a single Signal value that can be of type string or double. dataType enum defines what property the value exists in."
      required:
        - key
        - dataType
        - doubleValue
        - stringValue
      properties:
        key:
          type: string
        dataType:
          type: string
          enum: [f, s]
        doubleValue:
          type: number
          format: double
        stringValue:
          type: string
    VehicleMetadata:
      type: object
      description: Vehicle metadata fields from Vehicle API
      properties:
        idVin:
          type: integer
          format: int64
          description: The vehicle idVin (also used as CSV column "vin")
        vehNo:
          type: string
        timeStamp:
          type: integer
          format: int64
        location:
          type: string
        ecmCalibration:
          type: string
        tcmCalibration:
          type: string
        engine:
          type: string
        body:
          type: string
        trans:
          type: string
        dlVersion:
          type: string
        idConfig:
          type: integer
          format: int64
        idEvent:
          type: integer
          format: int64
        timeStampGmt:
          type: integer
          format: int64
      example:
        "12345":
          vehNo: "VEH001"
          location: "Detroit"
          engine: "V8"
          ecmCalibration: "ECM_V1.2"
        "67890":
          vehNo: "VEH002"
          location: "Shanghai"
          engine: "I4"
    CreateSubsystemAnalysisRequest:
      type: object
      description: Request to create a new SubsystemAnalysis
      required:
        - snapshotCriteria
        - vehicleCriteria
      properties:
        snapshotCriteria:
          $ref: "#/components/schemas/SnapshotCriteria"
        vehicleCriteria:
          $ref: "#/components/schemas/VehicleCriteria"
    SubsystemAnalysisSearchResults:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SubsystemAnalysis"
        pagination:
          $ref: "#/components/schemas/SearchPagination"
    SubsystemAnalysis:
      type: object
      description: |
        Contains a reference to a SnapshotAnalysis. The SnapshotAnalysis includes all signals for a given subsystem defined as input when creating the SubsystemAnalysis.
      required:
        - id
        - snapshotAnalysisId
      properties:
        id:
          nullable: false
          type: string
          description: Unique identifier for subsystem analysis
        snapshotAnalysisId:
          nullable: false
          type: string
          description: ID of the referenced SnapshotAnalysis
    CreateSignalAnalysisExportRequest:
      type: object
      description: |
        Request to create CSV export from existing signal analysis.
      required:
        - signalAnalysisId
      properties:
        signalAnalysisId:
          nullable: false
          type: string
          description: |
            ID of existing signal analysis to export as CSV. 
    SignalAnalysisExport:
      type: object
      description: CSV export job resource representing an export of a SignalAnalysis
      required:
        - id
        - signalAnalysisId
        - processingState
        - tenantId
        - ownerId
        - createdAt
      properties:
        id:
          nullable: false
          type: string
          description: Unique identifier for the export job
        signalAnalysisId:
          nullable: false
          type: string
          description: ID of the signal analysis being exported
        tenantId:
          nullable: false
          type: integer
          format: int64
          description: Tenant ID
        ownerId:
          nullable: false
          type: string
          description: Owner ID
        createdAt:
          nullable: false
          type: string
          format: date-time
          description: Creation timestamp
        processingState:
          $ref: "#/components/schemas/ProcessingState"
        csvDownloadUrl:
          type: string
          format: uri
          description: URL to download the CSV file
          example: "/signalanalysisexports/abc123/data"
          nullable: true
    CreateStatisticalAnalysisRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Datapoint"
        thresholds:
          type: array
          items:
            $ref: "#/components/schemas/Threshold"
    Threshold:
      type: object
      required:
        - limit
      properties:
        limit:
          nullable: false
          type: number
          format: double
    Datapoint:
      type: object
      required:
        - value
      properties:
        value:
          nullable: false
          type: number
          format: double
    StatisticalAnalysis:
      type: object
      required:
        - transformations
      properties:
        transformations:
          nullable: false
          type: object
          additionalProperties:
            $ref: "#/components/schemas/Transformation"
    Transformation:
      type: object
      required:
        - andersonDarling
        - stats
        - cpks
      properties:
        andersonDarling:
          $ref: "#/components/schemas/AndersonDarlingResult"  
        statistics:
          $ref: '#/components/schemas/Statistics'
        cpks:
          nullable: false
          type: array
          items:
            $ref: '#/components/schemas/Cpk'
    AndersonDarlingResult:
      type: object
      required:
        - processingError
        - statistic
        - pValue
      properties:
        processingError:
          nullable: false
          type: string
        statistic:
          nullable: false
          type: number
          format: double
        pValue:
          nullable: false
          type: number
          format: double  
    Statistics:
      type: object
      description: Calculated statistical data about a dataset.
      required:
        - count
        - minValue
        - maxValue
        - avg
        - sum
        - standardVariation
        - standardDeviation
      properties:
        count:
          nullable: false
          type: number
          format: double
        minValue:
          nullable: false
          type: number
          format: double
        maxValue:
          nullable: false
          type: number
          format: double
        avg:
          nullable: false
          type: number
          format: double
        sum:
          nullable: false
          type: number
          format: double
        standardVariation:
          nullable: false
          type: number
          format: double
        standardDeviation:
          nullable: false
          type: number
          format: double
    Cpk:
      type: object
      description: The calculated CPK value based on the limit and statistics provided
      required:
        - threshold
        - value
      properties:
        threshold:
          $ref: '#/components/schemas/Threshold'
        value:
          nullable: false
          type: number
          format: double
    ErrorMessage:
      type: object
      required:
        - message
      properties:
        message:
          type: string
