What is the schema for exchange variables?

[kezike]

What is the schema for exchange variables? I have seen examples where the keys are the step name (e.g., variables[exchange.step].results.verifiablePresentation) and I have seen other examples where the keys are something else (e.g., results) and the values are step-scoped data (e.g., variables.results[exchange.step].verifiablePresentation).

[dlongley]

We should clarify what pieces of this should be considered standard (i.e., every implementation must implement in a specific way). At present, the only restriction on variables is for it to be an object, but given that implementations have used it to also store step results to allow template access to the result of any other step, we should probably reserve the results key and define it in a particular way for interoperability.

If we do that, we would say that results is reserved and, if used, it is an object with step names as keys and the exchange server sets the result of each step (e.g., {verifiablePresentation, ...}) as the value. The other properties could be left up to implementations to use as desired.

Another option would be to store results in another place and allow implementations to merge it into variables for template processing, but this just seems like it would be de facto reserving some property that would be overwritten (probably results) in the variables object to enable implementations to do this anyway.

We could also reserve some other top-level property in variables to allow for future expansion of the spec w/any other implementation-common features. We might consider whether to move results underneath that property, considering backwards compatibility concerns with existing implementations.

[kezike]

Yes, that would be good to clarify, as well as errors, which I have seen stored in variables under the scope of a step as error/errors. Perhaps, that also belongs under results? Don't have a strong opinion on this at the moment, but just wanted to call it out as another field I have seen used in variables.

[msporny]

The group talked about this on the 2025-02-18 telecon. @dlongley noted that we might want to reserve some key names underneath the variables object. The current YAML states the following:

variables:
  type: array
  description: Template variables to be used in the exchange.
  items:
    type: object
    properties:
      type:
        type: string
        description: The type of template.
      template:
        type: string
        description: The template itself.

... which is wrong. The variables.type should be an object, not an array. Each item is wrong as well. It should be something closer to the following (no strong schema/typing necessary):

variables:
  type: object
  description: Template variables to be used in the exchange.

Should we preserve some key names like results so they're common across implementations?

A PR should be raised that allows variables to be a free form object. It's too early to preserve key names like results.