语义协议：重要字段和通用字段

**目录**
1. 消息格式
2. 应答消息字段定义
	2.1. 语义semantic
	2.2. Data字段
	2.3. 简化图文结果表示
	2.4. moreResults结构表示
3. 通用功能协议
	3.1.3. 表示交叉路口的location
	3.1.4. 表示区域的location
	3.1.5. 表示位置点的location
	3.2. 时间描述相关协议
	3.3. 标准时间
	3.4. 时间段
	3.5. 偏移时间
	3.6. 重复时间

## 1. 消息格式

交互返回数据为JSON格式:
<details>

<summary>点击查看示例</summary>

``` json
{
 "data": {
 "result": [
 {
 "airData": 35,
 "date": "2018-02-07",
 "dateLong": 1517932800,
 "humidity": "16%",
 "tempRange": "-9℃ ~ 2℃",
 }
 ]
 },
 "rc": 0,
 "semantic": [
 {
 "intent": "QUERY",
 "slots": [
 {
 "name": "datetime",
 "value": "今天",
 "normValue": "{\"datetime\":\"2018-02-07\",\"suggestDatetime\":\"2018-02-07\"}"
 },
 {
 "name": "location.city",
 "value": "北京市",
 "normValue": "北京市"
 },
 {
 "name": "subfocus",
 "value": "天气状态"
 }
 ]
 }
 ],
 "service": "weather",
 "text": "查看北京今天的天气",
 "answer": {
 "text": "\"北京今天多云转晴\"
 },
 "dialog_stat": "DataValid",
 "category" : "IFLYTEK.weather",
 "version" : "10.0",
 "sid": "atn00d35cc3@ch13c70dd605786f1d01"
}
```
</details>

## 2. 应答消息字段定义

### 2.1. 语义semantic

意图的描述信息，通过该字段定位用户意图，并获取意图图参数，实现技能逻辑处理。

semantic字段说明：

| 字段名称 | 字段类型 | 是否必须 | 说明 |
| :--- | :--- | :--- | :--- |
| intent | String | 是 | 技能中的意图 |
| slots | Object | 是 | 参照后续不同技能的定义 |

slots字段说明：

| 字段名称 | 字段类型 | 是否必须 | 说明 |
| :--- | :--- | :--- | :--- |
| name | String | 是 | 槽位名 |
| value | String | 是 | 槽位值 |

### 2.2. Data字段

该字段表示应答结果，如果应用本身没有数据源，可以直接选择该结果解析和展现，无需处理语义信息。

| 字段名称 | 字段类型 | 是否必须 | 说明 |
| :--- | :--- | :--- | :--- |
| header | String | 否 | 导语部分 |
| result | Object | 否 | 结构化数据；如果没有查到数据，此字段不返回。参照后续不同技能的定义 |

### 2.3. 简化图文结果表示

对于一些技能，支持直接返回一段文本应答结果，同时辅助一张图片和相关链接。应用可以无需解析和提取语义/结果的结构化数据信息，直接显示该字段的图文信息。同时用户可以选择通过开放平台编辑和上传/导入图文应答信息，快速自定义扩展应用交互。

### 2.4. moreResults结构表示

说法命中多个技能时出现moreResults字段，通过moreResults字段来扩展其他意图技能描述。moreResults是一个JSON数组，可以在开放平台配置是否允许多结果。\(这里需要针对几个关键字段的特殊处理单独说明，如rc\)

示例:

``` json
{
    "answer" : {
        "text" : "你想做飞机还是火车?"
    },
    "rc" : 0,
    "semantic" : [
        {
            "intent" :  "QUERY",
            "slots" : [
                    ......
            ]
        }
    ],
    "service" : "flight",
    "text" : "我要去北京",
    "moreResults" : [
        {
            "text" : "我要去北京",
            "rc" : 0,
            "semantic" : [
                    ......
            ],
            "service" : "train"
        }
    ]
}
```

## 3. 通用功能协议

本章描述了在各技能中相对通用的字段定义，在具体技能中如果引用相关字段将不再具体描述，直接参考相关章节。例如：在“航班”技能中需要定义“预定时间”，可以直接参考本章节中对“时间点”的定义，而不需要在技能中具体定义。

### 3.1. 地点描述相关协议

地点的基础描述为基于行政区划的地点定义，在此基础上包括扩展协议：表示道路、表示交叉路口、表示区域、表示位置点。

#### 3.1.1. 基础地点（表示行政区划）的location

