Discussion: The importance of template values in actions

[JornWildt]

An action may have a template value associated with it:

"some-action": { type: "json", href: "..:", template: { ... some template value ... } }

The template is a nice base for client developers that explores the API. It can supply default values for all of the JSON data. It could in fact also be used for default values for an end user application.

But is the client REQUIRED to use the template?

I would say no when used for default values only ... but the template might just also include some server-specific information unknown to the client, like for instance a one-time access token - in this case the client MUST use the template (by merging its own values into it).

[JornWildt]

I am leaning towards "Clients MUST use any supplied template" because the template can contain some rather important hidden values (unknown to the client) - it can be a security token of some sort as mentioned before, but it can also be used to include something similar to HTTP ETag values for avoiding lost updates (see http://www.w3.org/1999/04/Editing/).

So what does "use" mean. I think of it as merging client supplied values into the template. Say we have a very simple action taking only one JSON value "Title" as an argument, like this:

{
  "type": "json",
  "template": {
    "Title": "Existing title",
    "ETag": "978jkbnasd97823"
  }
}

The client wishes to modify Title - but instead of building up its own JSON object with a Title property it must instead take the template object as-is and set the Title property on that instead.

Does anyone know of a standard definition for merging two JSON objects?

[JornWildt]

It will be "Clients MUST use any supplied template" (based on discussions I have had with a few people here and there).