First template is named "default" even in presence of multiple templates, from affordances in HAL-FORMS

[filipeamaral]

As per documentation at HAL-FORMS complete example:

A template named default is exposed. Its name is default as it’s the sole template defined and the spec requires that name to be used. If multiple templates are attached (by declaring additional affordances) they will be each named after the method they’re pointing to.

and at Template titles:

To define a template title use the following pattern: _templates.$affordanceName.title. Note that in HAL-FORMS, the name of a template is default if it is the only one. This means that you’ll usually have to qualify the key with the local or fully qualified input type name that affordance describes.

it goes against what is stated in Example 33, at 4.2. HAL-FORMS:

{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "role" : "ring bearer",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/employees/1"
    }
  },
  "_templates" : {
    "default" : {
      "method" : "put",
      "properties" : [ {
        "name" : "firstName",
        "required" : true
      }, {
        "name" : "lastName",
        "required" : true
      }, {
        "name" : "role",
        "required" : true
      } ]
    },
    "partiallyUpdateEmployee" : {
      "method" : "patch",
      "properties" : [ {
        "name" : "firstName",
        "required" : false
      }, {
        "name" : "lastName",
        "required" : false
      }, {
        "name" : "role",
        "required" : false
      } ]
    }
  }
}

and my pet project as well:

{
  "id": "2fd3db95-885a-4b0a-a4bc-d779aacd46c1",
  "firstName": "John",
  "lastName": "Doe",
  "_links": {
    "self": {
      "href": "http://localhost:8080/authors/2fd3db95-885a-4b0a-a4bc-d779aacd46c1"
    }
  },
  "_templates": {
    "default": {
      "method": "delete",
      "properties": []
    },
    "replaceAuthor": {
      "method": "put",
      "properties": [
        {
          "name": "firstName",
          "regex": "^[a-zA-Z]+$",
          "required": true
        },
        {
          "name": "id",
          "readOnly": true
        },
        {
          "name": "lastName",
          "regex": "^[a-zA-Z]+$",
          "required": true
        }
      ]
    }
  }
}

Is the current behaviour correct and default should always be kept or is there a bug preventing the default to not be present upon multiple templates?

Thank you in advance!

[odrotbohm]

The reason we currently do it this way is that, if we kept the original affordance name in case of multiple templates, that would be disruptive to clients that try to find a default template as soon as you add a second template to the resource. I.e. you start with one named foo, that's exposed as default and you ship that API. You now add a second one bar and all of a sudden, default is gone and foo, bar appear with foo logically equivalent to the default one before. I've filed mamund/hal-forms#82 for clarification.

That said, in case we stay with the current approach, we need to fix the docs.

[talentedasian]

IMO the thing(atleast for me) with default keys is that it often lacks context in _template collections. Like if _template only has a default it wouldn't be confusing but if it has different keys like: save-entity, update-entity compared to default, update-entity and would just continuously grow it's a bit confusing even if you already know what the default key does.

[odrotbohm]

Yeah, the lack of dedicated semantics conveyed by a foo masked as default is what I tried to convey on the ticket I referenced. It looks like both variants have their downsides and it's not immediately clear to me what goal Mike had in mind when designing that part of the spec.