FAQ: Adaptive Card schema version supports in Web Chat

[compulim]

Web Chat bundles with the latest version of Adaptive Cards JavaScript SDK (below, Adaptive Cards SDK). Different version of Adaptive Cards SDK has a different range of schema versions they support.

This FAQ will answer questions around versioning of Web Chat, Adaptive Cards SDK, and Adaptive Cards schema.

However, as Web Chat and Adaptive Cards are different teams, we ship at a different release cycle. There are steps needed to find out what schema version of Adaptive Cards is supported in a specific version of Web Chat.

The version of Adaptive Cards SDK does not directly represent the Adaptive Cards schema version. In this article, we will outline steps that need to find out the version, from Web Chat, to Adaptive Cards SDK, then to Adaptive Cards schema.

What is the maximum schema version of Adaptive Cards supported by a specific version of Web Chat?

To find the maximum schema version of Adaptive Cards supported by Web Chat:

1. Read the CHANGELOG.md of Web Chat
2. Search the keyword "adaptivecards", write down the version
3. Go to Adaptive Cards SDK page
4. In the "New policy versioning" section, match the Adaptive Cards SDK version, read the "Can parse from schema versions"

This is the maximum schema version that is supported by a specific version of Web Chat.

Using Web Chat 4.15.0 as an example:

1. Read the CHANGELOG.md of Web Chat 4.15.0
2. Searching the keyword yielded adaptivecards@2.10.0, this is Adaptive Cards SDK 2.10.0
3. Read the Adaptive Cards SDK page
4. The "New policy versioning" section says Adaptive Cards SDK version 2.10 can parse from schema versions of 1.0 ... 1.5

So, Web Chat 4.15.0 can parse up to Adaptive Cards schema 1.5.

What is the default schema version of Adaptive Cards supported by a specific version of Web Chat?

Although Adaptive Cards SDK page says they can parse up to a specific version, the Adaptive Cards SDK may default to an older version of schema. This behavior is entirely controlled by the Adaptive Cards team.

To find the default schema version of an Adaptive Cards SDK:

1. Go to the release page of Adaptive Cards project
2. Search the keyword "Latest Packages" and look for the "JavaScript" version, match the release with the Adaptive Cards SDK you are looking for
3. Click the tag icon on the left of the release
4. Under the source code of Adaptive Cards, browse to this file, source/nodejs/adaptivecards/src/serialization.ts
5. Search the keyword export class Versions
6. Look at the field latest

This is the default schema version that is supported by a specific version of an Adaptive Cards SDK.

Using Web Chat 4.15.0 as an example. In former section, we already know Web Chat 4.15.0 is using Adaptive Cards SDK 2.10.0.

1. Read the release page of Adaptive Cards project
2. Searching the keyword yielded "JavaScript 2.10.0" under this release
3. The tag icon on the left "21.09", click on it will navigate to this commit tag
4. Browse to the file at source/nodejs/adaptivecards/src/serialization.ts
5. Searching the keyword will reach line 105
6. On line 112, latest = Versions.v1_5

When using Web Chat 4.15.0, by default, it will parse Adaptive Cards with schema version up to 1.5.

I cannot use Adaptive Cards x.y in Web Chat

First, find out the version of Web Chat you are using. In your browser, press F12 to open Developer Tools and paste in the following code. It will print out the version.

[].map.call(document.head.querySelectorAll('meta[name^="botframework-"]'), function (meta) { return meta.outerHTML; }).join('\n')

If you are using <iframe>, you can look for <meta> tags in your page that contains Web Chat, then look for one with name attribute of botframework-webchat:bundle:version. The content attribute should contains the version number.

Then, follow the questions above to find out the "default schema version of Adaptive Cards" supported by the version of Web Chat you are using.

How can I specific another schema version in Web Chat?

When rendering Web Chat, you can pass styleOptions.adaptiveCardsParserMaxVersion prop to select a different version to parse the Adaptive Cards. This version number could be as high as the "Can parse from schema version" as specified by Adaptive Cards SDK.

If the Adaptive Cards schema version you want to use is not supported by the version of Adaptive Cards SDK bundled in Web Chat, you can bring-your-own Adaptive Cards SDK.

Can I use another version of Adaptive Cards SDK in Web Chat?

Yes, you can bring-your-own Adaptive Cards SDK into Web Chat.

Given the SDK you are bringing shares a compatible API as the version bundled by Web Chat, you can bump to a latter or former version of Adaptive Cards SDK.

You can pass the whole Adaptive Cards SDK package into Web Chat through the adaptiveCardsPackage prop.

import * as MyAdaptiveCardsPackage from 'adaptivecards';
import ReactWebChat from 'botframework-webchat';

ReactDOM.render(
  <ReactWebChat
    adaptiveCardsPackage={MyAdaptiveCardsPackage}
    ...
  />,
  ...
);

I think there are improvements to Adaptive Cards SDK that are beneficial to many web developers using Web Chat

Web Chat always bumps to the latest version of Adaptive Cards SDK in our early development cycle.

When we are releasing Web Chat in late development cycle, Adaptive Cards team might have released a newer version of their Adaptive Cards SDK.

Please file an issue if you think there are significant amount of improvements in the Adaptive Cards SDK that taking a newer version will be beneficial to many web developers using Web Chat.

As the version bump could disrupt our development cycle, we will evaluate on a per-request basis.

I have other issues about Adaptive Cards

Please file an issue and we will address them.

[Question]