Commit 2ba1c650 authored by Yongjing Zhang's avatar Yongjing Zhang

Add initial draft for JSON Serialization

parent cc7bcc24
......@@ -10,7 +10,7 @@ Any contributions made to this project must comply with the aforementioned licen
## Quick Introduction
The Smart Device Template (SDT) is a template which is used to model the capabilities, actions and events of connected devices. The intent of the SDT is to be able to model any type of connected device using a well accepted and standardised format. The main application of SDT is to enable a uniformly structured Application Programmer’s Interface (API) to applications that need to interact with connected devices. Usually, these applications would communicate to devices using an Abstraction Layer as an intermediary logic. The Abstraction Layer „hides“ the technology-specific, native language format of devices of different technology type from the applications.
The Smart Device Template (SDT) is a template which is used to model the capabilities, actions and events of connected devices. The intent of the SDT is to be able to model any type of connected device using a well accepted and standardised format. The main application of SDT is to enable a uniformly structured Application Programmer鈥檚 Interface (API) to applications that need to interact with connected devices. Usually, these applications would communicate to devices using an Abstraction Layer as an intermediary logic. The Abstraction Layer 鈥瀐ides鈥� the technology-specific, native language format of devices of different technology type from the applications.
[Read the full Introduction.](SDT/schema4.0/docs/Introduction.md)
......@@ -25,6 +25,7 @@ You can find further Information here:
- [Introduction to the SDT](SDT/schema4.0/docs/Introduction.md)
- [SDT Components](SDT/schema4.0/docs/SDT_Components.md)
- [JSON Serializatoin](SDT/schema4.0/docs/SDT_JSON.md)
- [SDT Build System](SDT/schema4.0/docs/SDT%20Build%20System.md)
- [Examples](SDT/schema4.0/docs/Examples.md)
- [Links & References](SDT/schema4.0/docs/Links.md)
......
JSON serialization is supported since SDT4.0 as it's very popular nowadays 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)).
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.
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)
*Editor's note: a full JSON example will be developed later when the solution is complete*
# SDT Elements mapping to JSON
| 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 |
|ImplementedModuleClasses |ImplementedModuleClasses |
|ImplementedProperties |ImplementedProperties |
|DeviceClasses | DeviceClasses|
|SubDevice | SubDevice|
|Product | Product|
|Properties |Properties |
|ModuleClasses | ModuleClasses|
|Data| DataPoints|
|Actions| Actions|
| Args | Args|
|Events | Events|
|DataType| | DataType|
*Editor's note: In XML schema, data-point is tagged as 'Data'. Should we change it to 'DataPoints' to be consistent?*
# 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.
| SDT 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] |
| | integer | | integer | JSON Schema |
| | | multipleOf | multipleOf | JSON Schema |
| | | maximum | maximum | JSON Schema |
| | | exclusiveMaximum | exclusiveMaximum | JSON Schema |
| | | minimum | minimum | JSON Schema |
| | | exclusiveMinimum | exclusiveMinimum | JSON Schema |
| | float || number | JSON Schema |
| | | multipleOf | multipleOf | JSON Schema |
| | | maximum | maximum | JSON Schema |
| | | exclusiveMaximum | exclusiveMaximum | JSON Schema |
| | | minimum | minimum | JSON Schema |
| | | exclusiveMinimum | exclusiveMinimum | JSON Schema |
| | string || string | JSON Schema |
| | | maxLength | maxLength | JSON Schema |
| | | minLength | minLength | JSON Schema |
| | | pattern | pattern | JSON Schema |
| | enum || enum | JSON Schema |
| | date || date | JSON Schema |
| | time || time | JSON Schema |
| | datetime || date-time | JSON Schema |
| | blob || blob | A **base64Binary** encoded string according to [RFC 2045](https://www.w3.org/TR/xmlschema-2/#RFC2045) |
| | uri || uri | JSON Schema |
| StructType || | Struct | |
| ArrayType || | Array | |
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment