Where JSON:api meets OpenAPI and Object Schemas

1

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 :coffee: 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 Person.

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., data, links, relationships, etc., providing example responses, or should I adjust the persistence model at the top-level, i.e., have type and 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.

Thanks!

2

I found this in these forums, OpenAPI 3.0 spec that conforms to JSON:api. This is a start I think.

Doesn’t really discuss the persistence model though. This is probably the curtain I’m trying to pull down the most, modeling the DynamoDB objects. Do they need to conform to the JSON:api at the Resource Object level? For example, my model looks something like this (obfuscated intentionally):

{
  "ver": 1625063965
  "id": "840cafbe-33a7-4c56-9ae9-d76726be1eb5"
  "deleted": false
  "personId": 12345
  ...
}

Does this need to meet the JSON:api? Maybe that’s the simpler question I can’t answer yet as I learn.

3

No. It does not need to meet the spec. It is an implementation detail of the API, not the persistence model. I sort of knew that, but needed to post. Part of this is also being the new dev here and not having the tribal knowledge of the dev I replaced.