Referencing PR #237 as a few minutes ago it is not possible to link from resources which have internal structure, eg:

{
  "data": {
    "eab9b2af-73f0-4e13-b348-0bd4377fb06a": {
      "type": "contact",
      "name": "Some One"
      "address": {
        street: "some street"
        city: "<some city id>"
        state: "<some state id>"
        country: "<some country id>"
      }
    }
}

The spec doesn't deal with resources that have internal structure AFAIKT since it requires one to put all references under a "links" object within the resource. In my example above addresses do not have ids, they are embedded properties of a resource.

In my actual system, addresses are embedded arrays within contact resources, they have no id and cannot be resources, yet they link to other resources.

I am not sure what the rationale for embedded 'links' object it, but I have decided to abandon any conformance to json-api in my systems because of this issue plus not being able to have generic collections in linked resources and other observations commented on in PR #237.

I wish you all well with it, there is good work being done here but what works for me does not align with JSON API compromises and the many paradigms it is trying to simultaneously address.

My primary technical issues:

• links (why an object as opposed to just properties on the resource)
• server ids vs (v4) UUIDs
• typed vs generic collections (related to server ids/ UUIDs)
• polymorphism (base types vs specific types)
• schema window dressing (link templates)

I will check back from time to time with the hope things may mature enough to allow it to be a good reference for JSON APIs but my gut tells me that unless one nails down the server-id/UUID/ design choice up front then it will forever be trying to serve too many API designs simultaneously rather than being a minimal purposeful spec. As I have said before the UUID vs server assigned ID its not just about carrying an opaque field in a transport document, but is rather an entire paradigm which deeply affects the interactions between client and server when serializing object graphs and results in a very different API design to one with server assigned ids scoped to a resource type. JSON-API tries to straddle both and despite some excellent work, IMO it fails in its key objective to settle good api design once and for all.