COVESA VISS version 3.1

The Vehicle Information Service Specification (VISS) is a service for accessing vehicle information, including signals from sensors on control units within a vehicle's network. This information is exposed through a hierarchical, tree-like taxonomy as defined in the COVESA Hierarchical Information Model (HIM), and is provided in JSON format. The VISS service may be hosted within the vehicle or on external servers, using data that has already been off-boarded.

VISS enables a broad range of use cases, including predictive maintenance, usage-based insurance, fleet management, and real-time driver assistance services. In the context of artificial intelligence, VISS serves as a critical data access layer, providing high-quality, real-time vehicle data that can be utilized by AI algorithms for tasks such as anomaly detection, driver behavior analysis, energy optimization, and contextual decision-making.

The first version of VISS, which has been implemented and deployed in production vehicles, supported only WebSocket as a transport protocol.
The second version is generalized to work across also the HTTP and MQTT transport protocols to improve the support for different use cases. It also contains improved subscription capabilities and added an access control mechanism.
The third version included the gRPC transport protocol but also simplified addition of other transport protocols by placing the normative requirement on the message payload only, and not also on what transport protocol to use. Several new features were added such as file transfer, payload encoding, and improved server capabilities representation.
This specification, the version 3.1, is a backwards compatible extension of the third version of VISS. Instead of referencing to the VSS rule set for how to define the content of a tree it refers to the rule sets of the HIM vehicle data profile.This enables also other trees than the VSS tree to be used, a server may manage a set of trees, a forest, that a client can access. Other changes are support for the Unix domain socket protocol, and minor adaptations to support the concept of having a forest of trees, such as adding support for a client to do a forest inquiry.

There are three parts to this specification, CORE, [[TRANSPORT]], and [[PAYLOAD ENCODING]]. This document, the VISS version 3.1 CORE specification, describes the VISSv3.1 messaging layer.
The VISSv3.1 transport protocol specification describes the deviations from the CORE definitions that are used in some transport protocols. It also examplifies the JSON primary payload format using the Websocket payloads. The VISSv3.1 payload encoding specification describes payload encoding designs that may be applied e. g. for payloads in transit.
The specification is supplemented by the [[IMPLEMENTATION_GUIDELINES]] document which provides recommendations on how to implement certain features to ensure client interoperability on different implementations.

Interface

This section describes the different methods and their arguments that govern the communication between a client and the server.

Methods

Transport protocols used to implement these methods MUST support the Read and Update methods, and MAY support the Subscribe, Unsubscribe, and Subscription methods.

Read

Purpose: Get one or more values addressed by the given path.

The client MAY have to obtain an authorization token before accessing the requested values. If the server successfully processes the request, it MUST return a success response. If the server fails to fulfill the request, then the server MUST return an error message.

Arguments, of which path is mandatory:

path The HIM-defined path to a node in the tree.
filter Additional parameters to refine the requested data.
authorization The authorization token.
dc The compression scheme(s) used for transmitted data.

Success response, of which authorization is optional:

data A structure containing one or more sets of a path and data point.
path The HIM-defined path for the associated data point.
data point A structure containing one or more value-timestamp tuples.
value The latest available value. Please note that also for actuators this returns the current value, and not a target value that might have been set.
timestamp The capture time of the value.
authorization A handle representing the authorization token.
timestamp The server execution time of the request.

Update

Purpose: Provide an altered value to the vehicle signal addressed by the path.

The client MAY have to obtain an authorization token before updating a vehicle signal. If the server successfully processes the request, it MUST return a success response. If it cannot, it MUST return an error message. Only actuator type signals can be updated. Please note that a success response does not guarantee that the actuation attempt to change to the updated target value has, or will, succeed. A client may monitor the actuation progress through subsequent reads of the actuator value.
The server MAY use the timestamp from the request to discard requests that are older than the latest previously received request, followed by an error response. For more information, refer to the .

Arguments, of which path and value are mandatory:

path The HIM-defined path to a leaf node in the tree.
value The new value to update the vehicle signal at the specified path.
authorization The authorization token.
timestamp The client dispatch time of the request.

Success response, of which authorization is optional:

authorization A handle representing the authorization token.
timestamp The server execution time of the request. This may not be the same as the final update time of the signal.

Unsubscribe

Purpose: Terminates a subscription that was previously established through a subscribe request.

If the server successfully processes the request, it MUST return a success response, and it MUST stop issuing event messages associated to the subscription handle. If the server fails to fulfill the request, then the server MUST return an error message.

Arguments, of which subscriptionId is mandatory:

subscriptionId A unique identifier for the subscription session.

Success response:

timestamp The time at which the subscription was terminated.

Subscription

Purpose: Sends asynchronous event messages to the client when a subscribe request trigger rule is met.

The server MUST issue an event message when a triggering rule associated with the subscription is met. If the server cannot fulfill the triggering rules it MUST issue an error message and terminate the subscription.

Arguments, of which all are mandatory:

subscriptionId A unique identifier for the subscription session.
data A structure containing one or more sets of a path and data point.
path The HIM-defined path for the associated data point.
data point A structure containing one or more value-timestamp tuples.
value The current value associated with the filter expression.
timestamp The capture time of the value.
timestamp The server execution time of the subscription event.

Error Message

The server MUST notify the client of any errors that occur during their interaction, whether as a synchronous error response or an asynchronous error event resulting from a previous subscription request. The error message has three arguments, of which subscriptionId is mandatory only for error events. In the case of an error event being issued by the server, the associated subscription session SHALL thereafter be terminated by the server.

Arguments:

subscriptionId The reference to the subscribe session.
timestamp The server execution time when the error occurred.

Error Information

The error information consists of three components: number, reason, and description. All the three components MUST be part of the error information.

number Refer to the section 4.1 Status Codes defined in [[TRANSPORT]].
reason Refer to the section 4.1 Status Codes defined in [[TRANSPORT]].
description Refer to the section 4.1 Status Codes defined in [[TRANSPORT]].

Timestamps

Timestamps in transport payloads MUST conform to the [[ISO8601]] standard, using the UTC format with a trailing Z. Time resolution SHALL at least be seconds, with subsecond resolution as an optional degree of precision when desired. The time and date format shall be as shown below, where the sub-second data and delimiter is optional.
YYYY-MM-DDTHH:MM:SS.ssssssZ
The exceptions to this are timestamps within tokens which MUST conform to Unix time, or if timestamp data compression is applied.

Filter Request

Filtering is a mechanism that refines client requests to provide more precise control over the returned response data. Filtering can be applied in both read requests and subscribe requests.
A request with filtering follows this structure:

For HTTP protocol:
- GET /<himpath>?filter=<filter-expression>
For any protocol using the primary JSON payload format:
- {"action":"get", "path":"<himpath>", "filter":"<filter-expression>"}

where

get: the transport protocol method.
himpath: The HIM path, starting from the tree root.
filter: The key name for the filter expression.
filter-expression: The filter instructions.

The filter expression has the object format as shown below. For the case of an optional second object of this type, these are enclosed in an array expression.

{"variant":"<x>", "parameter":"<y>"}

where

variant: The key name for the filter operation variant, which can have one of the following values:
- paths:
  - One or more relative paths. If multiple paths are used, an array expression SHALL be applied.
- timebased:
  - Data is captured at fixed time intervals.
- range:
  - Data is captured when values are in the given range.
- change:
  - Data is captured when the value since last capture has changed more than a fixed value.
- curvelog:
  - Captured data is processed according to the curve logging algorithm before being sent to client.
- history:
  - Captured data from a time period from current time and backwards in time.
- metadata:
  - The response contains the metadata of the addressed sub-tree.
parameter: The key name for optional configuration data required by the filter operation. The parameter data varies depending on the variant. It must be enclosed in an object or, optionally, an array of two objects. Detailed descriptions of parameter values are provided in the following sections.

The server MUST support the timebased and change variants, the other variants are optional.
In the JSON object, the key-value pairs "variant" and "parameter" MUST always be present. Multiple filter expressions may be combined in one subscribe request.
The following SHALL be supported.

A JSON expression that may consist of maximum one object with variant "paths", plus maximum one object with any other supported variant, which are then logically combined as with an AND operator.
The variants timebased, range, change, and curvelog can only be used in subscription requests.

A server may optionally support other filter combinations on top of the mandatory support. In that case these combinations MUST be expressed in the Server.Support.Filter tree node string array by the filter variant names combined with a plus sign (+) as delimiter. A combination of e. g. a timebased filter and a change filter would be represented in the array as “timebased+change”. For the combined trigger condition to lead to an issued event message a logical AND operation combines the evaluated results of the respective conditions, which SHALL be evaluated at the same point in time.
Subscription requests are NOT supported by the HTTP transport protocol.
The restriction on how many objects that can be combined is also set by the URL size restriction on 1k characters (*).
(*) 1k is the "conservative limit, which should always be supported, a more liberal limit is 2k, which is supported in most cases.

Paths Filter Operation

