API response from /entities inconsistent with docs & client libraries

Do you want to request a feature, report a bug, or ask a question about wit?

bug

What is the current behavior?

https://wit.ai/docs/http/20221114/#post__entities_link claims that the "roles" field in the JSON response body should be an array of strings (like "roles": ["favorite_city"]):

{
  "id": "5418abc7-cc68-4073-ae9e-3a5c3c81d965",
  "name": "favorite_city",
  "roles": ["favorite_city"],
  "lookups": ["free-text", "keywords"],
  "keywords": []
}

However making a request to the /entities endpoint gives the responses:

curl -XPOST 'https://api.wit.ai/entities?v=20221114' \
>   -H "Authorization: Bearer $TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{"name":"favorite_city",
>        "roles":[]}'
{"name":"favorite_city","roles":[{"id":"<redacted>","name":"favorite_city"}],"lookups":["free-text","keywords"],"keywords":[],"id":"<redacted>"}

The "roles" field is not an array of strings but in fact an array of objects which each object containing an "id" & "name" field. This contradicts the docs and also causes errors in client libraries. The same occurs with v=20200513.

In particular I am seeing this cause issues with the wit.ai golang implementation: https://pkg.go.dev/github.com/wit-ai/wit-go/v2@v2.0.2#Client.CreateEntity, where an error occurs when trying to unmarshal the object described above into the defined []string type.

json: cannot unmarshal object into Go struct field Entity.roles of type string

What is the expected behavior?

According to the docs "roles" should be an array of strings.

Either the backend needs updating to only return the name of each role in an array of strings.
or the client libraries and docs need updating to this new object structure.

wit-ai / wit

API response from /entities inconsistent with docs & client libraries #2584