asyncapi: 3.0.0
info:
  title: 3S-API Websocket API
  description: |
    ## Overview
    This API provides real-time communication capabilities for Smart Screen Apps with the 3S-API via a websocket connection.
    It follows the CloudEvents v1.0 specification for message envelope structure and uses
    XRN (eXtended Resource Name) identifiers for source, subject, and type attributes.
    
    ## Siemens Xcelerator X Conformance
    This API is designed to be **Siemens Xcelerator X** conform and follows the asynchronous messaging 
    design guidelines specified by Siemens. The API adheres to the CloudEvents v1.0 specification 
    for message envelope structure and implements the required MUST attributes as defined in the 
    Siemens Xcelerator API Guidelines.
    
    For more information about the Siemens Xcelerator X API Guidelines for asynchronous messaging, 
    see: https://xcelerator.code.siemens.io/api-guidelines/async/site-public/index.html
    
    ## Message Flow
    1. Client connects to WebSocket endpoint
    2. Client sends authentication request with JWT token
    3. 3S-API responds with authentication result
    4. Client subscribes to desired attributes
    5. 3S-API sends events when subscribed attributes change
    6. Client can unsubscribe from attributes at any time
    
    ## CloudEvents Compliance
    All messages conform to CloudEvents v1.0 specification with the following XRN formats:
    - **Source**: `xrn:ces:<namespace>:<source>` - Identifies the message producer
    - **Type (Events)**: `xrn:cet:<namespace>:<resource>.<pastTenseVerb>` - Describes what happened
    - **Type (Commands)**: `xrn:cec:<namespace>:<resource>.<imperativeVerb>` - Describes requested action
  version: 1.0.0
  license:
    name: Proprietary
  contact:
    name: 3S-API Development Team

defaultContentType: application/json
servers:
  3sapi:
    host: "localhost:31913"
    pathname: /vss/3s-api/v1
    protocol: ws
    description: |
      Local development WebSocket server for 3S-API.
      In production, this endpoint is provided by the train's onboard system.
channels:
  authenticationRequestChannel:
    address: authenticationRequestChannel
    messages:
      authenticationRequest.message:
        $ref: "#/components/messages/authenticationRequest"
    description: |
      Channel for client authentication requests.
      The client must send a valid JWT token to authenticate before accessing other features.
  authenticationResponseChannel:
    address: authenticationResponseChannel
    messages:
      authenticationResponse.message:
        $ref: "#/components/messages/authenticationResponse"
    description: |
      Channel for authentication response messages.
      The 3S-API responds with the authentication result indicating success or failure reason.
  subscriptionRequestChannel:
    address: subscriptionRequestChannel
    messages:
      subscriptionRequest.message:
        $ref: "#/components/messages/subscriptionRequest"
    description: |
      Channel for subscription requests.
      Authenticated clients can subscribe to specific train attributes to receive real-time updates.
  subscriptionResponseChannel:
    address: subscriptionResponseChannel
    messages:
      subscriptionResponse.message:
        $ref: "#/components/messages/subscriptionResponse"
    description: |
      Channel for subscription response messages.
      The 3S-API confirms or rejects the subscription request.
  unsubscriptionRequestChannel:
    address: unsubscriptionRequestChannel
    messages:
      unsubscriptionRequest.message:
        $ref: "#/components/messages/unsubscriptionRequest"
    description: |
      Channel for unsubscription requests.
      Clients can stop receiving updates for specific attributes by unsubscribing.
  unsubscriptionResponseChannel:
    address: unsubscriptionResponseChannel
    messages:
      unsubscriptionResponse.message:
        $ref: "#/components/messages/unsubscriptionResponse"
    description: |
      Channel for unsubscription response messages.
      The 3S-API confirms or rejects the unsubscription request.
  eventChannel:
    address: eventChannel
    messages:
      event.message:
        $ref: "#/components/messages/event"
    description: |
      Channel for real-time attribute change events.
      The 3S-API pushes updates to subscribed clients whenever monitored attributes change.
  errorChannel:
    address: errorChannel
    messages:
      error.message:
        $ref: "#/components/messages/error"
    description: |
      Channel for error messages.
      The 3S-API sends error notifications when it cannot process a client request.
