Handling JSON:API structures in stoplight editor

When building a JSON:API-style API, models are embedded within metadata wrappers of the form:

{
  data: {
    id: <item identifier>,
    type: <item type>,
    attributes: {
      key: value,
      key2: value
    }
  }
}

As far as I can see, the model only describes the attributes element, perhaps the id value as well. I’m not clear how I should model this in stoplight in a way that remains functional. The data wrapper is not part of the model, and it may be accompanied by other metadata elements such as links and relation elements. Also, while it appears in this wrapper in responses, the same structure is not used for requests. How should I model these things in Stoplight? Perhaps something like:

{
  data: {
    id: <item identifier>,
    type: <item type>,
    attributes: $ref(./models/thing.v1.yaml)
  }
}

Hi Marcus,

In our company we use both JSON:API and Stoplight as well.
We currently approach modeling like this:

{ data: $ref(./models/thing.v1.yaml }

where the model is separate from the data/meta/links wrappers, but contains id, type, attributes, relationships, links.

Would that work for you as well?

I’m not sure - I don’t think type should appear in the model at all (it’s implicit), and it would be confusing for it to appear there. Would you do it via some kind of nested model? Something like:

{ data: $ref(./models/jsonthing.v1.yaml }

and that model contains:

{
  id: <id>,
  type: thing,
  attributes: $ref(./models/thing.v1.yaml }
}

I’m also a bit concerned about using the same models for requests and responses - for example a typical POST request does not contain an id element, as that’s usually/often assigned by the service (eg. as a UUID, or an autoincrementing int), so the models for requests and responses have different forms. I don’t know how that’s supposed to be handled either!

Do you have any shareable examples of OpenAPI docs using JSON:API and models?