The paths filter operation allows a single request to retrieve signal data from multiple data points in the tree. The himpath SHALL point to the last node in the tree that is common for the relative paths in the filter parameter object, that start off from this node. If a path endpoint in the filter value is a branch, all leaf nodes in the sub-tree below that branch SHALL be included. A path in the filter value MAY contain the wildcard character (*), which represents a single path segment.
Every path element in a value array must address at least one node in the tree. If no matching node is found, the server SHALL return an error message.
Different elements of the value array MAY address the same node, in which case it is the responsibility of the server to resolve this to a singleton in the event messages.
Examples can be found in the section 5.1.2.1.2 Search Read and section 5.2.2.1.2 Search Read in [[TRANSPORT]] specification.

History Filter Operation

By default, the server typically have access only to the latest, most fresh data point representing a signal. However, under certain conditions, it MAY temporarily store and provide access to historical data points. One such scenario occurs when a vehicle temporarily loses connectivity, for example, when entering a tunnel. If the vehicle detects this loss of connectivity, it MAY begin recording data. If recorded, this data MAY be accessed using the history variant of the filter operation. The vehicle system makes its own decision whether to record any data, and for how long this data will be kept in storage. The history period in the filter expression MUST extend backward in time from the current time, excluding the current value. The number of data points in the response depends on the history period size, and the sampling frequency. Since the sampling frequency is server-defined, the client SHOULD estimate the potential data volume before making a request. If no historical data is available, the request SHALL return a "404 Not Found" error. The period MUST conform to the [[ISO8601]] duration format, expressed in days, hours, minutes, and seconds. For example: "parameter": "PdddDThhHmmMssS". The number of days MUST be less than 999. Only a single period can be specified.
Examples can be found in the section 5.1.2.1.3 History Read and section 5.2.2.1.3 History Read in [[TRANSPORT]] specification.

Time-Based Filter Operation

The parameter object contains the period time X in between captures, {"period":"X"}. X is an integer and represents the period time in milliseconds. Example can be found in the section 5.1.2.3 Subscribe in [[TRANSPORT]] specification.

Range Filter Operation

The range filter operation supports two types of ranges, as described in the following sub-sections
The values MUST be of a numeric data type.

Single Boundary Range

A single "boundary operator" evaluates the current signal value relative to a single boundary. If the condition evaluates to true, the server MUST issue an event message containing the signal value to the subscribing client. The boundary operator MUST be one of the values listed in the footer (**).
Examples
{"logic-op":"gt", "boundary": "5"} // x > 5
{"logic-op":"eq", "boundary": "5"} // x == 5

Multi Boundary Range

A multi boundary range evaluates the current signal value relative to two boundaries. The logical outcome of the two evaluations are applied as input to a logical AND/OR operation. If the condition evaluates to true, the server MUST issue an event message containing the signal value to the subscribing client. In addition to the mandatory "logic-op" and "boundary" key-value pairs in each JSON object, the first object MAY include an optional "combination-op" key-value pair, which MUST have either the value "AND" or "OR". If omitted, the result of the two boundary evaluations SHALL default to an AND operation. The JSON array MUST contain two objects. The boundary operator MUST be one of the values listed in the footer (**).
Examples
[{"logic-op":"gt", "boundary": "5"},{"logic-op":"lt", "boundary": "10"}] // x > 5 AND x < 10
[{"logic-op":"lt", "boundary": "5", "combination-op":"OR"},{"logic-op":"gt", "boundary": "10"}] // x < 5 OR x > 10

(**)The supported boundary operators are ["eq", "ne", "gt", "gte", "lt", "lte"], where "eq" is "equal", "ne" is "not equal", "gt" is "greater than", "gte" is "greater than or equal", "lt" is "less than", "lte" is "less than or equal".
Examples can be found in the section 5.1.2.3.1 Authorized Subscribe and section 5.1.2.3.3 Range Subscribe in [[TRANSPORT]] specification.

Change Filter Operation

The change filter operation detects differences between previous and current values based on a specified condition. The diff values MUST be of numeric or boolean data types.
The parameter object contains the logical operator for comparison of previous and current values, {"logic-op":"X", "diff":"Y"}, where X is one of the supported logical operators (**), and Y is the value of the required change.
For boolean values the following expressions SHALL be supported:

{"logic-op":"gt", "diff": "0"}: Triggers an event when the value changes from false->true.
{"logic-op":"lt", "diff": "0"}: Triggers an event when the value changes from true->false.
{"logic-op":"ne", "diff": "0"}: Triggers an event when the value changes from true->false OR false->true.

The "not equal" (ne) logic operator with a zero (0) diff can also be used to track changes in string data types, where other diff values may not be applicable.

(**)The supported logic operators are ["eq", "ne", "gt", "gte", "lt", "lte"], where "eq" is "equal", "ne" is "not equal", "gt" is "greater than", "gte" is "greater than or equal", "lt" is "less than", "lte" is "less than or equal".
Example can be found in the section 5.1.2.3.4 Change Subscribe in [[TRANSPORT]] specification.

Curve logging Filter Operation

The curve logging filter operation compresses data by simplifying a time-series signal while maintaining its essential characteristics. The parameter object contains the maximum error limit, and the buffer size, {"maxerr": "X", "bufsize":"Y"}, where X is a floating-point value representing the maximum allowable error between any sampled data point and the simplified curve, and Y is the number of buffer elements. The data is processed when the buffer becomes full, and only the essential data points are returned as a time series per signal.
Example can be found in the section 5.1.2.3.2 Curve Logging Subscribe in [[TRANSPORT]] specification.

Metadata Filter Operation

A metadata request allows a client to do a so called "signal inquiry", i. e. to retrieve metadata associated with tree node(s), rather than the actual signal data.
The metadata is retrieved from the tree that is deployed in the vehicle. This request variant is sometimes referred to as a signal discovery request.
The path in the request MAY point to either a leaf node or a branch node. The "parameter" value in the filter expression sets the number of descendant generations that metadata will maximally be returned from. If it is set to zero then there is no limit set and the entire sub-tree that has the addressed node as root will be returned. If it is set to two then the metadata from the subtree root and its immediate children will be returned. A metadata request can be combined with a paths filter operation to address multiple nodes. If it is combined with any other filter variant an error message is returned.
The response is a JSON formatted object containing key-value pairs for each addressed node. The server MAY support the metadata request.
Example can be found in the section 5.2.2.1.4 Signal Discovery Read in [[TRANSPORT]] specification.

Forest Inquiry

A metadata request can also be used by the client to retrieve information about the set of trees that the server manages, a so called "forest inquiry". This request must have a path starting with the root node name "HIM" which may be appended with one dot delimited segment name to address a specific tree in the forest. The response contains all the addressed metadata in the HIM configuration file except for the "local" property which holds the path to the tree in the local file system.
The forest inquiry request is the only request type that is allowed on the HIM configuration file data, all others will get an error response.
A server that does not utilize a HIM file for representing the set of trees it manages, if it e. g. manages a predefined, static set of trees, MUST be able to respond to the request e. g. by having a predefined, static response describing the trees it manages. The response shall have the same content as if it was created from a HIM configuration file describing the forest.

Multiple Signals Request

Filtering operations MAY be used to address multiple nodes in the tree within a single request. However, this MAY lead to specific issues in certain situations, as described below.

Error Handling

Error messages for multiple-signal requests are handled the same way as for single-signal requests, except when one or more signals are temporarily unavailable. In such cases, the server MAY use in-line error reporting, Refer to the section 4.1.1 In-line Error Reporting in [[TRANSPORT]] specification.

Response syntax

A response MAY contain multiple values, due to either that multiple nodes were addressed or that multiple values for one signal are returned.
These two reasons can be combined, leading to four different cases.

Request for a single value from a single node.
Request for multiple values from a single node.
Request for a single value from multiple nodes.
Request for multiple values from multiple nodes.