operations:
  authenticationRequest:
    action: send
    channel:
      $ref: "#/channels/authenticationRequestChannel"
    messages:
      - $ref: "#/channels/authenticationRequestChannel/messages/authenticationRequest.message"
    summary: Send authentication request
    description: |
      Client sends a JWT token to authenticate with the 3S-API.
      This must be the first message sent after establishing the WebSocket connection.
      The JWT token should be obtained from the identity provider (e.g., Keycloak).
  authenticationResponse:
    action: receive
    channel:
      $ref: "#/channels/authenticationResponseChannel"
    messages:
      - $ref: "#/channels/authenticationResponseChannel/messages/authenticationResponse.message"
    summary: Receive authentication response
    description: |
      3S-API responds to the authentication request with the result.
      On success, the client can proceed to subscribe to attributes.
      On failure, the response type indicates the reason (notAuthorized, badRequest, failed).
  subscriptionRequest:
    action: send
    channel:
      $ref: "#/channels/subscriptionRequestChannel"
    messages:
      - $ref: "#/channels/subscriptionRequestChannel/messages/subscriptionRequest.message"
    summary: Subscribe to attributes
    description: |
      Client requests to subscribe to one or more train attributes.
      Only authenticated clients can subscribe to attributes.
      The client will receive events whenever subscribed attributes change.
  subscriptionResponse:
    action: receive
    channel:
      $ref: "#/channels/subscriptionResponseChannel"
    messages:
      - $ref: "#/channels/subscriptionResponseChannel/messages/subscriptionResponse.message"
    summary: Receive subscription response
    description: |
      3S-API responds to the subscription request with the result.
      On success, the client will start receiving events for the subscribed attributes.
      On failure, the response type indicates the reason.
  unsubscriptionRequest:
    action: send
    channel:
      $ref: "#/channels/unsubscriptionRequestChannel"
    messages:
      - $ref: "#/channels/unsubscriptionRequestChannel/messages/unsubscriptionRequest.message"
    summary: Unsubscribe from attributes
    description: |
      Client requests to unsubscribe from one or more previously subscribed attributes.
      After successful unsubscription, the client will no longer receive events for those attributes.
  unsubscriptionResponse:
    action: receive
    channel:
      $ref: "#/channels/unsubscriptionResponseChannel"
    messages:
      - $ref: "#/channels/unsubscriptionResponseChannel/messages/unsubscriptionResponse.message"
    summary: Receive unsubscription response
    description: |
      3S-API responds to the unsubscription request with the result.
      On success, the client will stop receiving events for the unsubscribed attributes.
  event:
    action: receive
    channel:
      $ref: "#/channels/eventChannel"
    messages:
      - $ref: "#/channels/eventChannel/messages/event.message"
    summary: Receive attribute change events
    description: |
      3S-API pushes real-time events to the client when subscribed attributes change.
      The event payload contains the current values of the changed attributes.
      Events are only sent for attributes the client has subscribed to.
  error:
    action: receive
    channel:
      $ref: "#/channels/errorChannel"
    messages:
      - $ref: "#/channels/errorChannel/messages/error.message"
    summary: Receive error notifications
    description: |
      3S-API sends error messages when it cannot process a client request.
      The correlationid links the error to the original request that caused it.
      The error message provides details about what went wrong.