| name字段名 | 是否必须 | 说明（value取值） |
| :--- | :--- | :--- |
| location.type | 是 | 取LOC\_BASIC |
| location.country | 否 | 国别简称\(参见附录的对照表\) |
| location.province | 否 | 省全称（包括直辖市、台） |
| location.provinceAddr | 否 | 省简称 |
| location.city | 否 | 市全称（包括港澳） |
| location.cityAddr | 否 | 市简称 |
| location.area | 否 | 县区 |
| location.areaAddr | 否 | 县区简称 |
|  |  | location.country、location.province、location.city、location.area这4种元素必须至少出现一种 |

示例：合肥市包河区

``` json
"slots": [
    {
        "name": "location.area",
        "value": "包河区"
    },
    {
        "name": "location.areaAddr",
        "value": "包河"
    },
    {
        "name": "location.city",
        "value": "合肥市"
    },
    {
        "name": "location.cityAddr",
        "value": "合肥"
    },
    {
        "name": "location.type",
        "value": "LOC_BASIC"
    }
]
```

#### 3.1.2. 表示道路的location

| name字段名 | 是否必须 | 说明（value取值） |
| :--- | :--- | :--- |
| location.type | 是 | 取LOC\_STREET |
| location.country | 否 | 国别简称\(参见附录的对照表\) |
| location.province | 否 | 省全称（包括直辖市、台） |
| location.provinceAddr | 否 | 省简称 |
| location.city | 是 | 市全称（包括港澳）, CURRENT\_CITY代表当前城市 |
| location.cityAddr | 否 | 市简称 |
| location.area | 否 | 县区 |
| location.areaAddr | 否 | 县区简称 |
| location.street | 是 | 道路名称 |
|  |  | city、street必选，其他元素可选，当用户没有输入城市，city为”CURRENT\_CITY” |

示例：合肥市长江西路

``` json
"slots": [
    {
        "name": "location. street",
        "value": "长江西路"
    },
    {
        "name": "location.city",
        "value": "合肥市"
    },
    {
        "name": "location.cityAddr",
        "value": "合肥"
    },
    {
        "name": "location.type",
        "value": " LOC_STREET "
    }
]
```

#### 3.1.3. 表示交叉路口的location

| name字段名 | 是否必须 | 说明（value取值） |
| :--- | :--- | :--- |
| location.type | 是 | 取LOC\_CROSS |
| location.country | 否 | 国别简称\(参见附录的对照表\) |
| location.province | 否 | 省全称（包括直辖市、台） |
| location.provinceAddr | 否 | 省简称 |
| location.city | 是 | 市全称（包括港澳）, CURRENT\_CITY代表当前城市 |
| location.cityAddr | 否 | 市简称 |
| location.area | 否 | 县区 |
| location.areaAddr | 否 | 县区简称 |
| location.street | 是 | 道路名称 |
| location.streets | 否 | 交口的另一道路名称 |
|  |  | city、street必选，其他元素可选，当用户没有输入城市而又没有上传所在城市信息，city为”CURRENT\_CITY” |

示例：合肥市望江西路和永和路交口

``` json
"slots": [
    {
        "name": "location. street",
        "value": "望江西路"
    },
    {
        "name": "location. streets",
        "value": "永和路"
    },
    {
        "name": "location.city",
        "value": "合肥市"
    },
    {
        "name": "location.cityAddr",
        "value": "合肥"
    },
    {
        "name": "location.type",
        "value": " LOC_ CROSS "
    }
]
```

#### 3.1.4. 表示区域的location

| name字段名 | 是否必须 | 说明（value取值） |
| :--- | :--- | :--- |
| location.type | 是 | 取LOC\_REGION |
| location.country | 否 | 国别简称\(参见附录的对照表\) |
| location.province | 否 | 省全称（包括直辖市、台） |
| location.provinceAddr | 否 | 省简称 |
| location.city | 是 | 市全称（包括港澳）, CURRENT\_CITY代表当前城市 |
| location.cityAddr | 否 | 市简称 |
| location.area | 否 | 县区 |
| location.areaAddr | 否 | 县区简称 |
| location.street | 否 | 道路名称 |
| location.region | 是 | 区域名称 |
|  |  | city、region必选，其他元素可选，当用户没有输入城市而又没有上传所在城市信息，比如“西直门”，city为“CURRENT\_CITY” |

示例：合肥市三里庵

``` json
"slots": [
    {
        "name": "location. region",
        "value": "三里庵"
    },
    {
        "name": "location.city",
        "value": "合肥市"
    },
    {
        "name": "location.cityAddr",
        "value": "合肥"
    },
    {
        "name": "location.type",
        "value": " LOC_ REGION"
    }
]
```

