Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Schema.org Claim to Direct Line Activity spec #6612

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Add Schema.org Claim to Direct Line Activity spec #6612

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 38 additions & 15 deletions specs/botframework-activity/botframework-activity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -432,7 +432,7 @@ The `importance` field contains an enumerated set of values to signal to the rec
The `deliveryMode` field contains any one of an enumerated set of values to signal to the recipient alternate delivery paths for the activity or response. The value of the `deliveryMode` field is of type string, with defined values of `normal`, `notification` and `expectReplies`. The default value is `normal`.

Activities with a `deliveryMode` of `expectReplies` differ only in their requirement to return a response payload back to the caller synchronously, as a direct response to the initial request.

`A3110`: If a sender includes the `deliveryMode` field, it SHOULD only send defined values.

`A3111`: Receivers SHOULD interpret undefined values as `normal`.
Expand All @@ -445,7 +445,7 @@ Activities with a `deliveryMode` of `expectReplies` differ only in their require

`A3115`: Senders MUST establish whether a receiver understands `deliveryMode` of `expectReplies` prior to sending activities with that value.

`A3116`: Bots SHOULD NOT send activities with `deliveryMode` of `expectReplies` to channels.
`A3116`: Bots SHOULD NOT send activities with `deliveryMode` of `expectReplies` to channels.

### Listen for

Expand Down Expand Up @@ -753,7 +753,7 @@ Handoff activities are identified by a `type` value of `handoff`.

## Command activity

Command activities communicate a request to perform a specific action. They are identified by a `type` value of `command` and specific values of the `name` field.
Command activities communicate a request to perform a specific action. They are identified by a `type` value of `command` and specific values of the `name` field.

Commands look similar in structure to events but have different semantics. Commands are requests to perform an action and receivers typically respond with one or more commandResult activities. Receivers are also expected to explicitly reject unsupported command activities.

