Package org.eclipse.ditto.json

Interface JsonFieldDefinition<T>

public interface JsonFieldDefinition<T>
A JsonFieldDefinition is a formal description of a single JsonField. A JSON field consists of a key (or name) and a value. A JsonFieldDefinition differs in the way that it consists not only of a simple JSON key but its super type JsonPointer. With the help of this interface one can explicitly define a schema of a JSON document including all sub documents.

The following example shows how a JSON document would be described with the help of JsonFieldDefinition. 

      {
         "thingId": "myThing",
         "attributes": {
            "someAttr": {
               "subsel": 42
            },
            "anotherAttr": "baz"
         }
      }

Within an according class the structure of this JSON document could be described as follows: 

    import static JsonFactory.newIntFieldDefinition;
    import static JsonFactory.newStringFieldDefinition;
    ...

    public final class Thing {

        private static final JsonFieldDefinition THING_ID = newStringFieldDefinition("thingId");
        private static final JsonFieldDefinition SUBSEL = newIntFieldDefinition("attributes/someAttr/subsel");
        private static final JsonFieldDefinition ANOTHER_ATTR = newStringFieldDefinition("attributes/anotherAttr");

       ...

    }

In this case attributes and someAttr are implicitly defined with the value type JsonObject.

Additionally, a JSON field definition can be marked with zero to n JsonFieldMarkers. The semantics of a marker is defined by you rather than Ditto JSON. One possible usage scenario would be to define the fields which belong to a particular schema version with a maker according to that version.

Implementations of this interface are required to be immutable!