The syntax to accommodate these four cases have a common structure where a data point ("dp") consists of one or more objects containing a "value" and a timestamp ("ts"), and the complete aggregation ("data"), consists of one or more objects containing a "path" and a data point (dp"). The syntax of the four cases are shown below.

Response for a single value from a single node:

  "data": {
    "dp": {
      "ts": "Z",
      "value": "Y"
    },
    "path": "X"
  }

Response for multiple values from a single node:

  "data": {
    "dp": [
      {
        "ts": "Z1",
        "value": "Y1"
      },
      {
        "ts": "Zn",
        "value": "Yn"
      }
    ],
    "path": "X"
  }

Response for a single value from multiple nodes:

  "data": [
    {
      "dp": {
        "ts": "Z1",
        "value": "Y1"
      },
      "path": "X1"
    },
    {
      "dp": {
        "ts": "Zm",
        "value": "Ym"
      },
      "path": "Xm"
    }
  ]

Response for multiple values from multiple nodes:

  "data": [
    {
      "dp": [
        {
          "ts": "Z11",
          "value": "Y11"
        },
        {
          "ts": "Z1n",
          "value": "Y1n"
        }
      ],
      "path": "X1"
    },
    {
      "dp": [
        {
          "ts": "Zm1",
          "value": "Ym1"
        },
        {
          "ts": "Zmn",
          "value": "Ymn"
        }
      ],
      "path": "Xm"
    }
  ]

In the case of a request for multiple values from multiple nodes, the data point for different paths MAY contain single or multiple objects, as the vehicle system MAY not have multiple values recorded for all requested signals.

Subscription Event Triggering

A subscription request MUST include a filter operation that defines the trigger event causing the server to dispatch an asynchronous event message. For "range" and "change" filter variants, triggering depends on the signal value. When a request addresses multiple signals, the triggering condition SHALL be evaluated for only one signal, specifically the first signal in the paths parameter array. The first path in the array MUST NOT contain wildcards, as it determines the triggering signal. If a wildcard expression is used, one of the resolved path addresses MUST be explicitly selected as the first array element, followed by the wildcard expression. If this results in a duplicate reference to the same signal, the server SHALL resolve it into a singleton in the event messages.

Access Control Model

This section defines an access control model aligned with the General Data Protection Regulation (GDPR). The general process begins with a client authenticating for a specific role with the Access Grant Token Server. If this is successful it receives an access grant token. This token can then be used one or more times when making access requests to the Access Token Server. These requests contain the AGT and a purpose. It is assumed that the Ecosystem Manager has published a list of approved purposes that the ecosystem serves, and any other purpose must be denied access. If the request to the ATS is successful, the client receives an access token, which can then be used in requests to the VISSv3 server to access one or more signals associated with the approved purpose.
Access control MUST be supported. However, in this section, only the parts that describe interactions between the client and the VISSv3 server are mandatory.
Access control SHALL NOT be applied to the tree nodes containing the tree version data, nor to client requests for dynamic metadata about server capabilities or access control selection tags applied to the tree.

Architecture

This section is non-normative. The VISSv3 access control model is inspired by OAuth2.0 [[RFC6749]], but includes some deviations, which are described in the following sections.

The architecture defines four primary actors:

Client: An application making protected and authorized resource requests on behalf of its user.
Access Grant Token (AGT) Server: The server issuing the access grant token after successfully authenticating the client.
Access Token Server (ATS): The server issuing the access token to the client after successfully validating the request and obtaining authorization.
VISSv3 Server: The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

The abstract protocol flow illustrated in the figure below describes the interaction between the four actors.

VISSv3 abstract protocol flow. — The abstract protocol flow.

In addition to the four core actors, two additional actors participate in the ecosystem:

Resource Owner: This is typically the driver of the vehicle, who may be required to provide consent before access is granted.
Ecosystem Manager: The entity manages the access control ecosystem. It controls the Policy documents, and manages the PKI ecosystem that the other actors may utilize.

The abstract protocol flow is implemented through two different flows, which are described in the following sections.
The process of obtaining credentials for client authentication is out-of-scope, along with the installation procedures for the applications.

Protocol Flows

This section is non-normative.

Two different flows are described, and the choice of flow depends on the client's capabilities.
If a client supports public key cryptographic operations, such as key pair generation and digital signatures, and has access to a trusted execution environment (TEE) that protects private keys from the regular execution environment, then it can use the long-term flow. Clients that lack these capabilities or choose not to use them MUST select the short-term flow.
The advantage of the long-term flow is that the client can be trusted with longer expiry times of access grant tokens. In the short-term flow, due to a shorter expiry time, the client must contact the Access Grant Token Server more often to obtain a new access grant token.
A client selects the type of flow by either submitting a public key in the access grant request, or not. If a public key is submitted, the long-term flow is used; otherwise, the short-term flow applies.

Protocol Messages

This section is non-normative.

This section describes the payload structures of the messages used in the protocol flow.

Access Grant Request

The request SHALL contain the Context and Proof parameters listed below. The other parameters are optional:

VIN: The vehicle identification number. Instead of the assigned VIN, a generated hash may be used as a pseudo-VIN, or any other unique identifier that links the vehicle within the access control ecosystem.
Context: The context associated with the client, consisting of three key roles: user roles, application roles, and device roles.
Proof: A verification mechanism used by the client to prove its context to the Access Grant Token Server. This is a composite proof that includes user roles, application roles, and device roles.
Public Key: If this parameter is present, the client will receive a long-term access grant token in return.

Depending on the type of proofs included in the request, the client and the server MAY need to run an interactive protocol to verify them. The protocol MAY also involve third parties, such as the ecosystem manager or the resource owner. The verification protocol itself is out of scope for this specification.
In scenarios where both the client and the Access Grant Token Server are deployed inside the vehicle, the VIN parameter MAY be omitted. In all other deployment scenarios, the VIN parameter SHALL be included.

Access Grant Response

The response SHALL contain the parameter below:

Access Grant Token: A signed token that includes claims required to validate the client request.

The response to a successful access grant request MAY be either a short-term or long-term access grant token, depending on the input in the request message. The only difference between these token types is that a long-term access grant token SHALL include the public key used in the request.
The access grant token is a digitally signed document, issued by the Access Grant Token Server, containing all relevant information required to issue access tokens. If the request fails, the response SHALL contain the following parameter:

Error code: A error code that provides the client with clear guidance on what must be corrected for the request to succeed.

Access Token Request

The client may need to send multiple requests before receiving an access token, even when a valid access grant token is available. This is because, if consent is required, the Access Token Server (ATS) will forward the consent request to the External Consent Framework (ECF), and an immediate response from the ECF may not be available. In such cases, the ATS will respond to the initial access token request with a session handle, which the client MUST use in subsequent requests for the access token. Once the ATS receives a response from the ECF, it will process the client’s follow-up request in one of two ways:

If consent is granted, the ATS will return the access token.
If consent is denied, the ATS will return a response indicating the negative consent result only.

Initial Access Token Request

The request SHALL contain at least the following two parameters:

Access Grant Token: A signed token that includes the claims required to validate the client request.
Purpose: The intended use of the requested data by the client.

Short-term access grant tokens can be used directly as input to the Access Token Server. However, when using a long-term access grant tokens, the client SHOULD provide a Proof of Possession (PoP) for the private key corresponding to the public key embedded in the token.

The Access Token Server acts as a Policy Enforcement Point (PEP), making access control decisions based on the submitted access grant token and declared purpose.

Inquiry Access Token Request

This request MAY be issued by the client after receiving a session handle in response to an initial access token request.
The request SHALL contain at least the following parameter:

Session Handle: A reference identifier that logically links this request to the previously issued initial access token request.

Access Token Response

Protected Resource Request

This is a VISSv3 request including an access token as described in general in the section 5.1 Methods, and in detail for various transport protocols in the [[TRANSPORT]] specification. The first time a token is submitted in a request, it MUST be included in full. If the server supports access token caching and returns a token handle to the client, then subsequent requests MAY use the token handle instead of the complete access token.

Protected Resource Response

This is a VISSv3 response as described in general in the section 5.1 Methods, and in detail for various transport protocols in the [[TRANSPORT]] specification. It is identical to the response for an unprotected resource request, with no differences in structure or content.

Actors

Client

This section is non-normative. The client is an abstract representation of three sub-actors:

Device: It is responsible for running the applications that make requests to the VISSv3 server.
Application: It runs requests on behalf of the user.
User: It delegates access rights to the application.

All information related to the client is encoded in the context of the request.

Access Grant Token Server

This section is non-normative. The Access Grant Token Server is responsible for issuing access grant tokens to clients.
Depending on the capabilities of the client, the specification supports two types of access grant tokens as short-term and long-term access grant tokens.
Long-term access grant tokens, are recommended for clients that support public key cryptographic primitives (e.g., key pair generation and digital signatures), and that have access to a trusted execution environment (TEE) where private keys are securely protected from the regular execution environment. Short-term access grant tokens are intended for clients without such cryptographic capabilities. However, due to their shorter expiry times, they require the client to contact the Access Grant Token Server more frequently when requesting an access token from the Access Token Server.

A client request to the Access Grant Token Server SHALL contain:

A client context.
A set of proofs.
A VIN(Vehicle Identification Number).

If the client and the Access Grant Token Server are both deployed in-vehicle, the VIN MAY be omitted.
In all other cases, the VIN SHALL be included.
When the VIN is included in the request, the vehicle identity (vin) claim SHALL be present in the resulting access grant token.

If the client requires a long-term access grant token, then the request shall also contain:

A public key.

The public key MUST be generated by client, and the associated private key MUST be securely controlled by the client.

The VIN provided must identify the vehicle that the client intends to access.
The client context contains all relevant information about the client, i.e. for each of the three sub-actors that the client represents.
The proofs are used by the server to validate the client context.

The Access Grant Token Server is responsible for:

Verifying the client context, and determining if the requested roles can be granted.
Validating that the vehicle identified by the VIN belongs to the ecosystem and is accessible.
Issuing the access grant token.

The proofs may include certificates issued by a trusted Certificate Authority (CA) known to the Access Grant Token Server. For example, users may authenticate themselves using X.509 identity certificates and roles may be issued using attribute certificates. In such cases, as part of the authentication protocol, the Access Grant Token Server SHALL also validate the certificates signatures.
The Access Grant Token Server may contact the ecosystem manager to validate the VIN.
Details regarding access grant token generation are defined in the corresponding section.

Access Token Server

This section is non-normative. After a successful interaction with the Access Grant Token Server, the client SHALL request an access token from the Access Token Server. The client request SHALL include at least the following two parameters:

Access Grant Token.
Purpose.

If the client uses a long-term access grant tokens(i.e., one that includes a public key), it MUST also include a proof of possession for the corresponding private key in the request.
The purpose specified in the request MUST be supported by the ecosystem manager, and therefore listed in the official purpose list. The purpose list defines the set of accessible signals associated with each purpose, thereby enforcing the principle of least privilege.

The Access Token Server is responsible for:

Validating the the access grant token.
Verifying that the client context is authorized for the requested purpose.
Creating and issuing the access token.

The validation of the access grant token consists of at least the following:

Signature verification (using the public key of the Access Grant Token Server).
Expiry time check.

For long-term access grant tokens, the server MUST additionally verify the proof of possession, using the public key contained in the token.
The access grant token signature validation is done with the Access Grant Token Server public key.
To accommodate minor clock drift and network latency, the expiry time SHOULD include a reasonable margin, possibly up to tens of seconds.
If a vehicle identity (VIN) claim is present in the access grant token, it SHALL also be included in the access token.
If the client context, as defined in the access grant token, does not match any of the roles permitted for the specified purpose in the purpose list, then the client request for an access token MUST be denied.

Access Control Server

The VISSv3 server MUST support validation of access tokens. The functionality required for this validation is described in this section. This includes, at a minimum, validation of the following elements:

Token Signature.
Token Expiry Time.

If a vehicle identity claim (vin) is present in the token, then it MUST be validated to match the identity of this vehicle.
If any of these validations fail, the server MUST reject the access request.
Token signature validation MAY be delegated to the Access Token Server, provided that a secure communication link can be established. If delegation is not possible, then a pre-provisioned common secret may be shared with the Access Token Server, or PKI-based solutions MAY be used.
The VISSv3 server SHALL have access to a secure system time, which cannot be modified by actors without system acknowledged credentials. Time validation MAY allow for synchronization inaccuracies, typically within a range of tens of seconds.
After a successful token validation, the server MUST verify that the scope of the token is compatible with the request:

If the scope claim of the access token contains a purpose short-name, successful validation requires that all the nodes addressed by the path in the request MUST be matched by the paths associated with the purpose in the purpose list .
If the scope claim of the access token contains a explicit list of signals, successful validation requires that all the nodes addressed by the path in the request MUST be matched by the one of the signals included in the token.

Validation of the device and application roles MAY include techniques such as:

MAC Address Checks.
message Round-trip Measurements.

The result of access permission validation MUST have the outcome shown in the table below, when comparing the type of the client request with the access control mode either in the purpose list or the explicit signals that are associated to the scope claim in the access token. If the client request contains multiple signals, and any one of them fails the validation, then the entire request MUST be rejected.

Permission	read-only	read-write
get set subscribe
	Ok	Ok
	Nok	Ok
	Ok	Ok

The access token needs to be refreshed periodically, which is determined by the expiry time. If the access grant token that the client originally used to obtain the now-expired access token is still valid, then the client can revisit the Access Token Server with this access grant token to obtain a new access token.
However, if the access grant token is also expired, then the client MUST obtain a new access grant token first, before revisiting the Access Token Server.
The server SHOULD support caching of a limited number of access tokens. The access token MUST be added to the cache after a first successful request and it MUST be removed once they expire. If an access token is cached then the server SHALL return a token handle of at least 24 bytes long. The client MAY then use this instead of the complete access token in following requests that require this access token. If the client decides to include the access token handle in a request, the server must then fetch the corresponding access token from the cache, and verify its validity before deciding to grant the request.
The server MAY decide to remove any token from the cache at any time. If the client later references a removed token using its handle, the server WILL return a "401, invalid_token" error, and the client MUST resend the whole access token.
For any client request denied due to access control, the VISSv3 server MUST return a "401, invalid_token" error message.

Resource Owner

This section is non-normative.

The resource owner is typically the owner and/or driver of the vehicle. If consent is required to grant access to the protected resource, then the request SHOULD be directed to the resource owner. The process of obtaining consent is out of scope for this specification.

Ecosystem Manager

This section is non-normative.

The Ecosystem manager is the entity responsible for managing the access control system. This typically includes managing the Access Grant Token Server, and the Access Token Server, maintaining the Policy documents, and ensuring that a PKI domain is available for use by other actors in the ecosystem. .

Credentials

Client Authentication

This section is non-normative.

The three client sub-actors must provide authentication credentials to the Access Grant Token Server. These credentials MAY be certificates issued by a Certificate Authority (CA) recognized by Access Grant Token Server.
The details of these interactions are out of scope for this specification.

Access Grant Token

This section is non-normative.

Short-Term Access Grant Token

The short-term access grant token SHALL include the following claims in both the header and the payload. All claims are mandatory, except for the vehicle identity (vin) claim, which is optional.


          {
            "alg": "ES256",
            "typ": "JWT"
          },
          {
            "vin": "vehicle-id",
            "iat": 1609452095,
            "exp": 1609459199,
            "clx": "user+app+dev",
            "aud": "covesa.global/VISSv3",
            "jti": "5967e92e-40e8-5f39-892d-cc0da890db1d"
          }

The alg (algorithm) claim SHALL be set to a valid RSA or ECDSA algorithms according to [[RFC7518]].
The typ (type) claim SHALL be set to "JWT".
The vin (vehicle identity) claim MAY be present or not, depending on input to the Access Grant Token Server.
The iat (issued at) claim SHALL be set to the Unix timestamp representing the token’s issuance time.
The exp (expiry) claim SHALL be set to the Unix timestamp when the token expires.
The clx (Client context) SHALL be set to the client’s assigned role triplet (user, app, device), with each role separated by a plus sign (+).
The aud (audience) claim SHALL be set to the URL: "covesa.global/VISSv3".
The jti (JSON Web Token identity) claim SHALL be set to a UUID that is unique within the domain controlled by the ecosystem manager.

Long-Term Access Grant Token

Except for the vehicle identity (vin) claim, which is optional, the long term access grant token SHALL include the following claims in both the header and the payload.


          {
            "alg": "ES256",
            "typ": "JWT"
          },
          {
            "vin": "vehicle-id",
            "iat": 1609452095,
            "exp": 1609459199,
            "clx": "user+app+dev",
            "pub": client_pub_key,
            "aud": "covesa.global/VISSv3",
            "jti": "5967e92e-40e8-5f39-892d-cc0da890db1d"
          }

The alg (algorithm) claim SHALL be set to a valid RSA or ECDSA algorithms according to [[RFC7518]].
The typ (type) claim SHALL be set to "JWT".
The vin (vehicle identity) claim MAY be present or not, depending on input to the Access Grant Token Server.
The iat (issued at) claim SHALL be set to the Unix timestamp representing the token’s issuance time.
The exp (expiry) claim SHALL be set to the Unix timestamp when the token expires.
The clx (Client context) SHALL be set to the client’s assigned role triplet (user, app, device), with each role separated by a plus sign (+).
The pub (public key) claim SHALL be set to the client's public key provided in the access grant request, using the JSON Web Key (JWK) data structure [[RFC7517]].
The aud (audience) claim SHALL be set to the URL: "covesa.global/VISSv3".
The jti (JSON Web Token identity) claim SHALL be set to a UUID that is unique within the domain controlled by the ecosystem manager.

Access Token

Except for the vehicle identity (vin), and client context (clx) claims, which are optional, the access token SHALL include the following claims in both the header and the payload.


          {
            "alg": "HS256",
            "typ": "JWT"
          },
          {
            "vin": "vehicle-id",
            "iat": 1609452095,
            "exp": 1609459199,
            "scp": "PurposeX" || signal-set,
            "clx": "user+app+dev",
            "aud": "covesa.global/VISSv3",
            "jti": "5967e93f-40f9-5f39-893e-cc0da890db2e"
          }

The alg (algorithm) claim SHALL be set to a valid algorithms according to [[RFC7518]].
The typ (type) claim SHALL be set to "JWT".
The vin (vehicle identity) claim MAY be present or not, depending on input to the Access Grant Token Server.
The iat (issued at) claim SHALL be set to the Unix timestamp representing the token’s issuance time.
The exp (expiry) claim SHALL be set to the Unix timestamp when the token expires.
The scp (scope) claim SHALL be set to either a purpose list short name, which logically links to the signal scope as defined in the purpose list, or to a set of signals that the token permits access to. Each signal is defined as a JSON object containing the signal path, and the signal permission as shown below.
{"path":"him-path", "access_permission":"permission"}
If the scope claim is set to a purpose, the client context claim MUST be present in the token.
The clx (Client context) SHALL be set to the client’s assigned role triplet (user, app, device), with each role separated by a plus sign (+).
The aud (audience) claim SHALL be set to the URL: "covesa.global/VISSv3".
The jti (JSON Web Token identity) claim SHALL be set to an unguessable UUID that is unique within the domain controlled by the ecosystem manager.

Proof of Possession

This section is non-normative.

Long-term access grant tokens MUST to be accompanied by a Proof of Possession (PoP) for the private key corresponding to the public key included in the access grant token. This requirement enables a longer validity for this kind of tokens, ranging from a several days to a even a year. By adding the PoP, an eavesdropper is prevented to reuse an access token request, impersonating the client. Without a PoP, the longer the validity of an access grant token, the higher the risk an attacker could intercept and reuse it. PoP for JWT are defined in [[RFC7800]]. In essence, PoP enables the requester to proof to the server that it has access to a private key, without disclosing it. Traditionally, this is done by the server generating a random challenge, or nonce, and ask the client to sign it with its private key. Along with the public key, the server would be able to verify the PoP. This scheme would require an extra step in the protocols, where the client ask for the nonce.

To avoid this extra step, the client MAY generate the nonce itself. In this case, the server must ensure that nonces are not reused. While logging previously used nonces on the server may work in small-scale environments, a more scalable approach is to use an incremental nonce based on a timestamp. One of the drawbacks of this proposal is that the server has no means to check whether the PoP has been precomputed or not. However, this is irrelevant from the eavesdropper point of view.

If PoP freshness is a critical requirement, the nonce could be derived from a public source of randomness, such as the League of Entropy or Interoperable Randomness Beacons. That would provide the server a mean to check freshness of the PoP but on the other hand, it would require the client to access the public source of randomness every time it needs to create a PoP which is against the main design goals for the long term access grant token.

Client Context

This section is non-normative. The client context contains a client actor that is characterized by three sub-actors:

The user of the application.
The application.
The device.

Each of these sub-actors is in turn characterized by a role, building on the concept of a Role Based Access Control (RBAC) model. The set of these three roles is called the Client context.
VISSv3 specifies a rudimentary list of roles for each sub-actor, it is expected that these lists are augmented by the ecosystem manager, hopefully in a cooperative effort.
Using an RBAC model provides the following main purposes in the VISSv3 access control model:

Input to the Access Grant Token Server during client authentication process.
Input to the Access Token Server during purpose validation.

During authentication, the Access Grant Token Server MAY need to authenticate each sub-actor individually. For the Access Grant Token Server to decide on which authentication method to use per sub-actor can be quite complex. However, this complexity can be reduced if the client explicitly requests specific roles for each sub-actor. Following the principle of least privilege, a client should not have access to more vehicle signals than necessary. This is achieved by the purpose list, that assigns only the for the purpose relevant signals to the client.

User Roles

VISSv3 specifies the following minimum set of roles for users:

OEM
Dealer
Independent
Owner
Driver
Passenger

An OEM user is anyone who represents the vehicle manufacturer (OEM).
A Dealer user represents an OEM-affiliated organization that provides vehicle sales and workshop services.
An Independent user represents a non-OEM-affiliated organization offering aftermarket services for the vehicle.
An Owner user is the representative of the organization that owns the vehicle.
A Driver user is anyone operating the vehicle.
A Passenger user is anyone riding in the vehicle without driving it.

Application Roles

VISSv3 defines the following minimum set of roles for applications:

OEM
Third Party

An OEM application role is used for applications that are pre-installed in the vehicle by the OEM, or later OEM-provisioned to the vehicle.
A Third party application role is used for applications that are approved by automotive manufacturer for vehicle deployment, but developed by a third party.

Device Roles

VISSv3 defines the following minimum set of roles for devices:

Vehicle
Nomadic
Cloud

A Vehicle device role is one that is deployed within the vehicle, such as in the center stack ECU.
A Nomadic device role refers to a mobile device (e.g., smartphone or laptop) that connects to the vehicle via short-range communication (e.g., Bluetooth or Wi-Fi).
A Cloud device role is hosted outside the vehicle, typically in a data center, and connects to the vehicle via long-range communication, such as cellular networks.

Policy Documents

This section is non-normative.

The Policy documents are typically owned and created by the ecosystem manager. They MUST be handled securely to protect their integrity. The ecosystem manager SHALL securely provision them to the Access Token Servers in the access control ecosystem.

Purpose List

A client SHALL provide a purpose as input when requesting an access token. To support this, a predefined list of supported purposes MUST exist, allowing the client to select the purpose that matches its use case. The ecosystem manager SHALL provide a mechanism for clients to access and review this list.
Each entry in the purpose list includes the following:

A short description of the purpose, which the client uses as input when requesting an access token.
A long description, which MAY be used in consent dialogs when applicable.
A list of valid client context (i.e., combinations of user, app, and device roles) that may be granted access for this purpose.
A list of signals accessible under this purpose, along with the associated access permissions and any consent requirements.

The purpose list SHALL be formatted in JSON, as illustrated below:


        {"purposes":
            [{"short": "fuel-status",
            "long": "Fuel level and remaining range.",
            "contexts":[{"user":"Independent","app":["OEM", "Third party"], "device":"Cloud"}, {"user":"Owner", "app":"Third party", "device":"Nomadic"}, {"user":"Driver", "app":"OEM", "device":"Vehicle"}],
            "signal_access":
                [{"path": "Vehicle.Powertrain.FuelSystem.Level", "access_permission": "read-only"},
                {"path": "Vehicle.Powertrain.FuelSystem.Range", "access_permission": "read-only"}]
            },
            {}]
        }

The purpose list SHALL be securely provisioned to the Access Token Server. The provisioning protocol is out of scope for this specification. If the Access Token Server does not possess a valid purpose list, it MUST reject all access tokens requests.

Scope List

The Scope List defines the tree nodes to which access SHALL be prohibited for specific client context, regardless of whether the client possesses a valid access token.
In addition to access control, the scope list MAY also be used to restrict metadata visibility when a client sends a signal discovery request.
Each entry in the list contains:

A list of node paths to be excluded, and
A list of client contexts (i.e., sub-actor role triplets) for which this exclusion applies.

The scope list MAY include an entry for a context with all three Roles set to "Undefined". The no-access scope of this entry shall then be used for signal discovery requests where no token is included. An entry in the no_access array that addresses a branch results in no access to the subtree of this branch.
The scope list SHALL be formatted in JSON, as illustrated below:


        {"scope":
            [{"contexts":[ { "user":["Driver", "Passenger"], "app":"Third party", "device":"Vehicle"}, { } ],
            "no_access":
                ["Vehicle.Drivetrain.Transmission.Speed",
                "Vehicle.CurrentLocation.Latitude",
                "Vehicle.CurrentLocation.Longitude"]
            },
            {}]
        }

The scope list SHALL be securely provisioned to the Access Token Server. The provisioning protocol is out of scope for this specification. If the Access Token Server does not have access to a scope list, it SHALL NOT apply any scope restrictions for client context.

Access Control Selection

This section is non-normative. This section describes a complementary feature to the access control model: the ability to selectively apply access control to specific parts of the tree. This functionality is useful in cases where:

Not all nodes are considered to require access control, or
Write-only validation is sufficient instead of full read-write validation for certain nodes.

This functionality requires that the access token specifies whether the access permission granted to the client to a signal is read-only, or read-write. It also requires that the metadata for the node in the tree contains data specifying whether the access control verification should be carried out only for write request, or for both read and write requests.
The former requirement is realized as described in earlier sections by that the access token scope claim links to a purpose where the signals and their respective access permission are found.
The latter requirement is realized by adding to nodes in the tree the key-value pair "validate":'access-control-mode', where 'access-control-mode' is either the string "write-only", or "read-write".

The figure above shows an example where both read and write requests to the three leftmost leaf nodes will be access controlled, while the two rightmost leaf nodes only will be access controlled for write requests. An inheritance rule leads to that any nodes below a tagged node are assigned the same access control, if they are untagged.
This metadata is not likely to be applied to the publicly standardised tree, as different implementers of this standard may have different views on which nodes to apply it to. Instead it is anticipated that it is applied at a "deployment" stage, possibly using the VSS-Tools layering concept.
The inheritance model, which says that if access-control-mode data is added to a node, then all nodes in the subtree for which this node is the root inherits the setting, unless there is access-control-mode data added to any node in this subtree, makes possible a reduction of the number of nodes this metadata have to be added to.
This allows for example an entire tree to be assigned an access-control-mode by merely applying it in the root of the tree.
The figure below shows an overview of the access control selection model, and a table showing the required access control tagging of a node for the VISSv3 server to grant the requested access.

If the tree used by a VISSv3 server contains access control selection tags, the server MUST support their usage as described in this section.
If access control selection tags are not present, the server MAY implement access control for the entire tree.

JSON Schema

The primary payloads that are sent over any transport protocol SHALL conform with the JSON schema in this appendix, unless otherwise specified in the VISSv3 [[TRANSPORT]] or VISSv3 [[PAYLOAD ENCODING]] specifications.

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://covesa.global/vissv3.1.bundled.schema.json",
    "title": "VISSv3",
    "description": "VISS version 3.1 bundled schema",
    "type": "object",
    "properties": {
        "action": {
            "type": "string"
        }
    },
    "required": [
        "action"
    ],
    "oneOf": [
        {
            "properties": {
                "action": {
                    "const": "get"
                }
            },
            "$ref": "/vissv3.1/get-message.schema.json"
        },
        {
            "properties": {
                "action": {
                    "const": "set"
                }
            },
            "$ref": "/vissv3.1/set-message.schema.json"
        },
        {
            "properties": {
                "action": {
                    "const": "subscribe"
                }
            },
            "$ref": "/vissv3.1/subscribe-message.schema.json"
        },
        {
            "properties": {
                "action": {
                    "const": "unsubscribe"
                }
            },
            "$ref": "/vissv3.1/unsubscribe-message.schema.json"
        },
        {
            "properties": {
                "action": {
                    "const": "subscription"
                }
            },
            "$ref": "/vissv3.1/subscription-event.schema.json"
        }
    ],
    "$defs": {
        "https://covesa.global/vissv3.1/get-message.schema.json": {
            "$id": "https://covesa.global/vissv3.1/get-message.schema.json",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "title": "VISSv3-get-message",
            "description": "VISSv3 get request and response messages",
            "type": "object",
            "oneOf": [
                {
                    "properties": {
                        "path": {
                            "description": "The path",
                            "type": "string"
                        },
                        "filter": {
                            "$ref": "https://covesa.global/vissv3.1/filter.schema.json"
                        },
                        "authorization": {
                            "description": "The access token",
                            "type": "string"
                        },
                        "dc": {
                            "description": "The data compression scheme",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "path"
                    ]
                },
                {
                    "properties": {
                        "data": {
                            "$ref": "https://covesa.global/vissv3.1/data.schema.json"
                        },
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "data",
                        "ts"
                    ]
                },
                {
                    "properties": {
                        "metadata": {
                            "type": "object",
                            "description": "The metadata"
                        },
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "metadata",
                        "ts"
                    ]
                },
                {
                    "properties": {
                        "error": {
                            "$ref": "https://covesa.global/vissv3.1/error.schema.json"
                        },
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "error",
                        "ts"
                    ]
                }
            ]
        },
        "https://covesa.global/vissv3.1/set-message.schema.json": {
            "$id": "https://covesa.global/vissv3.1/set-message.schema.json",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "title": "VISSv3-set-message",
            "description": "VISSv3 set request and response messages",
            "type": "object",
            "oneOf": [
                {
                    "properties": {
                        "path": {
                            "description": "The path",
                            "type": "string"
                        },
                        "value": {
                            "description": "The value",
                            "$ref": "https://covesa.global/vissv3.1/value.schema.json"
                        },
                        "authorization": {
                            "description": "The access token",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        },
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        }
                    },
                    "required": [
                        "path",
                        "value"
                    ]
                },
                {
                    "properties": {
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "ts"
                    ]
                },
                {
                    "properties": {
                        "error": {
                            "$ref": "https://covesa.global/vissv3.1/error.schema.json"
                        },
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "error",
                        "ts"
                    ]
                }
            ]
        },
        "https://covesa.global/vissv3.1/subscribe-message.schema.json": {
            "$id": "https://covesa.global/vissv3.1/subscribe-message.schema.json",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "title": "VISSv3-subscribe-message",
            "description": "VISSv3 subscribe request and response messages",
            "type": "object",
            "oneOf": [
                {
                    "properties": {
                        "path": {
                            "description": "The path",
                            "type": "string"
                        },
                        "filter": {
                            "oneOf": [
                                {
                                    "$ref": "/vissv3.1/filter.schema.json"
                                },
                                {
                                    "type": "array",
                                    "items": {
                                        "$ref": "/vissv3.1/filter.schema.json"
                                    },
                                    "minItems": 1,
                                    "maxItems": 2
                                }
                            ]
                        },
                        "authorization": {
                            "description": "The access token",
                            "type": "string"
                        },
                        "dc": {
                            "description": "The data compression scheme",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "path",
                        "filter"
                    ]
                },
                {
                    "properties": {
                        "authorization": {
                            "description": "The access token handle",
                            "type": "string"
                        },
                        "subscriptionId": {
                            "description": "The subscription Id",
                            "type": "string"
                        },
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "subscriptionId",
                        "ts"
                    ]
                },
                {
                    "properties": {
                        "error": {
                            "$ref": "https://covesa.global/vissv3.1/error.schema.json"
                        },
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "error",
                        "ts"
                    ]
                }
            ]
        },
        "https://covesa.global/vissv3.1/unsubscribe-message.schema.json": {
            "$id": "https://covesa.global/vissv3.1/unsubscribe-message.schema.json",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "title": "VISSv3-unsubscribe-message",
            "description": "VISSv3 unsubscribe request and response messages",
            "type": "object",
            "oneOf": [
                {
                    "properties": {
                        "subscriptionId": {
                            "description": "The subscription Id",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "subscriptionId"
                    ]
                },
                {
                    "properties": {
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "ts"
                    ]
                },
                {
                    "properties": {
                        "error": {
                            "$ref": "https://covesa.global/vissv3.1/error.schema.json"
                        },
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "error",
                        "ts"
                    ]
                }
            ]
        },
        "https://covesa.global/vissv3.1/subscription-event.schema.json": {
            "$id": "https://covesa.global/vissv3.1/subscription-event.schema.json",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "title": "VISSv3-subscription-event",
            "description": "VISSv3 subscription event",
            "type": "object",
            "oneOf": [
                {
                    "properties": {
                        "subscriptionId": {
                            "description": "The subscription Id",
                            "type": "string"
                        },
                        "data": {
                            "$ref": "https://covesa.global/vissv3.1/data.schema.json"
                        },
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "subscriptionId",
                        "data",
                        "ts"
                    ]
                },
                {
                    "properties": {
                        "subscriptionId": {
                            "description": "The subscription Id",
                            "type": "string"
                        },
                        "error": {
                            "$ref": "https://covesa.global/vissv3.1/error.schema.json"
                        },
                        "ts": {
                            "description": "The time stamp",
                            "type": "string"
                        },
                        "requestId": {
                            "description": "The request id",
                            "type": "string"
                        }
                    },
                    "required": [
                        "subscriptionId",
                        "error",
                        "ts"
                    ]
                }
            ]
        },
        "https://covesa.global/vissv3.1/filter.schema.json": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "$id": "https://covesa.global/vissv3.1/filter.schema.json",
            "title": "VISSv3.1-filter",
            "description": "VISS version 3.1 filter",
            "type": "object",
            "properties": {
                "variant": {
                    "type": "string"
                }
            },
            "required": [
                "variant"
            ],
            "oneOf": [
                {
                    "properties": {
                        "variant": {
                            "const": "paths"
                        },
                        "parameter": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    },
                    "required": [
                        "parameter"
                    ]
                },
                {
                    "properties": {
                        "variant": {
                            "const": "timebased"
                        },
                        "parameter": {
                            "properties": {
                                "period": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "period"
                            ]
                        }
                    },
                    "required": [
                        "parameter"
                    ]
                },
                {
                    "oneOf": [
                        {
                            "properties": {
                                "variant": {
                                    "const": "range"
                                },
                                "parameter": {
                                    "type": "object",
                                    "properties": {
                                        "logic-op": {
                                            "type": "string",
                                            "enum": [
                                                "eq",
                                                "ne",
                                                "gt",
                                                "gte",
                                                "lt",
                                                "lte"
                                            ]
                                        },
                                        "boundary": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "logic-op",
                                        "boundary"
                                    ]
                                }
                            },
                            "required": [
                                "parameter"
                            ]
                        },
                        {
                            "properties": {
                                "variant": {
                                    "const": "range"
                                },
                                "parameter": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "logic-op": {
                                                "type": "string",
                                                "enum": [
                                                    "eq",
                                                    "ne",
                                                    "gt",
                                                    "gte",
                                                    "lt",
                                                    "lte"
                                                ]
                                            },
                                            "boundary": {
                                                "type": "string"
                                            },
                                            "combination-op": {
                                                "type": "string",
                                                "enum": [
                                                    "AND",
                                                    "OR"
                                                ]
                                            }
                                        },
                                        "required": [
                                            "logic-op",
                                            "boundary"
                                        ]
                                    },
                                    "minItems": 2,
                                    "maxItems": 2
                                }
                            },
                            "required": [
                                "parameter"
                            ]
                        }
                    ]
                },
                {
                    "properties": {
                        "variant": {
                            "const": "change"
                        },
                        "parameter": {
                            "properties": {
                                "logic-op": {
                                    "type": "string",
                                    "enum": [
                                        "eq",
                                        "ne",
                                        "gt",
                                        "gte",
                                        "lt",
                                        "lte"
                                    ]
                                },
                                "diff": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "logic-op",
                                "diff"
                            ]
                        }
                    },
                    "required": [
                        "parameter"
                    ]
                },
                {
                    "properties": {
                        "variant": {
                            "const": "curvelog"
                        },
                        "parameter": {
                            "properties": {
                                "maxerr": {
                                    "type": "string"
                                },
                                "bufsize": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "maxerr",
                                "bufsize"
                            ]
                        }
                    },
                    "required": [
                        "parameter"
                    ]
                },
                {
                    "properties": {
                        "variant": {
                            "const": "history"
                        },
                        "parameter": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "parameter"
                    ]
                },
                {
                    "oneOf": [
                        {
                            "properties": {
                                "variant": {
                                    "const": "metadata"
                                },
                                "parameter": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "parameter"
                            ]
                        },
                        {
                            "properties": {
                                "variant": {
                                    "const": "metadata"
                                },
                                "parameter": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                }
                            },
                            "required": [
                                "parameter"
                            ]
                        }
                    ]
                }
            ]
        },
        "https://covesa.global/vissv3.1/data.schema.json": {
            "$id": "https://covesa.global/vissv3.1/data.schema.json",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "title": "VISSv3-data-representation",
            "description": "VISSv3 data representation",
            "oneOf": [
                {
                    "type": "object",
                    "$ref": "/vissv3.1/data-object.schema.json"
                },
                {
                    "type": "array",
                    "items": {
                        "$ref": "/vissv3.1/data-object.schema.json"
                    }
                }
            ]
        },
            "https://covesa.global/vissv3.1/data-object.schema.json": {
                "$id": "https://covesa.global/vissv3.1/data-object.schema.json",
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "title": "VISSv3-data-object",
                "description": "VISSv3 data object",
                "properties": {
                    "path": {
                        "description": "The path",
                        "type": "string"
                    },
                    "dp": {
                        "description": "The data point",
                        "oneOf": [
                            {
                                "$ref": "/vissv3.1/datapoint.schema.json"
                            },
                            {
                                "type": "array",
                                "items": {
                                    "$ref": "/vissv3.1/datapoint.schema.json"
                                },
                                "minItems": 1
                            }
                        ]
                    }
                }
            },
            "https://covesa.global/vissv3.1/datapoint.schema.json": {
                "$id": "https://covesa.global/vissv3.1/datapoint.schema.json",
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "title": "VISSv3-datapoint",
                "description": "VISSv3 datapoint",
                "type": "object",
                "properties": {
                    "value": {
                        "description": "The value",
                        "$ref": "https://covesa.global/vissv3.1/value.schema.json"
                    },
                    "ts": {
                        "description": "The time stamp",
                        "type": "string"
                    }
                },
                "required": [
                    "value",
                    "ts"
                  ]
            },
            "https://covesa.global/vissv3.1/error.schema.json": {
                "$id": "https://covesa.global/vissv3.1/error.schema.json",
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "title": "VISSv3-error",
                "description": "VISSv3 error data",
                "type": "object",
                "properties": {
                    "number": {
                        "description": "The status code",
                        "type": "string",
                        "enum": [
                            "400",
                            "401",
                            "403",
                            "404",
                            "408",
                            "429",
                            "502",
                            "503",
                            "504"
                        ]
                    },
                    "reason": {
                        "description": "The reason",
                        "type": "string",
                        "enum": [
                            "bad_request",
                            "invalid_data",
                            "invalid_token",
                            "forbidden_request",
                            "unavailable_data",
                            "request_timeout",
                            "too_many_requests",
                            "bad_gateway",
                            "service_unavailable",
                            "gateway_timeout"
                        ]
                    },
                    "description": {
                        "description": "The access token",
                        "type": "string"
                    }
                },
                "required": [
                    "number",
                    "reason",
                    "description"
                ]
            },
            "https://covesa.global/vissv3.1/value.schema.json": {
                "$id": "https://covesa.global/vissv3.1/value.schema.json",
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "title": "VISSv3-value",
                "description": "VISSv3 value data",
                "oneOf": [
                    {
                        "type": "string"
                    },
                    {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "minItems": 1
                    },
                    {
                        "type": "object",
                        "patternProperties": {
                            ".*": {
		                "oneOf": [
		                    {
                                	"type": "string"
                                    },
                                    {
		                        "type": "object"
                                    }
                                ]
                            }
                        },
                        "minItems": 1
                    }
                ]
            }
    }
}

