SDT_JSON.md 4.3 KB
Newer Older
1 2 3 4 5
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)). 

For these reasons, JSON serialization is supported since SDT4.0.
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88

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 | |