#### 3.1.5. 表示位置点的location

| name字段名 | 是否必须 | 说明（value取值） |
| :--- | :--- | :--- |
| location.type | 是 | 取LOC\_POI |
| location.country | 否 | 国别简称\(参见附录的对照表\) |
| location.province | 否 | 省全称（包括直辖市、台） |
| location.provinceAddr | 否 | 省简称 |
| location.city | 是 | 市全称（包括港澳）, CURRENT\_CITY代表当前城市 |
| location.cityAddr | 否 | 市简称 |
| location.area | 否 | 县区 |
| location.areaAddr | 否 | 县区简称 |
| location.street | 否 | 道路名称 |
| location.region | 否 | 区域名称 |
| location.poi | 是 | 机构等名称,CURRENT\_POI表示当前地点 |
|  |  | city、poi必选，其他元素可选，当用户没有输入城市而又没有上传所在城市信息， city为“CURRENT\_CITY” |

示例：合肥市三里庵国购广场

``` json
"slots": [
    {
        "name": "location. region",
        "value": "三里庵"
    },
    {
        "name": "location. poi",
        "value": "国购广场"
    },
    {
        "name": "location.city",
        "value": "合肥市"
    },
    {
        "name": "location.cityAddr",
        "value": "合肥"
    },
    {
        "name": "location.type",
        "value": " LOC_POI"
    }
]
```

### 3.2. 时间描述相关协议

datetime 4.0协议格式

``` json
{
    "name":"datetime",
    "begin":0,
    "end":9,
    "value":"明天下午3点到5点",
    "normValue":"
    {
        "datetime":"2018-03-07T15:00:00/2018-03-07T17:00:00",
        "suggestDatetime":"2018-03-07T15:00:00/2018-03-07T17:00:00"
    }
}
```

normValue中分为datetime和suggestDatetime，以明天上午为例：

datatime为 2018-03-29TAM

suggestDatatime为 2018-03-29T06:00:00

datetime字段的内容是依据当前文本的语义，理解得到的时间表示。suggestDatetime的内容是经过上下文理解，推理得到的相对精确的时间。开发者可以先检查是否存在"O+"或者"O-"字符，进行偏移时间解析，如果不是偏移时间，则使用“/”分割日期时间段为独立的日期时间，然后对每个日期时间使用“T”分割日期和时间，分别解析前段的日期内容和后段的时间内容。  
其中，时间分为4四种：标准时间，时间段，偏移时间，重复时间。

### 3.3. 标准时间

datetime格式为：时间类型+YY-MM-DDThh:mm:ss，其中时间类型可选，LC表示阴历，类型为空，则默认表示阳历；日期和时间之间用T分割。suggestDatetime统一表示为阳历时间，年-月-日T时:分:秒；推荐时间不保证准确，用户可以采用，也可以自行计算；suggest字段只精确到天，或者秒，大部分情况下缺失字段用当日的字段补全；阴历年、月说法补全缺失月、日字段为01，并计算阳历时间。

### 3.4. 时间段

datetime有三种表示方法：起始时间/结束时间，起始时间和结束时间都是基本时间，斜杠"/"前是起始时间,斜杠"/"后是结束时间。

### 3.5. 偏移时间

datetime为 O+时间段或O-时间段。suggestTime由当前时间加上或减去时间段，计算得到。

### 3.6. 重复时间

本版本暂不支持。

**部分不支持的时间描述格式，normValue.datetime和normValue.suggestDatetime值可能为空值，请开发者注意解析！**

