Batch-processing: Referencing New Entities in a Change Set

[hylkevds]

From OData:

11.7.3.1 Referencing New Entities in a Change Set
Entities created by an Insert request within a change set can be referenced by subsequent requests within the same change set in places where a resource path to an existing entity can be specified, in the request URL as well as in the request body.

I don't think we allow "resource paths to an existing entity" in the body of our requests. If I create a new Datastream that references an existing Thing and Sensor, the body would contain the IDs of those referenced entities, not the resource path to them.

For example, I create, in a ChangeSet:

• a Thing, referenced as $thing, that gets id 15 after the insert
• a Sensor, referenced as $sensor, that gets id 23
• a Datastream, linking to both.

What would the body of that last Change set item be? We can link to one of the two, by doing a post to $thing/Datastreams, since $thing will be replaced by the resource path to the entity (v1.0/Things(15)), giving the final path of the POST to be v1.0/Things(15)/Datastreams. But we can't reference both the Thing and the Sensor in the URL. Putting $sensor in the body isn't allowed, since v1.0/Sensors(23) is not a valid reference in the body.

We could, for STA, reword that paragraph to something like:

Entities created by an Insert request within a change set can be referenced by subsequent requests within the same change set in places where a resource path to an existing entity can be specified in the request URL, as well as in places where a resource ID to an existing entity can be specified in the request body.

The body of the request would then be:

{
  "name": "MyDataStream",
  "description": "A stream of data",
  "Thing": {"@iot.id": $thing},
  "Sensor": {"@iot.id": $sensor},
  "ObservedProperty": {"@iot.id": 1}
}

Since we've changed to spec to make body references reference the ID, not the resource path.

The problem with this is, of course, that it's invalid JSON. Only after the server blindly replaces all occurrences of $thing with 15 and of $sensor with 23 is it valid JSON.

That could be solved by specifying that the body reference must be encoded as a String in json, making the final request body:

{
  "name": "MyDataStream",
  "description": "A stream of data",
  "Thing": {"@iot.id": "$thing"},
  "Sensor": {"@iot.id": "$sensor"},
  "ObservedProperty": {"@iot.id": 1}
}

Which would be slightly confusing for servers that expect numeric IDs. But at least the JSON is valid.

[hylkevds]

This is related to #41: Batch Processing: Example 31-3 not demonstrating referencing

[hylkevds]

Fixed with the publication of Sensing v1.1.