Required properties and resource collections


#1

As illustrated on the “What’s New in RAML 1.0” page, when defining a resource collection it is natural to identify a family of related types. One type defines what the user has to provide when inserting a new object, another defines what is returned when we retrieve an object from the collection, and finally if we support partial updates then we need a type for that as well.

These types are similar but not identical. The server may create some properties, and so the creation type is likely to contain a subset of the object’s properties. In this case RAML inheritance can help to express this relationship. But how do we define the type used for partial updates without introducing a lot of duplication? The problem here is that we will typically have properties of an object that are required, either when inserting a new object, or retrieving it. But the properties used in the type supporting partial updates will presumably have the required property set to false, as we’d like to just set the properties that are being changed. The rule that subtypes can’t change a required property to an optional one makes sense in the traditional model of inheritance, but it presumably implies that something like User-update cannot inherit from User-base.

For small examples we can obviously just repeat the properties and their types and other details. But such an approach isn’t going to scale. So is there another way of structuring such examples in RAML 1.0 that avoids such duplication? Do we need other ways of reusing types, other than just inheritance, where we can relax things like the required rule, and perhaps be able to perform bulk modifications of all the properties?