Document-wide id


In a document, you may want to create a resource object that doesn’t correspond to a database object, and therefore, that doesn’t have a unique id from which you can recover that data.

However, the spec states:

Within a given API, each resource object’s type and id pair MUST identify a single, unique resource.

Does that imply that we should have the ability to retrieve that resource with that id?

If we want to have document-wide ids (which therefore might have a new id if the request was to be repeated), is the current solution to generate a UUIDv4 for each of those ids?

Could we standardize a way to say, “this id is document-wide, not API-wide”, to avoid having huge ids everywhere? For instance, if the id starts with an underscore, it is document-wide, otherwise it is API-wide. It doesn’t functionally break backwards compatibility: an existing id starting with _ that was assumed to be API-wide in v1.0 becomes a document-wide id which incidentally is the same across requests.


It might imply it, but I don’t believe it is required. JSON API resources are accessed via URLs, not via type + id keys (though usually there will be a strong correlation between the two).

Given this, it is a bit surprising that the resource identifier objects are not allowed to contain a related link that would enable you to retrieve the relevant resource object.


As @jlangey said, there’s no requirement that any given resource be retrievable.

For generating the required id, if UUIDs are too long, you could also use a simple prefixing strategy, like "id": "documentXXX-1" and "documentXXX-2"