Server Capabilities

A client that intends to connect to a server may be interested in what capabilities the server offers. The server shall expose this information via a dedicated Server tree, which the client can access to discover supported optional features. However, for the client to retrieve 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 mechanisms 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

The Server tree MUST contain the structures listed below. Additional 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.

Below follows an example of a server capabilities tree.

#
# 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.Support.Encoding:
type: attribute
datatype: string[]
description: List of supported payload encoding features.

Server.Support.Filetransfer:
type: attribute
datatype: string[]
description: List of supported file transfer features.

Server.Support.DataCompression:
type: attribute
datatype: string[]
description: List of supported data compression 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.Mqtt.Protobuf.DataCompression:
type: attribute
datatype: string[]
description: List of supported data compression variants.

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.Protocol.UDS:
type: branch
description: Top branch for the server supported Unix Domain Socket protocol.

Server.Config.Protocol.UDS.Socket:
type: attribute
datatype: string
description: UDS socket file path.

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.

A feature that is supported in at least one configuration shall be registered on the Support branch. The Config branch shall contain the information needed for a client to utilize the feature, for all configurations that has the feature supported. If a server e. g. supports file transfer upload and download then this shall be found at the Support branch, and then on the Config branch it shall be registered for which transport protocol(s) it is supported, and e. g. which port number is then used. Configuration data that is given a value in the specification documents does not have to be present on the Config branch.

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.

