From d7fdfb855407a2d1783f2db2f3ad4c0dd31ca2f4 Mon Sep 17 00:00:00 2001 From: Ulf Bjorkengren Date: Fri, 23 Aug 2024 15:20:10 +0200 Subject: [PATCH] Server capabilities update. Signed-off-by: Ulf Bjorkengren --- spec/VISSv3.0_Core.html | 323 ++++++++++++++++++++++++++-------------- 1 file changed, 212 insertions(+), 111 deletions(-) diff --git a/spec/VISSv3.0_Core.html b/spec/VISSv3.0_Core.html index be02b07..6d90e97 100644 --- a/spec/VISSv3.0_Core.html +++ b/spec/VISSv3.0_Core.html @@ -613,14 +613,10 @@

Filter Request

-
  • static-metadata: +
  • metadata:
    • the response contains the VSS metadata of the addressed sub-tree.
    • -
  • dynamic-metadata: -
      -
    • the response contains metadata additional to the VSS specification.
      • -
  • parameter: the key name for the optional configuration data that the filter operation requires. The parameter data varies depending on the variant, @@ -752,57 +748,27 @@

    Curve logging Filter Operation

    -
    -

    Static Metadata Filter Operation

    +
    +

    Metadata Filter Operation

    - The static metadata request is used when the client instead of the data associated to VSS node(s) + The metadata request is used when the client instead of the data associated to VSS node(s) wants to retrieve meta data associated to the VSS node(s).
    The metadata is retrieved from the VSS tree that is deployed in the vehicle. This request variant is sometimes referred to as a signal discovery request. If the "parameter" object contains an empty string, then all metadata that the server can retrieve for the for the addressed node(s) are returned, while if it contains a metadata key name, or an array of key names, then only the selected metadata is returned.
    - For the set of static metadata key names, + For the set of metadata key names, see the Vehicle Signal Specification.
    The vsspath in the request may point to either a leaf node, or to a branch node. - In the latter case then the response will contain static metadata from the entire sub-tree having this branch as the root.
    - A static metadata request can be combined with a paths filter operation to address multiple nodes, + In the latter case then the response will contain metadata from the entire sub-tree having this branch as the root.
    + A metadata request can be combined with a paths filter operation to address multiple nodes, but cannot be combined with any other filter variant.
    The response is a JSON formatted object with corresponding key-value pairs per addressed node. - The server MAY support the static metadata request.
    + The server MAY support the metadata request.
    Example can be found in the signal discovery read on HTTPS in [[viss3-transport-examples]] specification.

    -
    -

    Dynamic Metadata Filter Operation

    -

    - Dynamic metadata requests are used when the client instead of the data associated to VSS node(s) wants to - retrieve metadata that is additional to the VSS specification.
    - The dynamic metadata may change over time. - The request filter "parameter" object MUST only contain one of the metadata key names from the list of dynamic metadata key names below.
    -

      -
    • samplerate: The native capture frequency in Hz that is used by the vehicle system. - The response uses the same syntax as for ordinary data responses, with "value" representing the sample rate.
      • -
    • availability: The current availability of the signal(s). The possible values are ["available", "unavailable", "error"]. - The unavailable status is returned when the signal is inaccessible due to the current vehicle state. - The error status is returned if the subsystem represented by the signal exists in the vehice, but is broken and requires repair. - The response uses the same syntax as for ordinary data responses, with "value" representing the availability.
      • -
    • validate: The access control rule that is applied to the node and its sub-tree. - The possible values are ["write-only", "read-write"]. - The response uses the same syntax as for ordinary data responses, with "value" representing the validate tag. - The server applies the validate data according to the inheritance rules described in the access control selection chapter.
      • -
    • server_capabilities: The capabilities that the server supports. - See B. Server Capabilities for how this is expressed in the response.
      • -
    - A dynamic metadata request can be combined with a paths filter operation to address multiple nodes, - but not with any other filter variant.
    - The server capabilities request MUST be supported, the others on the list are optional. - For the server capabilities request the vsspath SHALL be set to "Vehicle", and the paths filter MUST not be used.
    - Examples can be found in the dynamic metadata read on HTTPS - and signal discovery read on WebSocket in [[viss3-transport-examples]] specification. -

    -
    -

    Multiple Signals Request

    @@ -2361,32 +2327,7 @@

    JSON Schema

    "oneOf": [ { "properties": { - "variant": { "const": "static-metadata" }, - "parameter": { - "type": "string" - } - }, - "required": ["parameter"] - }, - { - "properties": { - "variant": { "const": "static-metadata" }, - "parameter": { - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": ["parameter"] - } - ] - }, - { - "oneOf": [ - { - "properties": { - "variant": { "const": "dynamic-metadata" }, + "variant": { "const": "metadata" }, "parameter": { "type": "string" } @@ -2395,7 +2336,7 @@

    JSON Schema

    }, { "properties": { - "variant": { "const": "dynamic-metadata" }, + "variant": { "const": "metadata" }, "parameter": { "type": "array", "items": { @@ -2526,42 +2467,222 @@

    JSON Schema

    "required": ["number", "reason", "message"] } } -} +} +

    Server Capabilities

    - On receiving a dynamic-metadata request on server capabilities the server SHALL respond with a JSON object that for each of the keys - in the list below contains the associated values in the list that the server supports. - Both the keys and the values are represented as strings, if a key has more than one value, these are represented as an array.
    - A key name refers to a functional domain of the specification, and the tables below contain the capabilities of these domains. - The ones marked as underlined are mandatory, the others are optional. - + A client that wants to connect to a server may be interested in what capabilities the server offers. + The server maintains a separate Server tree which the client can access for this purpose. + However, for the client to access this information it must have information about at least one transport protocol that the server supports. + The VISS API should not make any assumptions on the communication network topology. + Therefore it should not mandate any transport protocol, instead it should assume that a client can obtain necessary information via out-of-band means + to configure its communication in order to successfully connect to the vehicle server. + How that is done is out-of-scope for this specification, + but as an example a solution may be designed around a cloud based repository to which servers can register their capabilities, + and clients can inquire about obtaining this information. + When a client has obtained the information how to connect to the server, then the server MUST respond to read requests for data from the Server tree. +

    + +

    Server Tree Example

    +

    + Below follows an example of a server capabilities tree. + The tree MUST contains the structures listed below, other parts are optional. + Server capabilities that extends this specification, or change anything defined in this specification SHALL be declared in the Server tree. +

      +
    • The root node name MUST be Server.
      • +
    • The Server node MUST have at least have two children named Support and Config.
      • +
    • The Support node MUST have at least one child named Protocol.
      • +
    • The Protocol node MUST be an attribute with a string array datatype with members defining the supported transport protocols.
      • +
    + 
    
+#
+# The server capabilities declaration.
+#
+Server:
+  type: branch
+  description: Root for the server capabilities.
+
+Server.Support:
+  type: branch
+  description: Top branch declaring the server supported features.
+  
+Server.Support.Protocol:
+  type: attribute
+  datatype: string[]
+  description: List of supported transport protocols.
+
+Server.Support.Security:
+  type: attribute
+  datatype: string[]
+  description: List of supported security related features.
+
+Server.Support.Filter:
+  type: attribute
+  datatype: string[]
+  description: List of supported filter features.
+
+Server.Config:
+  type: branch
+  description: Top branch declaring the configuration of server supported features.
+  
+Server.Config.Protocol:
+  type: branch
+  description: Top branch declaring the configuration of server supported protocols.
+  
+Server.Config.Protocol.Http:
+  type: branch
+  description: Top branch for the server supported HTTP protocol.
+
+Server.Config.Protocol.Http.Primary:
+  type: branch
+  description: HTTP configuration for the primary payload format.
+
+Server.Config.Protocol.Http.Primary.PortNum:
+  type: attribute
+  datatype: uint32
+  description: HTTP port number for the primary payload format.
+
+Server.Config.Protocol.Websocket:
+  type: branch
+  description: Top branch for the server supported Websocket protocol.
+
+Server.Config.Protocol.Websocket.Primary:
+  type: branch
+  description: Websocket configuration for the primary payload format.
+
+Server.Config.Protocol.Websocket.Primary.PortNum:
+  type: attribute
+  datatype: uint32
+  description: Websocket protocol port number for the primary payload format.
+
+Server.Config.Protocol.Websocket.Protobuf:
+  type: branch
+  description: Websocket configuration for the protobuf encoded payload format.
+
+Server.Config.Protocol.Websocket.Protobuf.PortNum:
+  type: attribute
+  datatype: uint32
+  description: Websocket protocol port number for the protobuf encoded payload format.
+
+Server.Config.Protocol.Mqtt:
+  type: branch
+  description: Top branch for the server supported MQTT protocol.
+
+Server.Config.Protocol.Mqtt.PortNum:
+  type: attribute
+  datatype: uint32
+  description: MQTT port number.
+
+Server.Config.Protocol.Mqtt.Primary:
+  type: branch
+  description: MQTT configuration for the primary payload format.
+
+Server.Config.Protocol.Mqtt.Primary.Topic:
+  type: attribute
+  datatype: string
+  description: MQTT topic name for the primary payload format.
+
+Server.Config.Protocol.Mqtt.Protobuf:
+  type: branch
+  description: MQTT configuration for the protobuf encoded payload format.
+
+Server.Config.Protocol.Mqtt.Protobuf.Topic:
+  type: attribute
+  datatype: string
+  description: MQTT topic name for the protobuf encoded payload format.
+
+Server.Config.Protocol.Grpc:
+  type: branch
+  description: Top branch for the server supported gRPC protocol.
+
+Server.Config.Protocol.Grpc.Protobuf:
+  type: branch
+  description: gRPC configuration with the protobuf encoded payload format.
+
+Server.Config.Protocol.Grpc.Protobuf.PortNum:
+  type: attribute
+  datatype: uint32
+  description: gRPC port number for the protobuf encoded payload format.
+
+Server.Config.AccessControl:
+  type: branch
+  description: Access control configuration.
+
+Server.Config.AccessControl.AgtsUrl:
+  type: attribute
+  datatype: string
+  description: Access Grant Token Server URL including port number and path.
+
+Server.Config.AccessControl.AtsPortNum:
+  type: attribute
+  datatype: uint32
+  description: Access Token Server port number.
+
+Server.Config.AccessControl.Flow:
+  type: attribute
+  datatype: string
+  description: Supported access control flows.
+
+Server.Config.Consent:
+  type: branch
+  description: Consent configuration.
+
+Server.Config.Consent.Ecf:
+  type: attribute
+  datatype: string
+  description: External Consent Framework description.
+
    +

    + +

    Server Feature Naming

    +

    + The feature names that are used in the Server tree should for the features described in this specification use the names listed below. + +

    Support Naming

    +
    - + - - + + - - + + + + + + + + + + + +
    Key nameProtocol Description
    filterhttp[[viss3-transport-examples]], Transport Protocol Examples:HTTPS chapter
    access_ctrlws[[viss3-transport-examples]], Transport Protocol Examples:Secure Websocket chapter
    mqtt[[viss3-transport-examples]], Transport Protocols:MQTT chapter
    grpc[[viss3-transport-examples]], Transport Protocols:gRPC chapter

    + + + + + - - + + - - + +
    SecurityDescription
    transport_protocol[[viss3-transport-examples]], Transport Protocol Examples chapteraccesscontrol
    payload_encoding[[viss3-payload-encoding]], Payload Encoding chapterconsent

    + - + @@ -2589,17 +2710,15 @@

    Server Capabilities

    - - - - - - + +
    filterFilter Description
    static_metadata
    dynamic_metadatametadata

    + +

    Config Naming

    - + @@ -2615,24 +2734,6 @@

    Server Capabilities

    access_ctrlAccess Control Flow Description

    - - - - - - - - - - - - - - - - - -
    transport_protocolDescription
    https[[viss3-transport-examples]], Transport Protocol Examples:HTTPS chapter
    wss[[viss3-transport-examples]], Transport Protocol Examples:Secure Websocket chapter
    mqtts[[viss3-transport-examples]], Transport Protocols:MQTT chapter