Vehicle Signal Catalogs

The Metrics Configuration Generator (MCG) validates metrics configurations by checking signal names, performing type checking on expressions, and inferring output types. MCG needs access to protocol buffer (protobuf) message definitions for vehicle signals to perform these tasks.

In SDV, vehicle signals and services are defined using Vehicle Service Interface Definition Language (VSIDL). VSIDL uses protobuf files to specify messages, and these protobuf files form the basis of a signal catalog.

To make signal definitions available to MCG, you must package these VSIDL protobuf files into a protobuf FileDescriptorSet and upload it to the MCG service. MCG uses the term Vehicle Signal Catalog for these uploaded and versioned definition sets (essentially making a Vehicle Signal Catalog the compiled, uploaded form of the proto message definitions in your VSIDL catalog).

What is a Vehicle Signal Catalog?

A Vehicle Signal Catalog provides MCG with signal definitions for validation, packaged as a protobuf FileDescriptorSet.

In MCG, catalogs are identified by a version string that you assign during upload, which lets you manage multiple distinct signal definition sets. For example, you might maintain different catalog versions for software releases (v1.0, v1.1, v2.0), or for different vehicle models or hardware configurations (suv-my2025, sedan-my2025). Each metrics configuration uses the vs_version field to reference a specific catalog, which defines the signals that are available as data sources and provides signal definitions for type inference and validation.

Create an instance of FileDescriptorSet

As described in Define messages and RPC services, vehicle signals are defined as protobuf messages in protobuf files. If you're part of an SDV project, use the protobuf files from your project's VSIDL catalog to create an instance of FileDescriptorSet.

To create a catalog for MCG, bundle your protobuf files into a FileDescriptorSet binary file using protoc.

If all your protobuf files are in one folder, run the following command to generate vehicle_signals.pb:

protoc --include_imports --descriptor_set_out=vehicle_signals.pb <var label="path to folder with .proto files">path/to/your/protos</var>/*.proto

Upload and manage catalogs

Uploading your signal definition set as a catalog lets you reference it by version name in metrics configuration requests.

Add or update a catalog version

After generating the vehicle_signals.pb catalog file, you can upload and manage it using the MCG API endpoints under /api/v1/vs/. The endpoint for adding or updating a catalog, POST /api/v1/vs/, requires the FileDescriptorSet to be passed as a base64-encoded string in the JSON payload.

To encode vehicle_signals.pb for API use, use the base64 command. The -w 0 flag disables line wrapping so that the encoded string appears on a single line:

VEHICLE_SIGNALS_BASE64=$(base64 -w 0 vehicle_signals.pb)

To upload vehicle_signals.pb as a new version (for example, v1.0) or to update an existing version, send a POST request with the base64-encoded content to the /api/v1/vs/ endpoint with a unique version name.

The request body must be a JSON object containing the version string and the base64-encoded vehicle_signals string:

{
  "version": "v1.0",
  "vehicle_signals": "Q2lSb1pYB3jCRkRt..."
}

The following example shows how to upload vehicle_signals.pb as version v1.0 using curl. The example uses printf to construct the JSON payload and pipes it to curl, which avoids the need to create a JSON file containing a very long single-line base64 string:

# 1. Encode the FileDescriptorSet to a Base64 string
VEHICLE_SIGNALS_BASE64=$(base64 -w 0 vehicle_signals.pb)

# 2. Define catalog version and build JSON payload
VERSION="<var label="catalog version">v1.0</var>"
JSON_PAYLOAD=$(jq -n --arg v "$VERSION" --arg d "$VEHICLE_SIGNALS_BASE64" \
  '{version: $v, vehicle_signals: $d}')

# 3. POST the data to the API endpoint
echo "$JSON_PAYLOAD" | curl -H "Content-Type: application/json" --data-binary @- "$SERVICE_URL/api/v1/vs/"

List and delete versions

You can list all available catalog versions or delete a specific version:

  • List versions: To see a list of identifiers for all uploaded catalog versions, send a GET request to /api/v1/vs/. See GET /api/v1/vs/.

  • Delete a version: To remove a catalog, send a DELETE request to /api/v1/vs/{version}, where {version} is the identifier provided when the catalog was uploaded (for example, v1.0). See DELETE /api/v1/vs/{version}.

For full details on all endpoints, see the API Reference.

Use a catalog in metrics configurations

When uploaded, reference a catalog version in metrics configurations using the vs_version field:

{ "vs_version": "v1.0", ... }

When this JSON object is sent to the /api/v1/generate_metrics_config or /api/v1/validate_metrics_config endpoints, MCG uses the signal definitions from the v1.0 catalog to perform validation and type inference.