Protocol	Description
ws	[[TRANSPORT]], Transport Protocols: section 5.1 Secure WebSocket
http	[[TRANSPORT]], Transport Protocols: section 5.2 HTTPS
mqtt	[[TRANSPORT]], Transport Protocols: section 5.3 MQTT
grpc	[[TRANSPORT]], Transport Protocols: section 5.4 gRPC
uds	[[TRANSPORT]], Transport Protocols: section 5.5 Unix Domain Sockets

Filter	Description
timebased	Time-based event trigger condition
change	Change-based event trigger condition
paths	Multiple signal paths
range	Range-based event trigger condition
curvelog	Curve logging-based event trigger condition
history	Historic data access
metadata	Metadata access

File transfer	Description
download	File download to vehicle
upload	File upload to client

Data compression	Description
pathuid	Static UID path compression
pathlocal	Request local path compression
timestamplocal	Response local timestamp compression

Security	Description
accesscontrol	Access control
consent	Consent

Access Control Flow	Description
short_term	Short term access flow
long_term	Long term access flow
signalset_claim	Signal set claim

File Transfer

This appendix is non-normative.
File transfer use cases, where a client either sends or receives a file from the vehicle server, can e. g. be a client that wants to push a map to the vehicle (download), or a client that wants to receive a video recording clip from the vehicle (upload).
File resources represented in the tree can either be read-only, represented by the sensor node type, or write-only, represented by the actuator node type. In either case the node datatype MUST be a reference to a struct datatype with the following fixed definition:


          typedef FileDescriptor struct {
              name string
              hash string
              uid string
          }

