How to structure schema to include JSON:API conforming links relationships

Hi everyone,

we’re working on a model/schema in Stoplight Studio. This model is used for automated testing to check if the controller responses are correct.

We make use of this library https://github.com/sixlive/laravel-json-schema-assertions. The library supports Hyper JSON Schema, but now I’m mixing up the concepts between the specifications and JSON:API.

What we want is this

{
  "type": "order",
  "id": "1",
  "attributes": {
    "order-number": "12345",
    "state": "commissioned",
    "created-at": "2019-10-06T20:07:31.000000Z",
    "updated-at": "2019-11-18T10:22:42.000000Z",
    "reference": "22-22-22",
    "price": "860",
    "zipcode": "47700"
  },
  "relationships": {
    "customer": {
      "links": {
        "self": "https:\/\/test.localhost\/api\/orders\/1\/relationships\/customer",
        "related": "https:\/\/test.localhost\/api\/orders\/1\/customer"
      },
      "data": {
        "id": "2",
        "type": "user"
      }
    },
    "packaged-by": {
      "links": {
        "self": "https:\/\/test.localhost\/api\/orders\/1\/relationships\/packaged-by",
        "related": "https:\/\/test.localhost\/api\/orders\/1\/packaged-by"
      },
      "data": {
        "id": "3",
        "type": "user"
      }
    },
    "contacts": {
      "links": {
        "self": "https:\/\/test.localhost\/api\/orders\/1\/relationships\/contacts",
        "related": "https:\/\/test.localhost\/api\/orders\/1\/contacts"
      },
      "data": []
    }
  },
  "links": {
    "self": "https:\/\/test.localhost\/api\/orders\/1"
  }
}

to be validated by the schema.

Attributes are straight-forward, but how do I define the relationships in Stoplight Studio?

  1. Adding a relationships object, below that a customer object, then the links object with an attribute related string

or

  1. Using refs for the relationships and referring to the model/schema of that entity?

Or making use of another feature?

I’m a little lost, so some advice would be appreciated.

Kind regards,

Michael

Hey Michael,

We unfortunately don’t support JSON Hyper-Schema.

1 Like