microsoft / microsoft/typespec

Revisit @parameterVisibility and @returnVisibility

Open
#2,318 1 comment 0 reactions 0 assignees View on GitHub
design:needed triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

I'm struggling to understand the new `@parameterVisibility` and `@returnVisibility` decorators.

I know that these were introduced to address azure/typespec-azure#3214 (patch operation should define "create" properties in request body). I think the root of that issue is that the http library assumes "patch" is "update" and there was no way to mark a "patch" to say "this is both create and update".

Stepping back, here's what the core docs say about `@visibility`:

> the following visibilities are well-known to standard libraries and should be used with standard emitters that interpret them as follows:
> - "read": output of any operation.
> - "create": input to operations that create an entity.
> - "query": input to operations that read data.
> - "update": input to operations that update data.
> - "delete": input to operations that delete data.

This combined with the documentation of [Automatic visibility in the HTTP library](https://microsoft.github.io/typespec/standard-library/http/operations#automatic-visibility) implies

- GET and HEAD requests "read data" -- because "query" visibility is automatically applied.
- POST and PUT requests "create an entity" -- because "create" visibility is automatically applied.
- PATCH and PUT requests "update data" -- because "update" visibility is automatically applied.
- DELETE requests "delete data" -- because "update" visibility is automatically applied.

But the HTTP library provides no means to deviate from this. I think what is missing is the ability to characterize an operation deviates from the above assumptions. PATCH that is "createOrUpdate" is a great example, but another common one is POST that does not "create an entity".

A decorator implemented in the HTTP library (could also be in core I suppose), say `@operationType` that could specify some combination of "create", "query", "update", or "delete" could fill this gap. The a PATCH operation that allows "create" or "update" could be defined with

```
@operationType("create", "update")
@patch op createOrUpdate(...Widget): Widget | Error;
```

and the HTTP library or downstream emitter could then "do the right thing".

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.