The FileDescriptor name member SHALL have a dot separated file extension that identifies the file format.
The FileDescriptor hash member SHALL be a SHA-1 hex string encoded hash calculated on the content of the file.
The FileDescriptor uid member SHALL be a hex string encoded random uint32 value. Its value shall be unique for each file transfer session, created by the client for download sessions, and by the server for upload sessions.

File transfer from client to server, or in the other direction, follows the model shown in the two sequence diagrams below. The server exposes two communication channels, a control channel and a data channel. The control channel is the channel where the primary VISSv3.1 payloads are communicated, while the data channel is a channel over which the file transfer data is communicated. As is seen in the sequence diagrams the messages sent on the data channel have the same structure in both the download and upload sequences, but interchanged between the client and the server.
The file transfer data message consists of the data from the file, split into appropriate size chunks, and prepended by a header.
The file transfer status message consists of the uid and messageNo from the received data message, together with the status of the reception of that data message.
The header in the data message consists of the fixed size parameters shown in the list below.

uid: 4 bytes. A unique identifier for this file transfer session.
messageNo: 1 byte. Starting at zero and increasing by one for each file chunk that is transferred. Maximum value is 254.
file chunk size: 4 bytes. The size in bytes of this message, including the header size.
lastMessage: 1 byte. Indiates whether this message is the last message in the transfer of this file. The value zero indicates that this is not the last message, while a non-zero value indicates that it is the last message.

