Relationship properties

Relationships are an important part of an API or a data model: People have Friends, People have Hobbies, which are shared by other People, …

OData represents relationships as a special kind of property, a so-called navigation property which allows retrieving related entities, and also retrieving an entity together with related entities:

• a single person: http://services.odata.org/V4/(S(n4bk11pfsypujadnvn5jtwic))/TripPinServiceRW/People(‘russellwhyte’)
• the friends of this person: http://services.odata.org/V4/(S(n4bk11pfsypujadnvn5jtwic))/TripPinServiceRW/People(‘russellwhyte’)/Friends
• the person and its friends: http://services.odata.org/V4/(S(n4bk11pfsypujadnvn5jtwic))/TripPinServiceRW/People(‘russellwhyte’)?$expand=Friends

As the last example shows it makes sense to model navigation properties just as “data” properties in the /definitions section as they may be part of the response if requested with $expand. It is also necessary to tag them as special properties, and include additional metadata about the relationship:

            "Products": {
                "type": "array",
                "items": {
                    "$ref": "#/definitions/ODataDemo.Product"
                },
                "x-relationship": {
                    "partner": "Category",
                    "onDelete": {
                        "action": "Cascade"
                    }                    }
            }
        }
    },

Partner is the navigation property in the target type that leads back to the current type, onDelete describes potential side-effects of deleting an entity of the current type, and referentialConstraints describe value dependencies to the related entity.

Anyone else having similar concepts/constructs in their APIs that would make it worth making this a first-class concept in OpenAPI?

[handrews]

@sensibleish I’m one of the main JSON Schema spec authors, and one reason I’m working with the OpenAPI TSC is to work through issues where new sets of JSON Schema keywords (separate from validation) would help solve data modeling problems.

At a high level, I think some of that might help you. But your descriptions are too general for me to propose any particular solutions. I think I would need to see some possible schema (and OAS operation) arrangements you’ve considered in order to go into any more detail.

Whether you can share those or not, this sort of work will continue, either in this repository or elsewhere. The version of JSON Schema that is being adopted in OAS 3.1 makes it much easier for 3rd parties to design extension keywords, although of course tooling support is not automatic!

[sensibleish]

Appreciate the discussion. As you point out, modeling and transmission/retrieval lead to different concerns. I am working to create a set of models that mostly represent real-world things, as a reference for a bunch of future work. If I were planning for a relational database, I think these “reference” needs would be easily handled by foreign keys. But these models will mostly be used in an ecosystem of systems talking RESTful APIs, so transmission/retrieval concerns can’t be ignored.

We haven’t chosen the new content management system, which might have dictated some of my decisions here. There will likely not be a 1:1 mapping between OpenAPI model attribute data types and the CMS features. For example, the current CMS has an attribute type that is explicitly a reference to another object inside the CMS. The CMS will (hopefully) have some way of expressing whether to embed linked objects in a response, depth of references to follow, etc.

Happy to have any suggestions you may offer. Mostly just want to express support for OpenAPI having ways to express some of these things.