feat(json-type): add a JSON data type

[Tieske]

replaces #255 , the JSON part of it

[schaze]

Thanks for splitting up my old PR!

I don't want the format field to be of object type for JSON. The schema is just the value for the format field like for any other datatype.

There are several reasons for this:

1. We do not use an array for enums or number ranges but keep it as a string. The same should apply for this. Having an escaped JSON object as string in this field is IMHO no different than a comma separated array as a string.
2. Allowing multiple data types for the format field needlessly increases complexity for the device description.
3. If someone has any JSON syntax errors in the JSON Schema this could break parsing the device description completely and make the homie device unusable.
4. If other devices do not care about the schema or format field they should not needlessly be forced to parse the JSON Schema down to an actual object when reading in the device description. It can be just left as a meaningless string value with no further consideration.

[Tieske]

Thanks for splitting up my old PR!

I don't want the format field to be of object type for JSON. The schema is just the value for the format field like for any other datatype.

There are several reasons for this:

1. We do not use an array for enums or number ranges but keep it as a string. The same should apply for this. Having an escaped JSON object as string in this field is IMHO no different than a comma separated array as a string.

That's because besides the simple formats, there was a need for complex datastructures (schedules, etc). Using JSON is just a way of using an existing well-known format. Otherwise everything would become JSON and JSONschema, which would severely raise the entry barrier for new developers trying to use Homie. So conceptually Homie uses its own simple types, and for the exceptional occasion where complex structures are required, JSON can be used.

2. Allowing multiple data types for the format field needlessly increases complexity for the device description.

I don't understand this one? Wouldn't escaped JSON be more complex to understand?

3. If someone has any JSON syntax errors in the JSON Schema this could break parsing the device description completely and make the homie device unusable.

That would be a positive effect to me. It's a programming mistake to begin with, and the only proper answer to such a thing is to bail out. The device was never set up to present a bad json, so if that happens you can only assume that the device is in an undetermined state. Which means it should abort operation. That's the only sensible thing to do.

4. If other devices do not care about the schema or format field they should not needlessly be forced to parse the JSON Schema down to an actual object when reading in the device description. It can be just left as a meaningless string value with no further consideration.

Parsing the JSON is just a few CPU cycles up front. Since this is controller side, this is not resource constraint, so shouldn't be a problem imho. If a resource constraint device parses it, then the memory constraint is probably bigger than the cpu-cycles, since its already parsing json. And the memory constraint is not going away if you make it escaped-json-in-a-string

Overall, I find using escaped json an extremely bad developer experience.

The one benefit of having a string value imo would be when using it with a statically typed language, where it would be easier to parse.

[schaze]

Overall, I find using escaped json an extremely bad developer experience.

I don´t think a developer will mind. The developer will only get a string field for format (like for any other datatype). This string will hold a JSON Schema as string, the same as if it were to be read from a file. There is no 'de-escaping' needed as this is automatically handled by whatever language feature is used that will parse the device description JSON. It is no different as if I would have double quotes in any other string within a JSON object.

IMHO for developers this might actually be better, because if you e.g. want to dump out a number of device description objects to the console the schema would only be printed as a long line of text, instead of potentially multiple screens full of formatted JSON notation.

The one benefit of having a string value imo would be when using it with a statically typed language, where it would be easier to parse.

This is exactly the reason why I would like to keep the fields in the description of the same type and not change based on the value of other fields.

format will be string which is something to be relied up. If I choose to use the schema for validation, I simply parse this string to a JSON object and use it. If not, I ignore it.

[Tieske]

@schaze updated, please check the last commit