diff --git a/.project b/.project new file mode 100644 index 0000000000000000000000000000000000000000..d70ce78c4a92f400a7e69ed464ed8a01fb039a11 --- /dev/null +++ b/.project @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<projectDescription> + <name>SDT</name> + <comment></comment> + <projects> + </projects> + <buildSpec> + </buildSpec> + <natures> + </natures> +</projectDescription> diff --git a/README.md b/README.md index 8ef9df2fcef6a01af93e34aadb50390cf8309bbd..90624122e355d98755329d6f6483823d23f37e5d 100644 --- a/README.md +++ b/README.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) diff --git a/SDT/schema4.0/docs/SDT_JSON.md b/SDT/schema4.0/docs/SDT_JSON.md new file mode 100644 index 0000000000000000000000000000000000000000..0b6c66bf7933db906f71224ea4013b2b11af4ad7 --- /dev/null +++ b/SDT/schema4.0/docs/SDT_JSON.md @@ -0,0 +1,88 @@ +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. + +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 | | + +