Require type (class) declaration of the root json object for proper json-ld interpretation.

[Fak3]

In our models, there are some (semantically distinct) properties with generic names, prone to be clashed with each other. In the json-ld vocabulary we will make sure they will have distinct fully-qualified identifiers, for ex statusCode of the TransportRoute class and statusCode of the TransportMovement class should probably be represented as edi3:routeStatusCode and edi3:movementStatusCode in the vocabulary, each property will have different domain and range.

The problem is that in the plain json, they currently share the same key statusCode, and if a property appears at the root json object, the @context magic of json-ld will not have a way to tell which one of these two properties is used, unless that root object have its type (class) specified. (if it appears at non-root sub-object, @context is able to distinct them by the full path of that sub-object inside the root)

There is also a broader problem of potential clash of our vocab properties with other vocabs which client may want to use - it will not be possible to tell which one is used if it appears at the root.

So I would suggest that our json schema serialization rules mandate adding the type for the classes which instances will appear at the root (in REST responses or requests)

If the class already have the type property in our model - no change required. If it does not - the JSON schema should be augmented with type property with a static value equal to the class name, for ex: type: TransportMovement

[onthebreeze]

I think this sounds fine - but would like to see an example or two.

[Fak3]

For ex vessels response and request would look like this:

{
  "@context": "https://edi3.org/context.json",
  "identification": "http://maersk.com/vessels/01",
  "type": "Vessel",  # The type (class) of this object
  "owner": { 
       "identification": "http://maersk.com", 
       "name": "Maersk"
  }
}

[Fak3]

So the rule for generating json schema would be:
When generating schema for the root object of the interface, and the class which this interface implements does not have top-level property named "type", then add a property named "type" with fixed string value, equal to this class name.