The status message consists of the fixed size parameters shown in the list below.

uid: 4 bytes. The identifier from the received message.
messageNo: 1 byte. The message number from the received message.
status: 1 byte. Indiates whether the message was correctly received or not. The value zero indicates that it was correctly received, while a non-zero value indicates that it was not. The value 255 is a request for immediate termination of the file transfer session.

The client SET request on the control channel is exemplified below in the primary payload format.


{
  "action": "set",
  "path": "Vehicle.Cabin.Infotainment.privateMap",
  "value": {
    "name": "privateMap.kml",
    "hash": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
    "uid": "2d878213"
  }
}

The Ok response would in primary payload format look like:


{"action": "set", "ts": "2024-08-20T11:30:00Z"}

If the SET request on the control channel receives an error message then the client shall not issue any SET requests on the data channel.
The client data message on the data channel consists of a concatenation of the header and the file chunk. The server responds to this with a status message.
If the client data message receives an error status response then the client shall resend the data message with the corresponding message number. If this results in another error response for the same message number the client may terminate the download session. If the status value is set to 255 the client shall immediately terminate the file download session.

The server GET request on the control channel is exemplified below in the primary payload format.


        {"action": "get", "path": "Vehicle.Cabin.DashCam.Clip"}

The Ok response would in primary payload format look like:


        {
          "action": "get",
          "data": {
            "path": "Vehicle.Cabin.DashCam.Clip", 
            "dp" {
              "value": {"name": "dashCamClip.mp4", "hash": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed", "uid": "2d878213"},
              "ts": "2024-08-20T11:30:00Z"
            }
          },
          "ts": "2025-01-09T12:13:14Z"
        }

If the GET request on the control channel receives an error message then the client shall not start the file upload session on the data channel by issuing the initial status message.
The client must issue an initial status message to trigger the server to respond with the first data message, in this first status message the message number is set to 255. The data message from the server following this status message shall have the message number zero. The client shall send a final status message after receiving the last data message from the server. If the status is set to zero the server shall respond with only the header from its last message, with the chunk size set to zero, thus terminating the file upload session.
If the server data message receives an error status response then the server shall resend the data message with the corresponding message number. If this results in another error response for the same message number the server may terminate the download session. If the status value is set to 255 the server shall immediately terminate the file download session.

The receiver of the file should calculate the hash on the received data after the session is concluded and compare with the file hash value received on the control channel. If they differ the received file is likely corrupt.

The sender of the file may terminate the file transfer session on the data channel by sending only the header by setting the message number to 255, the chunk size to zero, and the last message to non-zero, on which the receiver shall respond with status set to zero.

The node type for the file resource MUST be "actuator" for the download case and "sensor" for the upload case. This node must have a fixed datatype, a struct with the members "name", "hash", and "uid".
Examples of tree nodes for file download and upload, respectively:


        DownloadFile:
          type: actuator
          datatype: Types.Resources.FileDescriptor
          description: File that may be downloaded to the vehicle.

        UploadFile:
          type: sensor
          datatype: Types.Resources.FileDescriptor
          description: File stored at the vehicle that may be uploaded to a client.

The Types.Resources.FileDescriptor definition in the Types tree must mirror the struct definition above.

Data channel realization

If file transfer is realized over any supported transport protocol, this must then be shown in the server capabilities tree, together with the information needed for a client to access the data channel. The default mechanism for realizing a data channel is to assign a port number for it. The list below shows the recommended port numbers for the HTTP and WebSocket protocols.

HTTP port number: 445
WebSocket port number: 6445

The recommended mechanism for MQTT is to assign a separate topic name to the data channel. The recommended topic name is created by appending "/datachannel" to the topic name of the control channel.

Alternative based on well-known file transfer protocols

There exists a number of common file transfer protocols e. g. ftp, sftp, ftps, and scp which are widely adopted and have been optimized over many years. For larger files these may be a more efficient solution than the integrated VISS protocol. The model for using any of these instead builds on that the client can access the needed informattion to connect to the end point that is offering the use of the file transfer protocol to access the file. This information is available as a struct data point of the tree node. This struct should have members similar to what is shown below, depending on what is required to initiate he file transfer.


          struct {
              schema string
              port uint32
              path string
              filename string
          }

Schema is the file transfer protocol schema.
Port is the port number for this service, at least for the initial setup.
Path is the URL path for this service.
Filename is the file name of the file to be transferred. It shall include a file extension that defines the format of the file.
The node type of this tree node shall be "sensor" for files that can only be uploaded to a client, and "actuator" for the file download case.
Information about the vehicle file system structure, such as the file path information, shall not be exposed to the client. The server may use the path as a key into a lookup table for accessing the file in the vehicle file system.

Data Compression

This appendix is non-normative. The primary payload format is JSON, which is text based and thus may lead to large messages in terms of bytes. Particularly in subscription scenarios with large number of event messages that are sent off-vehicle this is an undesireable feature as the transportation cost may be significant. The payload encoding that is supported in this specification provides one possibility of compressing the message size, but it does typically not take advantage of specific knowledge of the data being transported. The data compression described here does so, as will be described in the following. This compression can typically also be combined with a following payload encoding compression step. The compression scheme is assymmetric in that it is applied to the response data from the server, but not to the client requests. The assumption is that this is where it may have the largest impact, particularly in the case of multiple responses on a subscribe request. It is also applied per request by an optional parameter that can be included in the Read or Subscribe requests, having the following format.


          "dc": "A+B"

The expression A+B instructs the server what compression scheme it shall apply to paths and/or timestamps in its response(s) to this request. This expression must consist of two values separated by a plus sign, "A + B", where the first value A represents which path compression that is selected, and the second value B represents which timestamp compression that is selected. The value 0 means that no compression scheme is selected, values 1, 2, 4, or 8 represents the compression scheme associated with bits no 0, 1, 2, or 3 in the figure below.

Consent architecture. — Data compression scheme coding.

The bits shown in the figure above are assigned to the data compression schemes shown in the list below and described in the following sections.
For path compression:

Bit 0: Static UID path compression.
Bit 1: Request local path compression.
Bit 2-3: Reserved for other path compression schemes.

For timestamp compression:

Bit 0: Request relative timestamp compression.
Bit 1-3: Reserved for other timestamp compression schemes.

Refer to the following sections for description of the supported compression schemes.
If the server supports data compression it SHALL declare the compression schemes it supports in its server capabilities tree with an expression A+B where A and B are the sum of the values representing the supported schemes, respectively.
If a client request for data compression is not supported, or impossible to realize, the server shall respond with an error message.

Static UID Path Compression

To enable the server to support this path compression the tree must include the static UIDs for each node. The VSS-Tools exporter tools can be used to assign a static UID to each tree node as described here.
The server will then in the response message(s) replace the path with the static UID value. The static UID is represented as a hex value string starting with the characters "0x" then followed by 8 hexadecimal values. The client needs to obtain means for decoding the static UIDs into corresponding paths, see the VSS-tools description.
The server shall respond with an error message if the client applies the path compression in its request.

Request Local Path Compression

The principle for request local path compression is that the server will in the response message(s) replace the path(s) with an integer index. In the case that the request only contains one path reference, then the index is always set to zero. For requests that reference more than one path via the usage of the paths filter, the first response from the server will contain the paths uncompressed, but any following responses will replace the paths with an index. The value of the index is then assigned according to a sorted list of the paths included in the first response, i. e. the first path in the sorted list is assigned the value zero, the second the value 1, and so on. The index logically represent an integer value but it is in the message payload represented as a string.

Request Relative Timestamp Compression

The request relative time stamp compression builds on that response messages always contain a timestamp that represent the time when the response message was issued by the server. This timestamp will then be the base time that the timestamps for the data point(s) in the response will contain an offset to. This offset will be represented as an integer representing milliseconds, prepended with a plus (+) or minus (-) sign. The uncompressed ISO8601 based timestamp contains 24 characters, so for very large offset values leading to low compression rates the server may decide to keep the uncompressed timestamp. The client will be able to analyze whether it is a compressed timestamp or not by examining the first character of the string. If it is an integer it is an uncompressed timestamp, as the compressed timestamps starts with a plus or a minus character.

Sequence Diagram Compression Scheme Examples

The sequence diagram below shows client Get requests for the vehicle speed signal where different combinations of compression schemes are used. The responses mainly show the paths or timestamps that becomes compressed. In the first request/response the client requests static UID path compression, in the second request local path compression, and in the third and fourth request relative timestamp compression is added together with the respective path compression.

Compression scheme sequence diagram. — Data compression scheme sequence diagram.

An example with the complete payloads for a subscribe on two signals with path and timestamp compression are shown below. The first payload is the request, the second is the response, then follows the two first event messages.


{"action":"subscribe","path":"Vehicle.CurrentLocation","filter":[{"variant":"paths","parameter":["Latitude", "Longitude"]}, {"variant":"timebased","parameter":{"period":"3000"}}], "dc":"2+1","requestId":"286"}

{"action":"subscribe","requestId":"286","subscriptionId":"1","ts":"2025-01-10T11:46:09.955Z"}

{"action":"subscription","data":[{"dp":{"ts":"-123","value":"56.02"},"path":"Vehicle.CurrentLocation.Latitude"},{"dp":{"ts":"-123","value":"12.36"},"path":"Vehicle.CurrentLocation.Longitude"}],"subscriptionId":"1","ts":"2025-01-10T11:46:12.957Z"}

{"action":"subscription","data":[{"dp":{"ts":"-15","value":"56.03"},"path":"0"},{"dp":{"ts":"-15","value":"12.37"},"path":"1"}],"subscriptionId":"1","ts":"2025-01-10T11:46:15.956Z"}

Introduction

Terminology

Definitions

Data Model

Addressing

Authority URI Component

IP address / domain name

Port number

Path URI Component

Data representation

Interface

Methods

Read

Update

Subscribe

Unsubscribe

Subscription

Error Message

Error Information

Timestamps

Security Considerations

Transport security

Data security

Privacy Considerations

Filter Request

Paths Filter Operation

History Filter Operation

Time-Based Filter Operation

Range Filter Operation

Single Boundary Range

Multi Boundary Range

Change Filter Operation

Curve logging Filter Operation

Metadata Filter Operation

Forest Inquiry

Multiple Signals Request

Error Handling

Response syntax

Subscription Event Triggering

Access Control Model

Architecture

Protocol Flows

Protocol Messages

Access Grant Request

Access Grant Response

Access Token Request

Initial Access Token Request

Inquiry Access Token Request

Access Token Response

Access Token Response — Consent Not Required

Access Token Response — Consent Required

Access Token Response To Initial Access Token Request

Access Token Response To Inquiry Access Token Request

Protected Resource Request

Protected Resource Response

Actors

Client

Access Grant Token Server

Access Token Server

Access Control Server

Resource Owner

Ecosystem Manager

Credentials

Client Authentication

Access Grant Token

Short-Term Access Grant Token

Long-Term Access Grant Token

Access Token

Proof of Possession

Client Context

User Roles

Application Roles

Device Roles

Policy Documents

Purpose List

Scope List

Access Control Selection

Consent support

External Consent Framework Interface

JSON Schema