API response from /entities inconsistent with docs & client libraries

[percivalalb]

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/[email protected]#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.

[percivalalb]

Same issue with the GET endpoint: https://wit.ai/docs/http/20221114/#get__entities__entity_link

[percivalalb]

This looks to have been resolved in v2.1.0 of the Go client library: Compare https://pkg.go.dev/github.com/wit-ai/wit-go/[email protected]#Entity vs https://pkg.go.dev/github.com/wit-ai/wit-go/[email protected]#CreateEntityResponse

However the docs still look wrong:

[percivalalb]

Go client was fixed by https://github.com/wit-ai/wit-go/pull/30 and mentioned in https://github.com/wit-ai/wit-go/issues/23