I find myself unsure about what exactly it means to have different representations of a RESTful resource. The canonical example is for an API to provide an endpoint - say /v1/users/:id - and allow the client to select the best representation of the resource between JSON, XML, HTML or PDF depending on the media range value of the ACCEPT headers.

I was under the impression that this definition of representation could be extended to encompass more than just content-types, but actually response schemas. Say for example a client wants extended information about the user they could get it by specifying a supported header.

So for instance, my application could supply different schemas for the same resource i.e.

# get the default user representation
GET /v1/users/1234
ACCEPT: application/vnd.myapp.v1+json
 
# server responds with
{"id": 1234, "name": "Jeffery Lebowski"}

# get the extended user representation
GET /v1/users/1234
ACCEPT: application/vnd.myapp.v1.extended+json

# server responds with
{"id": 1234, "name": "Jeffery Lebowski", "sport": "Bowling"}

Am I correctly understanding the concept of representations in REST? Or is the concept of resource representations only applicable to content types and content negotiation?

If so, how can I document the various representations that my API can return? It doesn't seem like either of the big documentation tools (swagger.io or RAML) support documenting multiple schema representations of a single resource.