components:
  schemas:
    authenticationRequestPayload:
      type: object
      description: |
        CloudEvents-compliant authentication request payload.
        Used by clients to authenticate with the 3S-API using a JWT token.
      required:
        - id
        - source
        - specversion
        - type
        - time
        - version
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier for this request (UUIDv4). Used for correlation with responses."
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        source:
          type: string
          const: "xrn:ces:siemens:3sapi.global.default"
          pattern: "^xrn:ces:[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents source identifier in XRN format. Identifies the message producer context."
        specversion:
          type: string
          const: "1.0"
          description: "CloudEvents specification version. Must be '1.0' for CloudEvents v1.0 compliance."
        type:
          type: string
          const: "xrn:cec:siemens3sapi:authentication.authenticate"
          pattern: "^xrn:(cet|cec):[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents type in XRN command format. Indicates this is an authentication command."
        version:
          type: string
          const: "1.0.0"
          description: "3S-API envelope specification version."
        datacontenttype:
          type: string
          const: "application/json"
          description: "Content type of the data value."
        time:
          type: string
          format: date-time
          description: "RFC3339 timestamp indicating when this request was created. Should use UTC timezone."
          example: "2023-10-05T14:48:00Z"
        subject:
          type: string
          description: "CloudEvents subject - identifies the subject of the event in the context of the producer."
          example: "authentication"
        dataschema:
          type: string
          format: uri
          description: "CloudEvents dataschema - URI reference identifying the schema that data adheres to."
          example: "https://siemens.com/3sapi/v1/schemas/authenticationRequest"
        data:
          type: object
          description: "Request-specific data containing the authentication credentials."
          required:
            - data
          additionalProperties: false
          properties:
            data:
              type: object
              description: "JSON:API resource object describing the authentication request."
              required:
                - id
                - type
                - attributes
              additionalProperties: false
              properties:
                id:
                  type: string
                  format: uuid
                  description: "JSON:API resource identifier (UUIDv4)."
                  example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                type:
                  type: string
                  const: "authenticationRequest"
                  description: "JSON:API resource type."
                attributes:
                  type: object
                  description: "JSON:API resource attributes containing the authentication credentials."
                  required:
                    - jwt
                  additionalProperties: false
                  properties:
                    jwt:
                      type: string
                      description: "JSON Web Token obtained from the identity provider (e.g., Keycloak) for authentication."
                      example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    authenticationResponsePayload:
      type: object
      description: |
        CloudEvents-compliant authentication response payload.
        Sent by the 3S-API to indicate the result of an authentication request.
      required:
        - id
        - source
        - specversion
        - type
        - time
        - version
        - correlationid
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier for this response (UUIDv4)."
          example: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
        source:
          type: string
          pattern: "^xrn:ces:[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents source identifier in XRN format (xrn:ces:...). Identifies the 3S-API instance that processed the request."
          example: "xrn:ces:siemens:3sapi.global.default"
        specversion:
          type: string
          const: "1.0"
          description: "CloudEvents specification version. Always '1.0'."
        type:
          type: string
          pattern: "^xrn:(cet|cec):[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents type indicating the authentication result. The type suffix indicates success or failure reason."
          enum:
            - "xrn:cet:siemens3sapi:authentication.succeeded"
            - "xrn:cet:siemens3sapi:authentication.notAuthorized"
            - "xrn:cet:siemens3sapi:authentication.badRequest"
            - "xrn:cet:siemens3sapi:authentication.failed"
        version:
          type: string
          const: "1.0.0"
          description: "3S-API envelope specification version."
        datacontenttype:
          type: string
          const: "application/json"
          description: "Content type of the data value."
        time:
          type: string
          format: date-time
          description: "RFC3339 timestamp indicating when this response was created."
          example: "2023-10-05T14:48:01Z"
        subject:
          type: string
          description: "CloudEvents subject - identifies the subject of the event in the context of the producer."
          example: "authentication"
        dataschema:
          type: string
          format: uri
          description: "CloudEvents dataschema - URI reference identifying the schema that data adheres to."
          example: "https://siemens.com/3sapi/v1/schemas/authenticationResponse"
        correlationid:
          type: string
          format: uuid
          description: "The id of the original request. Used to correlate this response with its request."
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        data:
          type: object
          description: "Response-specific data containing additional information."
          additionalProperties: false
          properties:
            data:
              type: object
              description: "JSON:API resource object describing the authentication response."
              required:
                - id
                - type
              additionalProperties: false
              properties:
                id:
                  type: string
                  format: uuid
                  description: "JSON:API resource identifier (UUIDv4)."
                  example: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
                type:
                  type: string
                  const: "authenticationResponse"
                  description: "JSON:API resource type."
                attributes:
                  type: object
                  description: "JSON:API resource attributes containing the response details."
                  additionalProperties: false
                  properties:
                    message:
                      type: string
                      description: "Human-readable message providing additional details about the authentication result."
                      example: "Authentication successful"
    subscriptionRequestPayload:
      type: object
      description: |
        CloudEvents-compliant subscription request payload.
        Used by authenticated clients to subscribe to train attribute updates.
      required:
        - id
        - source
        - specversion
        - type
        - time
        - version
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier for this request (UUIDv4). Used for correlation with responses."
          example: "c3d4e5f6-a7b8-9012-cdef-345678901234"
        source:
          type: string
          const: "xrn:ces:siemens:3sapi.global.default"
          pattern: "^xrn:ces:[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents source identifier in XRN format."
        specversion:
          type: string
          const: "1.0"
          description: "CloudEvents specification version."
        type:
          type: string
          const: "xrn:cec:siemens3sapi:subscription.subscribe"
          pattern: "^xrn:(cet|cec):[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents type in XRN command format. Indicates this is a subscription command."
        version:
          type: string
          const: "1.0.0"
          description: "3S-API envelope specification version."
        datacontenttype:
          type: string
          const: "application/json"
          description: "Content type of the data value."
        time:
          type: string
          format: date-time
          description: "RFC3339 timestamp indicating when this request was created."
          example: "2023-10-05T14:48:02Z"
        subject:
          type: string
          description: "CloudEvents subject - identifies the subject of the event in the context of the producer."
          example: "subscription"
        dataschema:
          type: string
          format: uri
          description: "CloudEvents dataschema - URI reference identifying the schema that data adheres to."
          example: "https://siemens.com/3sapi/v1/schemas/subscriptionRequest"
        data:
          type: object
          description: "Request-specific data containing the attributes to subscribe to."
          required:
            - data
          additionalProperties: false
          properties:
            data:
              type: object
              description: "JSON:API resource object describing the subscription request."
              required:
                - id
                - type
                - attributes
              additionalProperties: false
              properties:
                id:
                  type: string
                  format: uuid
                  description: "JSON:API resource identifier (UUIDv4)."
                  example: "c3d4e5f6-a7b8-9012-cdef-345678901234"
                type:
                  type: string
                  const: "subscriptionRequest"
                  description: "JSON:API resource type."
                attributes:
                  type: object
                  description: "JSON:API resource attributes containing the attribute names to subscribe to."
                  required:
                    - attributeNames
                  additionalProperties: false
                  properties:
                    attributeNames:
                      type: array
                      description: "List of attribute names to subscribe to. See API documentation for available attributes."
                      items:
                        type: string
                        description: "Name of a train attribute (e.g., 'currentSpeed', 'tractionEnergy')."
                      example: ["currentSpeed", "tractionEnergy", "edBrakeEnergy"]
    subscriptionResponsePayload:
      type: object
      description: |
        CloudEvents-compliant subscription response payload.
        Sent by the 3S-API to indicate the result of a subscription request.
      required:
        - id
        - source
        - specversion
        - type
        - time
        - version
        - correlationid
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier for this response (UUIDv4)."
          example: "d4e5f6a7-b8c9-0123-def4-567890123456"
        source:
          type: string
          pattern: "^xrn:ces:[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents source identifier in XRN format."
          example: "xrn:ces:siemens:3sapi.global.default"
        specversion:
          type: string
          const: "1.0"
          description: "CloudEvents specification version."
        type:
          type: string
          pattern: "^xrn:(cet|cec):[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents type indicating the subscription result."
          enum:
            - "xrn:cet:siemens3sapi:subscription.succeeded"
            - "xrn:cet:siemens3sapi:subscription.notAuthorized"
            - "xrn:cet:siemens3sapi:subscription.notAllowed"
            - "xrn:cet:siemens3sapi:subscription.badRequest"
            - "xrn:cet:siemens3sapi:subscription.failed"
        version:
          type: string
          const: "1.0.0"
          description: "3S-API envelope specification version."
        datacontenttype:
          type: string
          const: "application/json"
          description: "Content type of the data value."
        time:
          type: string
          format: date-time
          description: "RFC3339 timestamp indicating when this response was created."
          example: "2023-10-05T14:48:03Z"
        subject:
          type: string
          description: "CloudEvents subject - identifies the subject of the event in the context of the producer."
          example: "subscription"
        dataschema:
          type: string
          format: uri
          description: "CloudEvents dataschema - URI reference identifying the schema that data adheres to."
          example: "https://siemens.com/3sapi/v1/schemas/subscriptionResponse"
        correlationid:
          type: string
          format: uuid
          description: "The id of the original subscription request."
          example: "c3d4e5f6-a7b8-9012-cdef-345678901234"
        data:
          type: object
          description: "Response-specific data."
          additionalProperties: false
          properties:
            data:
              type: object
              description: "JSON:API resource object describing the subscription response."
              required:
                - id
                - type
              additionalProperties: false
              properties:
                id:
                  type: string
                  format: uuid
                  description: "JSON:API resource identifier (UUIDv4)."
                  example: "d4e5f6a7-b8c9-0123-def4-567890123456"
                type:
                  type: string
                  const: "subscriptionResponse"
                  description: "JSON:API resource type."
                attributes:
                  type: object
                  description: "JSON:API resource attributes containing the response details."
                  additionalProperties: false
                  properties:
                    message:
                      type: string
                      description: "Human-readable message about the subscription result."
                      example: "Subscription successful"
    unsubscriptionRequestPayload:
      type: object
      description: |
        CloudEvents-compliant unsubscription request payload.
        Used by clients to stop receiving updates for specific attributes.
      required:
        - id
        - source
        - specversion
        - type
        - time
        - version
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier for this request (UUIDv4)."
          example: "e5f6a7b8-c9d0-1234-ef56-789012345678"
        source:
          type: string
          const: "xrn:ces:siemens:3sapi.global.default"
          pattern: "^xrn:ces:[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents source identifier in XRN format."
        specversion:
          type: string
          const: "1.0"
          description: "CloudEvents specification version."
        type:
          type: string
          const: "xrn:cec:siemens3sapi:unsubscription.unsubscribe"
          pattern: "^xrn:(cet|cec):[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents type in XRN command format. Indicates this is an unsubscription command."
        version:
          type: string
          const: "1.0.0"
          description: "3S-API envelope specification version."
        datacontenttype:
          type: string
          const: "application/json"
          description: "Content type of the data value."
        time:
          type: string
          format: date-time
          description: "RFC3339 timestamp indicating when this request was created."
          example: "2023-10-05T14:48:04Z"
        subject:
          type: string
          description: "CloudEvents subject - identifies the subject of the event in the context of the producer."
          example: "unsubscription"
        dataschema:
          type: string
          format: uri
          description: "CloudEvents dataschema - URI reference identifying the schema that data adheres to."
          example: "https://siemens.com/3sapi/v1/schemas/unsubscriptionRequest"
        data:
          type: object
          description: "Request-specific data containing the attributes to unsubscribe from."
          required:
            - data
          additionalProperties: false
          properties:
            data:
              type: object
              description: "JSON:API resource object describing the unsubscription request."
              required:
                - id
                - type
                - attributes
              additionalProperties: false
              properties:
                id:
                  type: string
                  format: uuid
                  description: "JSON:API resource identifier (UUIDv4)."
                  example: "e5f6a7b8-c9d0-1234-ef56-789012345678"
                type:
                  type: string
                  const: "unsubscriptionRequest"
                  description: "JSON:API resource type."
                attributes:
                  type: object
                  description: "JSON:API resource attributes containing the attribute names to unsubscribe from."
                  required:
                    - attributeNames
                  additionalProperties: false
                  properties:
                    attributeNames:
                      type: array
                      description: "List of attribute names to unsubscribe from."
                      items:
                        type: string
                        description: "Name of a previously subscribed attribute."
                      example: ["currentSpeed", "tractionEnergy"]
    unsubscriptionResponsePayload:
      type: object
      description: |
        CloudEvents-compliant unsubscription response payload.
        Sent by the 3S-API to indicate the result of an unsubscription request.
      required:
        - id
        - source
        - specversion
        - type
        - time
        - version
        - correlationid
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier for this response (UUIDv4)."
          example: "f6a7b8c9-d0e1-2345-f678-901234567890"
        source:
          type: string
          pattern: "^xrn:ces:[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents source identifier in XRN format."
          example: "xrn:ces:siemens:3sapi.global.default"
        specversion:
          type: string
          const: "1.0"
          description: "CloudEvents specification version."
        type:
          type: string
          pattern: "^xrn:(cet|cec):[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents type indicating the unsubscription result."
          enum:
            - "xrn:cet:siemens3sapi:unsubscription.succeeded"
            - "xrn:cet:siemens3sapi:unsubscription.notAuthorized"
            - "xrn:cet:siemens3sapi:unsubscription.notAllowed"
            - "xrn:cet:siemens3sapi:unsubscription.badRequest"
            - "xrn:cet:siemens3sapi:unsubscription.failed"
        version:
          type: string
          const: "1.0.0"
          description: "3S-API envelope specification version."
        datacontenttype:
          type: string
          const: "application/json"
          description: "Content type of the data value."
        time:
          type: string
          format: date-time
          description: "RFC3339 timestamp indicating when this response was created."
          example: "2023-10-05T14:48:05Z"
        subject:
          type: string
          description: "CloudEvents subject - identifies the subject of the event in the context of the producer."
          example: "unsubscription"
        dataschema:
          type: string
          format: uri
          description: "CloudEvents dataschema - URI reference identifying the schema that data adheres to."
          example: "https://siemens.com/3sapi/v1/schemas/unsubscriptionResponse"
        correlationid:
          type: string
          format: uuid
          description: "The id of the original unsubscription request."
          example: "e5f6a7b8-c9d0-1234-ef56-789012345678"
        data:
          type: object
          description: "Response-specific data."
          additionalProperties: false
          properties:
            data:
              type: object
              description: "JSON:API resource object describing the unsubscription response."
              required:
                - id
                - type
              additionalProperties: false
              properties:
                id:
                  type: string
                  format: uuid
                  description: "JSON:API resource identifier (UUIDv4)."
                  example: "f6a7b8c9-d0e1-2345-f678-901234567890"
                type:
                  type: string
                  const: "unsubscriptionResponse"
                  description: "JSON:API resource type."
                attributes:
                  type: object
                  description: "JSON:API resource attributes containing the response details."
                  additionalProperties: false
                  properties:
                    message:
                      type: string
                      description: "Human-readable message about the unsubscription result."
                      example: "Unsubscription successful"
    eventPayload:
      type: object
      description: |
        CloudEvents-compliant event payload for attribute changes.
        Sent by the 3S-API when subscribed train attributes change their values.
      required:
        - id
        - source
        - specversion
        - type
        - time
        - version
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier for this event (UUIDv4)."
          example: "c4f6b3a8-7e0b-4f2c-9d1f-cc6de2d2a3a1"
        source:
          type: string
          const: "xrn:ces:siemens:3sapi.global.default"
          pattern: "^xrn:ces:[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents source identifier in XRN format."
        specversion:
          type: string
          const: "1.0"
          description: "CloudEvents specification version."
        type:
          type: string
          const: "xrn:cet:siemens3sapi:attributes.changed"
          pattern: "^xrn:(cet|cec):[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents type in XRN event format. Indicates attribute values have changed."
        version:
          type: string
          const: "1.0.0"
          description: "3S-API envelope specification version."
        datacontenttype:
          type: string
          const: "application/json"
          description: "Content type of the data value."
        time:
          type: string
          format: date-time
          description: "RFC3339 timestamp indicating when the attribute change occurred."
          example: "2023-10-05T14:48:00Z"
        subject:
          type: string
          description: "CloudEvents subject - identifies the subject of the event in the context of the producer."
          example: "attributes"
        dataschema:
          type: string
          format: uri
          description: "CloudEvents dataschema - URI reference identifying the schema that data adheres to."
          example: "https://siemens.com/3sapi/v1/schemas/attributeChangeEvent"
        data:
          type: object
          description: "Event-specific data."
          additionalProperties: false
          properties:
            data:
              type: object
              description: "JSON:API resource object describing the attribute change event."
              required:
                - id
                - type
              additionalProperties: false
              properties:
                id:
                  type: string
                  format: uuid
                  description: "JSON:API resource identifier (UUIDv4)."
                  example: "c4f6b3a8-7e0b-4f2c-9d1f-cc6de2d2a3a1"
                type:
                  type: string
                  const: "attributeChangeEvent"
                  description: "JSON:API resource type."
                attributes:
                  type: object
                  additionalProperties: true
                  description: |
                    JSON:API resource attributes containing the changed attribute values.
                    Keys are attribute names, values are the current attribute values.
                    Only subscribed attributes that have changed are included.
                  example:
                    currentSpeed: 80.5
                    tractionEnergy: 120.0
    errorPayload:
      type: object
      description: |
        CloudEvents-compliant error payload.
        Sent by the 3S-API when it cannot process a client request.
      required:
        - id
        - source
        - specversion
        - type
        - time
        - version
        - correlationid
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier for this error message (UUIDv4)."
          example: "a7b8c9d0-e1f2-3456-7890-123456789abc"
        source:
          type: string
          pattern: "^xrn:ces:[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents source identifier in XRN format."
          example: "xrn:ces:siemens:3sapi.global.default"
        specversion:
          type: string
          const: "1.0"
          description: "CloudEvents specification version."
        type:
          type: string
          pattern: "^xrn:(cet|cec):[a-zA-Z0-9_-]+:.+$"
          description: "CloudEvents type indicating the error type."
          enum:
            - "xrn:cet:siemens3sapi:error.badRequest"
        version:
          type: string
          const: "1.0.0"
          description: "3S-API envelope specification version."
        datacontenttype:
          type: string
          const: "application/json"
          description: "Content type of the data value."
        time:
          type: string
          format: date-time
          description: "RFC3339 timestamp indicating when the error occurred."
          example: "2023-10-05T14:48:06Z"
        subject:
          type: string
          description: "CloudEvents subject - identifies the subject of the event in the context of the producer."
          example: "error"
        dataschema:
          type: string
          format: uri
          description: "CloudEvents dataschema - URI reference identifying the schema that data adheres to."
          example: "https://siemens.com/3sapi/v1/schemas/error"
        correlationid:
          type: string
          format: uuid
          description: "The id of the request that caused this error."
          example: "00000000-0000-0000-0000-000000000000"
        data:
          type: object
          description: "Error-specific data."
          additionalProperties: false
          properties:
            errors:
              type: array
              items:
                type: object
                additionalProperties: false
                properties:
                  message:
                    type: string
                    description: "Human-readable error message describing what went wrong."
                    example: "Invalid message format"
  messages:
    authenticationRequest:
      name: authenticationRequest
      title: Authentication Request
      summary: Request to authenticate with the 3S-API
      description: |
        Sent by the client to authenticate using a JWT token.
        This must be the first message after establishing the WebSocket connection.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/authenticationRequestPayload"
      examples:
        - name: successfulAuthRequest
          summary: Example authentication request
          payload:
            id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            source: "xrn:ces:siemens:3sapi.global.default"
            specversion: "1.0"
            type: "xrn:cec:siemens3sapi:authentication.authenticate"
            version: "1.0.0"
            datacontenttype: "application/json"
            time: "2023-10-05T14:48:00Z"
            subject: "authentication"
            dataschema: "https://siemens.com/3sapi/v1/schemas/authenticationRequest"
            data:
              data:
                id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                type: "authenticationRequest"
                attributes:
                  jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    authenticationResponse:
      name: authenticationResponse
      title: Authentication Response
      summary: 3S-API response to authentication request
      description: |
        Sent by the 3S-API after processing an authentication request.
        The type field indicates whether authentication succeeded or failed.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/authenticationResponsePayload"
      examples:
        - name: successResponse
          summary: Successful authentication response
          payload:
            id: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
            source: "xrn:ces:siemens:3sapi.global.default"
            specversion: "1.0"
            type: "xrn:cet:siemens3sapi:authentication.succeeded"
            version: "1.0.0"
            datacontenttype: "application/json"
            time: "2023-10-05T14:48:01Z"
            subject: "authentication"
            dataschema: "https://siemens.com/3sapi/v1/schemas/authenticationResponse"
            correlationid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            data:
              data:
                id: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
                type: "authenticationResponse"
                attributes:
                  message: "Authentication successful"
        - name: failedResponse
          summary: Failed authentication response (not authorized)
          payload:
            id: "b2c3d4e5-f6a7-8901-bcde-f23456789013"
            source: "xrn:ces:siemens:3sapi.global.default"
            specversion: "1.0"
            type: "xrn:cet:siemens3sapi:authentication.notAuthorized"
            version: "1.0.0"
            datacontenttype: "application/json"
            time: "2023-10-05T14:48:01Z"
            subject: "authentication"
            dataschema: "https://siemens.com/3sapi/v1/schemas/authenticationResponse"
            correlationid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            data:
              data:
                id: "b2c3d4e5-f6a7-8901-bcde-f23456789013"
                type: "authenticationResponse"
                attributes:
                  message: "Invalid or expired JWT token"
    subscriptionRequest:
      name: subscriptionRequest
      title: Subscription Request
      summary: Request to subscribe to train attributes
      description: |
        Sent by authenticated clients to subscribe to one or more train attributes.
        After successful subscription, the client will receive events when these attributes change.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/subscriptionRequestPayload"
      examples:
        - name: subscribeToMultipleAttributes
          summary: Subscribe to multiple train attributes
          payload:
            id: "c3d4e5f6-a7b8-9012-cdef-345678901234"
            source: "xrn:ces:siemens:3sapi.global.default"
            specversion: "1.0"
            type: "xrn:cec:siemens3sapi:subscription.subscribe"
            version: "1.0.0"
            datacontenttype: "application/json"
            time: "2023-10-05T14:48:02Z"
            subject: "subscription"
            dataschema: "https://siemens.com/3sapi/v1/schemas/subscriptionRequest"
            data:
              data:
                id: "c3d4e5f6-a7b8-9012-cdef-345678901234"
                type: "subscriptionRequest"
                attributes:
                  attributeNames:
                    - "currentSpeed"
                    - "tractionEnergy"
                    - "edBrakeEnergy"
    subscriptionResponse:
      name: subscriptionResponse
      title: Subscription Response
      summary: 3S-API response to subscription request
      description: |
        Sent by the 3S-API after processing a subscription request.
        On success, the client will start receiving events for the subscribed attributes.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/subscriptionResponsePayload"
      examples:
        - name: successResponse
          summary: Successful subscription response
          payload:
            id: "d4e5f6a7-b8c9-0123-def4-567890123456"
            source: "xrn:ces:siemens:3sapi.global.default"
            specversion: "1.0"
            type: "xrn:cet:siemens3sapi:subscription.succeeded"
            version: "1.0.0"
            datacontenttype: "application/json"
            time: "2023-10-05T14:48:03Z"
            subject: "subscription"
            dataschema: "https://siemens.com/3sapi/v1/schemas/subscriptionResponse"
            correlationid: "c3d4e5f6-a7b8-9012-cdef-345678901234"
            data:
              data:
                id: "d4e5f6a7-b8c9-0123-def4-567890123456"
                type: "subscriptionResponse"
                attributes:
                  message: "Subscription successful"
    unsubscriptionRequest:
      name: unsubscriptionRequest
      title: Unsubscription Request
      summary: Request to unsubscribe from train attributes
      description: |
        Sent by clients to stop receiving updates for specific attributes.
        The client must specify which attributes to unsubscribe from.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/unsubscriptionRequestPayload"
      examples:
        - name: unsubscribeFromAttributes
          summary: Unsubscribe from multiple attributes
          payload:
            id: "e5f6a7b8-c9d0-1234-ef56-789012345678"
            source: "xrn:ces:siemens:3sapi.global.default"
            specversion: "1.0"
            type: "xrn:cec:siemens3sapi:unsubscription.unsubscribe"
            version: "1.0.0"
            datacontenttype: "application/json"
            time: "2023-10-05T14:48:04Z"
            subject: "unsubscription"
            dataschema: "https://siemens.com/3sapi/v1/schemas/unsubscriptionRequest"
            data:
              data:
                id: "e5f6a7b8-c9d0-1234-ef56-789012345678"
                type: "unsubscriptionRequest"
                attributes:
                  attributeNames:
                    - "currentSpeed"
                    - "tractionEnergy"
    unsubscriptionResponse:
      name: unsubscriptionResponse
      title: Unsubscription Response
      summary: 3S-API response to unsubscription request
      description: |
        Sent by the 3S-API after processing an unsubscription request.
        On success, the client will stop receiving events for the unsubscribed attributes.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/unsubscriptionResponsePayload"
      examples:
        - name: successResponse
          summary: Successful unsubscription response
          payload:
            id: "f6a7b8c9-d0e1-2345-f678-901234567890"
            source: "xrn:ces:siemens:3sapi.global.default"
            specversion: "1.0"
            type: "xrn:cet:siemens3sapi:unsubscription.succeeded"
            version: "1.0.0"
            datacontenttype: "application/json"
            time: "2023-10-05T14:48:05Z"
            subject: "unsubscription"
            dataschema: "https://siemens.com/3sapi/v1/schemas/unsubscriptionResponse"
            correlationid: "e5f6a7b8-c9d0-1234-ef56-789012345678"
            data:
              data:
                id: "f6a7b8c9-d0e1-2345-f678-901234567890"
                type: "unsubscriptionResponse"
                attributes:
                  message: "Unsubscription successful"
    event:
      name: event
      title: Attribute Change Event
      summary: Real-time notification of attribute value changes
      description: |
        Pushed by the 3S-API when subscribed train attributes change their values.
        The data payload contains the current values of all changed attributes.
        Only attributes the client has subscribed to are included.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/eventPayload"
      examples:
        - name: attributeChangeEvent
          summary: Event with multiple changed attributes
          payload:
            id: "c4f6b3a8-7e0b-4f2c-9d1f-cc6de2d2a3a1"
            source: "xrn:ces:siemens:3sapi.global.default"
            specversion: "1.0"
            type: "xrn:cet:siemens3sapi:attributes.changed"
            version: "1.0.0"
            datacontenttype: "application/json"
            time: "2023-10-05T14:48:00Z"
            subject: "attributes"
            dataschema: "https://siemens.com/3sapi/v1/schemas/attributeChangeEvent"
            data:
              data:
                id: "c4f6b3a8-7e0b-4f2c-9d1f-cc6de2d2a3a1"
                type: "attributeChangeEvent"
                attributes:
                  currentSpeed: 80.5
                  tractionEnergy: 120.0
                  edBrakeEnergy: 15.2
                  tractionLever: 0.75
                  traction: 50
                  totalCurrentPower: 300
                  afbSpeed: 85
                  mainPipePressure: 5.5
                  sandingMode: 1
                  edBrakeForceReduction: 10
                  propulsionSystemPower: 250
                  timestamp: "2023-10-05T14:48:00Z"
    error:
      name: error
      title: Error Message
      summary: Error notification from the 3S-API
      description: |
        Sent by the 3S-API when it cannot process a client request.
        The correlationid links this error to the original request.
        The data.message field provides human-readable error details.
      contentType: application/json
      payload:
        $ref: "#/components/schemas/errorPayload"
      examples:
        - name: badRequestError
          summary: Bad request error response
          payload:
            id: "a7b8c9d0-e1f2-3456-7890-123456789abc"
            source: "xrn:ces:siemens:3sapi.global.default"
            specversion: "1.0"
            type: "xrn:cet:siemens3sapi:error.badRequest"
            version: "1.0.0"
            datacontenttype: "application/json"
            time: "2023-10-05T14:48:06Z"
            subject: "error"
            dataschema: "https://siemens.com/3sapi/v1/schemas/error"
            correlationid: "00000000-0000-0000-0000-000000000000"
            data:
              errors:
                - message: "Invalid message format"

