When SDT was introduced, XML was the favorite encoding format for schemas. Since then, JSON became more popular in the developers' communities, especially in the context of RESTful implementation.
JSON is more concise and human-readable comparing to XML, but has less capability of formal schema definition and validation (such as the XML Schema as defined in [domain.xsd](SDT/schema4.0/src/domain.xsd)).
JSON is more concise and human-readable comparing to XML, but has less capability of formal schema definition and validation (such as the XML Schema as defined in [domain.xsd](../src/domain.xsd)).
For these reasons, JSON serialization is supported since SDT4.0.
For these reasons, JSON serialization is supported since SDT version 4.0.
There are some open tools such as [JSON Schema](http://json-schema.org/) that might be useful for describing and validating the JSON serialization of SDT, but it's not yet a formal standard and is still under development.
In this release, we chose to define the JSON serialization by the documentation below, while borrowing some valuable aspects from JSON Schema (e.g. data types and validation keywords). Full endorsement of [JSON Schema](http://json-schema.org/) may be considered in future.
In this release, we chose to define the JSON serialization by the documentation below, while borrowing some valuable aspects from JSON Schema (e.g. data types and validation keywords). Full endorsement of [JSON Schema](http://json-schema.org/) may be considered in the future.
The general JSON structure follows the general SDT structure presented in [SDT_UML.md](SDT_UML.md) and described in [SDT_Components.md](SDT_Components.md).
<aname="mappings"/></a>
## SDT mapping to JSON
<aname="elements"/></a>
### Elements mapping
| SDT XML Elements | JSON Key Words | Remark |
|------------------|----------------|--------|
|Action | Action | |
|Actions | Actions | This element is an array of *Action* structures. |
|Arg | Arg | |
|Args | Args | This element is an array of *Arg* structures. |
|Constraint | Constraint | |
|Constraints | Constraints | This element is an array of *Constraint* structures. |
|Data | Data | This element is an array of *DataPoint* structures. |
|DataPoint | DataPoint | |
|DataType | DataType | |
|DataTypes | DataTypes | This element is an array of *DataType* structures. |
|DeviceClass | DeviceClass | |
|DeviceClasses | DeviceClasses | This element is an array of *DeviceClass* structures. |
|Doc |Doc | |
|Domain | Domain | |
|Event | Event | |
|Events | Events | This element is an array of *Event* structures. |
|Exclude | Exclude | |
|Extend | Extend | |
|Imports |Imports| This element is an array of *Include* structures. |
|Include | Include | |
|ModuleClass | ModuleClass | |
|ModuleClasses | ModuleClasses | This element is an array of *ModuleClass* structures. |
|ProductClass | ProductClass | |
|ProductClasses | ProductClasses | This element is an array of *ProductClasses* structures. |
|Properties | Properties | This element is an array of *Property* structures. |
|Property | Property | |
|SubDevice | SubDevice | |
|SubDevices | SubDevices | This element is an array of *SubDevice* structures. |
Some JSON examples can be found in [SDT Components](SDT/schema4.0/docs/SDT_Components.md) and a full exmaple can be found in [JSON Example](SDT/schema4.0/docs/JSON_Example.md)
#### Example
*Editor's note: a full JSON example will be developed later when the solution is complete*
The following example defines a simple *Light* device.
# SDT Elements mapping to JSON
**XML**:
| SDT Elements | JSON Key Word |
|--------------|------------|
| Domain | Domain |
|Imports (*capitalization is not consistent in XML)|Imports (*FFS)|
|Doc |Doc |
|extends (why it's de-capitalized in XML?) |Extends |
<Doc>This property indicates the ON/OFF status.</Doc>
<DataType>
<SimpleTypetype="boolean"/>
</DataType>
</DataPoint>
</Data>
</ModuleClass>
</ModuleClasses>
</DeviceClass>
</DeviceClasses>
</Domain>
```
*Editor's note: In XML schema, data-point is tagged as 'Data'. Should we change it to 'DataPoints' to be consistent?*
**JSON**:
# SDT Attributes mapping to JSON
There are common attributes (e.g. *@id, @name, @optional*) used in several SDT components (e.g. *DeviceClass, ModuleClass*) as well as attributes used only in certain components (e.g. *@class* in *Extends*). The mapping of those attributes to JSON follows the same rule as below.
```javascript
{
"Domain":{
"id":"SimpleExample",
"DeviceClasses":[
{
"DeviceClass":{
"id":"Light",
"Doc":"This is a very simple device representing a light.",
"ModuleClasses":[
{
"ModuleClass":{
"Data":[
{
"DataPoint":{
"name":"status",
"readable":"true",
"writable":"true",
"Doc":"This property indicates the ON/OFF status.",
"DataType":"boolean"
}
}
]
}
}
]
}
}
]
}
}
```
| SDT Attributes | JSON Key Word |
<aname="attributes"/></a>
### Attributes mapping
There are common attributes (e.g. *@id, @name, @optional*) used in several SDT components (e.g. in *DeviceClass, ModuleClass*) as well as attributes used only in certain components (e.g. *@entity* in *Extend*). The mapping of those attributes to JSON follows the rules as below.
| SDT XML Attributes | JSON Key Word |
|----------------|-------------|
| @id |id |
| @name |name |
| @value |value |
| @optional | optional|
| @readable | readable|
| @writable | writable|
| @eventable | eventable|
| @domain |domain |
| @class |class |
# SDT data types and constraints mapping to JSON
*Editor's note: defining standardized SDT data type constraints as listed below in the main spec - SDT_Components.md and domain.xsd is ffs*
| SDT Data Types | Values | Constrains | JSON Key Word | Note |
|----------------|-----------|------|------|----|
| SimpleType | || - | For simplicity, the type value of *SimpleType* is directly put as the value of parent *DataType* key, e.g. "DataType":"String".|
| | boolean || boolean | JSON Schema |
| | byte || byte | An integer datatype with the range of [0 - 255] |
In the *Include* and *Exclude* elements one may specify the type of the element to be included or excluded. The following table shows the mapping of *ExtendType*.
| SDT ExtendType | JSON Key Word |
|----------------|---------------|
|action | action |
|datapoint | datapoint |
|event | event |
|moduleclass | moduleclass |
|property | property |
|device | device |
|subdevice |subdevice |
<aname="dataTypes"/></a>
### Data Type mapping
Data types are defined in [SDT_Components.md](SDT_Components.md).
The mapping of the different kind of data types to JSON happens directly to JSON structures. The identifier for the data type kind is the name of that structure. This means that the data type definition is not wrapped by a *DataType* structure.
<aname="SimpleType"/></a>
### SimpleType
Note for *SimpelType*: For simplicity, if there is no other attribute present then the type value of *SimpleType* can be directly put as the value of parent *DataType* key, e.g. ```"DataType":"string"```
| SDT Data Types | Note |
|----------------|-----------|
| boolean | boolean (JSON Schema) |
| string | string (JSON Schema) |
| byte | An integer datatype with the range of [0 - 255] |
| integer | integer (JSON Schema) |
| float | number (JSON Schema) |
| date | date (JSON Schema) |
| time | time (JSON Schema) |
| datetime | date-time (JSON Schema) |
| blob | A *base64Binary* encoded string according to [RFC 2045](https://www.w3.org/TR/xmlschema-2/#RFC2045) |
| uri | A string following the URI format (JSON Schema) |
| void | null (JSON Schema) |
#### Examples
Simple data type:
**XML**:
```xml
<DataType>
<SimpleTypetype="string"/>
</DataType>
```
**JSON**:
```javascript
"SimpleType":"string"
```
A simple data type with additional attributes:
**XML**:
```xml
<DataTypename="temperatureType"unitOfMeasure="C">
<SimpleTypetype="float"/>
</DataType>
```
**JSON**:
```javascript
"SimpleType":{
"name":"temperatureType",
"unitOfMeasure":"C",
"type":"number"
}
```
<aname="ArrayType"/></a>
### ArrayType
An *ArrayType* definition is mapped to an *Array* JSON structure. The content of the structure is only one element that defines the type of the array. This could be any *SimpleType*, *ArrayType*, *StructType*, or *EnumType*.
#### Example
A simple data type with additional attributes:
**XML**:
```xml
<DataType>
<Array>
<DataType>
<SimpleTypetype="float"/>
</DataType>
</Array>
</DataType>
```
**JSON**:
```javascript
"Array":{
"SimpleType":"float"
}
```
<aname="StructType"/></a>
### StructType
A *StructType* definition is mapped to a *Struct* JSON array. The content of the array are the individual data types for the structure. These could be any *SimpleType*, *ArrayType*, *StructType*, or *EnumType*.
A *StructType* definition must contain a *name* attribute.
#### Example
A simple structured data type (a structure that contains an *indentifier* variable of type *string* and a *count* variable of type *integer*).
**XML**:
```xml
<DataType>
<Struct>
<DataTypename="identifier">
<SimpleTypetype="string"/>
</DataType>
<DataTypename="count">
<SimpleTypetype="integer"/>
</DataType>
</Struct>
</DataType>
```
**JSON**:
```javascript
"Struct":[
{
"SimpleType":{
"name":"identifier",
"type":"string"
},
"SimpleType":{
"name":"count",
"type":"integer"
}
}
]
```
A more complex structured data type (a structure that contains an indentifier variable of type *string* and an *integer* array named *items*).
**XML**:
```xml
<DataType>
<Struct>
<DataTypename="identifier">
<SimpleTypetype="string"/>
</DataType>
<DataTypename="items">
<Array>
<DataType>
<SimpleTypetype="integer"/>
</DataType>
</Array>
</DataType>
</Struct>
</DataType>
```
**JSON**:
```javascript
"Struct":[
{
"SimpleType":{
"name":"identifier",
"type":"string"
},
"Array":{
"name":"items",
"SimpleType":"float"
}
}
]
```
<aname="EnumType"/></a>
### EnumType
A *EnumType* definition is mapped to an *Enum* JSON structure. The content of the structure are the individual enum values of the enum.
A *EnumType* definition must contain a *name* attribute.
#### Example
An *Enum* that defines three *EnumValues*. The first definition explicitly specifies the type of the *EnumValue*.
Extending *DataTypes* are mapped the same way as extending, for example, *ModuleClasses*. However, since the *DataType* is open, the generic form *DataType* must be used for JSON serialization. It maps to a structure that contains a single *Extend* structure. This structure contains the two attributes *domain* and *entity*.
#### Example
An *Enum* that defines three *EnumValues*. The first definition explicitly specifies the type of the *EnumValue*.