Expand Down Expand Up @@ -781,23 +781,23 @@ The recommended patterns for rejecting command activities are included in [Appen

The `value` field contains the command metadata and parameters specific to a command, as defined by the command `name`. The `value` field is a complex object of the [command value](#command-value) type.

`A6321`: Command activities MUST contain a `value` field.
`A6321`: Command activities MUST contain a `value` field.

`A6322`: Receivers MUST ignore command activities with missing or invalid `value` field.

## Command result activity

Command result activities communicate the result of a [command activity](#command-activity).
Command result activities communicate the result of a [command activity](#command-activity).

Command result activities are identified by a `type` value of `commandResult` and specific values of the `name` field. The `name` field of a command result is always set to the `name` of the original command activity.
Command result activities are identified by a `type` value of `commandResult` and specific values of the `name` field. The `name` field of a command result is always set to the `name` of the original command activity.

`A6400`: Senders MAY send one or more command result activities to communicate the result of the command.

### Name

The `name` field defines the meaning of the command result activity. The value of the `name` field is of type string.

`A6411`: Command result activities MUST contain a `name` field.
`A6411`: Command result activities MUST contain a `name` field.

`A6412`: Receivers MUST ignore command activities with missing or invalid `name` field.

Expand All @@ -807,7 +807,7 @@ The `name` field defines the meaning of the command result activity. The value o

The `value` field contains the command metadata and additional information specific to a command result, as defined by the command result `name`. The value of the `value` field is a complex object of type [command result value](#command-result-value) type.

`A6421`: Command result activities MUST contain a `value` field.
`A6421`: Command result activities MUST contain a `value` field.

`A6422`: Receivers MUST reject command result activities with missing or invalid `value` field.

Expand Down Expand Up @@ -1431,7 +1431,7 @@ The `data` field contains optional parameters specific to this command activity,
`A10201`: Extensions to the command activity SHOULD NOT require receivers to use any information other than the activity `type` and `name` fields to understand the schema of the `data` field.

### Command result Value
The `value` field of a [command result activity](#command-result-activity) contains metadata related to a command. An optional extensible `data` payload may be included if defined by the command result activity `name`. The presence of an `error` field indicates that the original command failed to complete.
The `value` field of a [command result activity](#command-result-activity) contains metadata related to a command. An optional extensible `data` payload may be included if defined by the command result activity `name`. The presence of an `error` field indicates that the original command failed to complete.

#### Command Id

Expand All @@ -1441,7 +1441,7 @@ The `value` field of a [command result activity](#command-result-activity) conta

The `data` field contains optional additional information specific to this command result activity, as defined by the `name`. The value of the `data` field is a complex type.

`A11200`: The `data` field MAY be missing or empty, if defined by the command result activity name.
`A11200`: The `data` field MAY be missing or empty, if defined by the command result activity name.

`A11201`: Extensions to the command result activity SHOULD NOT require receivers to use any information other than the activity `type` and `name` fields to understand the schema of the `data` field.

Expand Down Expand Up @@ -1477,6 +1477,9 @@ The `error` field contains the reason the original [command activity](#command-a

# Appendix I - Changes

## 2023-09-22 - [email protected]
* Added [Schema.org Claim](#schema-org-claim) type definition

## 2020-07-07 - [email protected]
* Fix the broken link to the Bot Framework Manifest Spec in the References section

Expand Down Expand Up @@ -1571,6 +1574,7 @@ Activity [entities](#entity) communicate extra metadata about the activity, such
| string | N/A | String |
| number | N/A | Number |
| clientInfo | N/A | Skype client info |
| Claim | https://schema.org/Claim | Schema.org Claim |

### string and number

Expand Down Expand Up @@ -1616,6 +1620,26 @@ Note that on channels with a persistent chat feed, `platform` is typically usefu

`A9230`: Bots SHOULD NOT use the `platform` field to control how response data is formatted unless they have specific knowledge that the content they are sending may only ever be seen on the device in question.

#### Schema.org Claim

A response may sometimes contains references to other work to support facts claimed in the message. These references provide transparency to human users. Human users may use these references to understand system's intended uses, interpret relevant system behavior effectively, and remain aware of the possible tendency of over-relying on outputs produced by the system.

When a reference is not fully accessible by the user, the bot can use [Schema.org Claim](https://schema.org/Claim) to include full or partial text from the original work. The claim is an extension to the activity and must not be cross-referenced from another activity.

Channels decide how the referenced content can be displayed in their user experience. In most cases, contents should be shown in a separate pane, popover, or dialog. In cases where the channel has limited capability to display the content, the channel may use an alternative channel (e.g. a link to a website, or sending the content via email).

`A9240`: The entity MUST include a `type` field, with value of `https://schema.org/Claim`.

`A9241`: The entity MUST include an `@context` field, with value of `https://schema.org`.

`A9242`: The entity MUST include an `@type` field, with value of `Claim`.

`A9243`: The entity SHOULD include an `@id` field, with value of type IRI unique to the activity and referenced in the message `text` field.

`A9244`: The entity MUST include a `text` field of type string, containing full, excerpted, or summarized text from the original work.

`A9245`: The entity MAY include a `name` field of type string.

# Appendix III - Protocols using the Invoke activity

The [invoke activity](#invoke-activity) is designed for use only within protocols supported by Bot Framework channels (i.e., it is not a generic extensibility mechanism). This appendix contains a list of all Bot Framework protocols using this activity.
Expand Down Expand Up @@ -1697,21 +1721,21 @@ The authenticity of a call from a bot can be established by inspecting its JSON
# Appendix VI - Protocols using the Command activity
[Command activities](#command-activity) communicate a request to perform a specific action. Command activities outside the `application` are considered reserved for Bot Framework Protocols. This appendix contains a list of command activities used in Bot Framework protocols and recommended patterns for defining and using command activities.

## Telephony Channel
## Telephony Channel

The Microsoft Telephony channel defines channel command activities in the namespace `channel/vnd.microsoft.telephony.<action>`.
The Microsoft Telephony channel defines channel command activities in the namespace `channel/vnd.microsoft.telephony.<action>`.

## Patterns for rejecting commands

### General pattern for rejecting commands
The general pattern for rejecting commands is to send an asynchronous commands result with an error. This is used in most cases when the receiver needs to process the command before rejecting it.
The general pattern for rejecting commands is to send an asynchronous commands result with an error. This is used in most cases when the receiver needs to process the command before rejecting it.

Here is an example of a command result indicating that the command was not supported by the receiver:
```
{
'type': 'commandResult'
'name': 'channel/vnd.microsoft.telephony.<action>'
'value': {
'value': {
'error' : {
'code': 'NotSupported',
'message' : 'Command channel/vnd.microsoft.telephony.<action> is not supported'
Expand All @@ -1722,4 +1746,3 @@ Here is an example of a command result indicating that the command was not suppo

### Channel rejecting commands
Some channels may may not support the command protocol or not allow for application customization of commands. In this case, the channel can reject commands with a transport-level response codes to allow a sender to detect the command activity was rejected. Example: When the transport is HTTP, 200 indicates acceptance and 400 indicates that the Activity name is not supported.