| 时间类型 | 子类型 | 说法举例 | datetime | SuggestTime | date格式说明 | SuggestTime格式说明 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| 基本时间 | 年 | 2017年 | 2017 | 2017-03-20 |  |  |
|  |  |  |  | 2018年 | 2018 | 2018-03-20 |
|  |  |  |  | 今年 | 2018 | 2018-03-20 |
|  |  |  |  | 明年 | 2019 | 2019-03-20 |
|  |  |  |  | 后年 | 2020 | 2020-03-20 |
|  |  |  |  | 农历2015年 | LC2015 | 2015-02-19 |
|  |  | 月 | 三月 | 2018-03 | 2018-03-20 |  |
|  |  |  |  | 上个月 | 2018-02 | 2018-02-20 |
|  |  |  |  | 下个月 | 2018-04 | 2018-04-20 |
|  |  |  |  | 腊月 | LC2018-12 | 2019-01-06 |
|  |  |  |  | 正月 | LC2018-01 | 2018-02-16 |
|  |  |  |  | 2017年三月 | 2017-03 | 2017-03-20 |
|  |  |  |  | 去年三月 | 2017-03 | 2017-03-20 |
|  |  |  |  | 明年三月 | 2019-03 | 2019-03-20 |
|  | 旬 | 上旬 | 2018-03-01 | 2018-03-01 | 旬精确到起始日 |  |
|  |  |  |  | 中旬 | 2018-03-11 | 2018-03-11 |
|  |  |  |  | 下旬 | 2018-03-21 | 2018-03-21 |
|  |  |  |  | 三月上旬 | 2018-03-01 | 2018-03-01 |
|  |  |  |  | 四月中旬 | 2018-04-11 | 2018-04-11 |
|  |  |  |  | 五月下旬 | 2018-05-21 | 2018-05-21 |
|  |  |  |  | 2014年三月下旬 | 2014-03-21 | 2014-03-21 |
|  | 周 | 下周 | 2018-03-27 | 2018-03-27 | 1，未指定周几，按照当前weeday指定 2，第几周说法有歧义，可能是normal时间，也有可能是便宜时间，此文档按照标准时间识别 |  |
|  |  |  |  | 上周 | 2018-03-13 | 2018-03-13 |
|  |  |  |  | 2017年第十周 | 2017-02-28 | 2017-02-28 |
|  |  |  |  | 去年第五周 | 2017-01-24 | 2017-01-24 |
|  |  |  |  | 四月第二周 | 2018-04-03 | 2018-04-03 |
|  |  |  |  | 三月份第二周 | 2018-03-06 | 2018-03-06 |
|  |  |  |  | 第三周周三下午五点半 | 2018-01-17T17:30:00 | 2018-01-17T17:30:00 |
|  |  |  |  | 去年三月份第一周 | 2017-03-07 | 2017-03-07 |
| 日 | day | 三号 | 2018-03-03 | 2018-03-03 | 年+节日可以精确推导日期，所以datetime给出的是日期 |  |
|  |  |  |  | 五号 | 2018-03-05 | 2018-03-05 |
|  |  |  |  | 初十 | LC2018-03-10 | 2018-04-25 |
|  |  |  |  | 三月五号 | 2018-03-05 | 2018-03-05 |
|  |  |  |  | 2017年十月一号 | 2017-10-01 | 2017-10-01 |
|  |  |  |  | 上个月三号 | 2018-02-03 | 2018-02-03 |
|  |  |  | weekday | 周一 | 2018-03-19 | 2018-03-19 |
|  |  |  |  | 周日 | 2018-03-25 | 2018-03-25 |
|  |  |  |  | 上周一 | 2018-03-19 | 2018-03-19 |
|  |  |  |  | 下周一 | 2018-03-19 | 2018-03-19 |
|  |  |  |  | 周末 | 2018-03-24 | 2018-03-24 |
|  |  |  |  | 2015年第四周周一 | 2015-01-19 | 2015-01-19 |
|  |  |  |  | 2015年四月第二周周一 | 2015-04-06 | 2015-04-06 |
|  |  |  |  | 2015年四月第二个周一 | 2015-04-06 | 2015-04-06 |
|  |  |  | festival | 清明节 | 清明 | 2018-04-05 |
|  |  |  |  | 端午节 | 端午节 | 2018-06-18 |
|  |  |  |  | 2017年国庆节 | 2017-10-01 | 2017-10-01 |
|  |  |  |  | 明年端午 | 2019-06-07 | 2019-06-07 |
| 时间 | 口语time | 上午 | TAM | 2018-03-20T06:00:00 | 目前支持的口语time：早上（AM），上午（AM），凌晨（EAM），清晨（AM），一早（AM），早晨（AM），清早（AM），头晌（MID），中午（MID），正午（MID），晌午（MID），傍晌（EV），下午（PM），傍晚（EV），黄昏（EV），夜里（NI），深夜（LNI），晚上（NI），夜晚（NI），午夜（MNI），半夜（MNI） | AM06:00:00 EAM 01:00:00 MID 12:00:00 EV18:00:00 PM13:00:00 NI20:00:00 LNI 22:00:00 MNI 23:59:59  |
|  |  |  |  | 下午 | TPM | 2018-03-20T13:00:00 |
|  |  |  |  | 明天上午 | 2018-03-21TAM | 2018-03-21T06:00:00 |
|  |  |  |  | 周一下午 | 2018-03-19TPM | 2018-03-19T13:00:00 |
|  |  |  |  | 2017年四月五号上午 | 2017-04-05TAM | 2017-04-05T06:00:00 |
|  |  |  |  | 国庆节晚上 | 国庆节TNI | 2018-10-01T20:00:00 |
|  |  |  |  | 前年中秋节下午 | 2016-09-15TPM | 2016-09-15T13:00:00 |
|  |  |  |  | 上个月三号中午 | 2018-02-03TMID | 2018-02-03T12:00:00 |
|  |  |  |  | 十号下午 | 2018-03-10TPM | 2018-03-10T13:00:00 |
|  | 时分秒 | 三点十分零五秒 | T03:10:05 | 2018-03-20T03:10:05 |  |  |
|  |  |  |  | 三点十分 | T03:10:00 | 2018-03-20T03:10:00 |
|  |  |  |  | 三点半 | T03:30:00 | 2018-03-20T03:30:00 |
|  |  |  |  | 三点一刻 | T03:15:00 | 2018-03-20T03:15:00 |
|  |  |  |  | 2017年三月八号十五点三十分钟十秒 | 2017-03-08T15:30:10 | 2017-03-08T15:30:10 |
|  |  |  |  | 三月八号十五点三十分钟十秒 | 2018-03-08T15:30:10 | 2018-03-08T15:30:10 |
|  |  |  |  | 八号十五点三十分钟十秒 | 2018-03-08T15:30:10 | 2018-03-08T15:30:10 |
|  |  |  |  | 2017年三月八号下午三点 | 2017-03-08T03:00:00 | 2018-03-20T03:00:00 |
|  |  |  |  | 三月八号下午十五点 | 2018-03-08T15:00:00 | 2018-03-20T15:00:00 |
|  |  |  |  | 八号上午十点 | 2018-03-08T10:00:00 | 2018-03-20T10:00:00 |
| 时间段 | 起始点/结束点 | 三号到五号 | 2018-03-03/2018-03-05 | 2018-03-03/2018-03-05 |  |  |
|  |  |  |  | 周一下午到周二上午 | 2018-03-19TPM/2018-03-20TAM | 2018-03-19T13:00:00/2018-03-20T06:00:00 |
|  |  |  |  | 三月中旬到下旬 | 2018-03-11/2018-03-21 | 2018-03-11/2018-03-21 |
|  |  |  |  | 2017年三月四号上午五点到下午7点 | 2017-03-04T05:00:00/2017-03-04T19:00:00 | 2017-03-04T05:00:00/2017-03-04T19:00:00 |
|  |  |  |  | 2017年三月四号下午五点到7点 | 2017-03-04T17:00:00/2017-03-04T19:00:00 | 2017-03-04T17:00:00/2017-03-04T19:00:00 |
|  | 时间段\(暂不支持\) | 一个小时 |  |  |  |  |
|  |  |  |  | 三天零2个小时 |  |  |
|  |  |  |  | 一年零两个月三天 |  |  |
|  |  |  |  | 一年零两个月三天零2个半小时 |  |  |
|  | 起始点/\[时间段\]\[时间段\]/结束点\(暂不支持\) | 未来三天 |  |  |  |  |
|  |  |  |  | 过去七天 |  |  |
| 重复时间 | 重复时间段\(暂不支持\) | 每2个月 |  |  |  |  |
|  |  |  |  | 每两个星期 |  |  |
|  |  |  |  | 每一年零三个月 |  |  |
|  |  |  |  | 每一年零三个月五天六个半小时 |  |  |
|  | 重复时间点\(暂不支持\) | 每年 |  |  |  |  |
|  |  |  |  | 每月 |  |  |
|  |  |  |  | 每年三月 |  |  |
|  |  |  |  | 每周二下午三点 |  |  |
|  |  |  |  | 每周末 |  |  |
|  |  |  |  | 每年三月五号下午五点半 |  |  |
| 偏移时间 | 偏移时间 | 第二天 | O+1D | 2018-03-21 |  |  |
|  |  |  |  | 前一天 | O-1D | 2018-03-19 |
|  |  |  |  | 两天三个小时后 | O+2D3h | 2018-03-22T17:13:52 |
|  |  |  |  | 半个小时之前 | O-30m | 2018-03-20T13:43:52 |
|  |  |  |  | 1年零3个月之后 | O+1Y3M | 2019-06-20 |
|  |  |  | 偏移时间+时间点（暂不支持） |  |  |  |