[Spike] Reference a Model/type and add additional constraints

[dhmlau]

Timebox to 5 days

Description / Steps to reproduce / Feature proposal

Originated from: #1722

During the discussion with @raymondfeng @bajtos, there were different discussion over the support for partial update, we think a spike is needed.

Acceptance Criteria

• Read through the discussion and proposals listed in the related issues
• Build a prototype showing how it can be done
• Share the spike outcome
  • Put the summary in this issue
  • Host a spike meeting
  • Blog post proposing what to do and involve the community

Related issues

• Partial update (PATCH) over REST #1722
• OpenAPI decorator does not properly generate schemas of type Partial #1179
• [API Explorer] Fields shown but ignored #1470
• relation expects foreignKey on the Object #1719
• fix(rest): allow @patch update obj to be a Partial #1894

[jannyHou]

Some notes during the estimation meeting(feel free to edit the comment and rephrase):

Let's do the spike from a more general level, think of the big picture of customizing a model's shape, a few of points to be considered:

• how to customize the shape of model
• satisfy different requirements of property
• apply constraints
• apply validations
• given a model and properties defined in it, we may have particular expectation at the rest layer, data persistency layer, etc….come up with a general solution to satisfy different requirements.

[raymondfeng]

I would like to explore the usage of {$ref: 'ref-to-the-original-model-or-type', ...additional properties}

[bajtos]

• apply constraints
• apply validations

Please read through the discussion in #1624, it has many insights relevant for this area.

Personally, I'd prefer to narrow down the scope of this spike and stay focused on the two use cases , otherwise it may take ages to complete:

• PATCH - all properties are optional,
• CREATE - id and possibly _rev must not be present

[bajtos]

the proposal: #2646

[bajtos]

Created the following stories:

• Emit schema with all model properties optional Emit schema with all model properties optional #2652
• Emit schema excluding certain model properties Emit schema excluding certain model properties #2653
• Spike: simplify requestBody annotation with schema options Spike: simplify requestBody annotation with schema options #2654

[bajtos]

Blog post proposing what to do and involve the community

As discussed with @dhmlau, we will provide a summary in the March milestone blog post.

Closing the spike as done 🎉