Update No. my persistence model does not need to meet the JSON:api spec.
It is an implementation detail of the API, not the persistence model. I sort of knew that, but needed to post, have a and ruminate on the question with colleagues. Part of this is also being the new dev and not having the tribal knowledge of the dev I replaced.
I have a given schema for a resource defined in my OpenAPI
yaml, let’s call it a
Should I be defining my schemas per the JSON:API, see the
links in the following:
Person: type: object properties: type: type: string description: |- Used to describe resource objects that share common attributes and relationships, e.g., "people" id: type: string description: A system generated UUID. format: uuid links: #should this even be defined in the OpenAPI, or required of the implementation type: object required: - self properties: self: type: string related: type: string attributes: type: object required: - name1 - email properties: ver: type: number format: float deleted: type: number personId: type: number description: person number.
Or should the schema follow the model of the persistence implementation/repository and allow the API implementation address the JSON:api model, e.g.,
relationships, etc., providing
example responses, or should I adjust the persistence model at the top-level, i.e., have
id and provide a
data object per the JSON:api. I have a sense that the latter is correct, but haven’t found any examples to review w.r.t. OpenAPI following JSON:api
This is probably pretty basic, I know, but this is a bit new me (contract first dev is not, but this specific “playground” has a lot of nuance and background to grok). I don’t see a lot of implementations out there and have been digging into forums like this and my Google-fu is just sharpening on this topic.