Expression forms for declarations

[bterlson]

We have a need for passing enums to decorators to support the "extensible enum" pattern - a value that is effectively a string or number, but which has some known and documented values. Passing an enum expression to a decorator is a convenient way to achieve this.

All of our current declarations may have similar use cases, and anyway being consistent about allowing expression forms for declarations seems like a good thing.

Semantically, expression forms are not declarations, but may still be named. This ensures that declarations which introduce bindings are still easily visible (and not affected by deeply nested expressions).

Example syntax:

@extensible(enum Options { @dec a, b })
model MyEnum is string;

model Foo {
  x: model Bar { }
}

Potential issues:

• Without the ability to decorate arbitrary expressions, you cannot have decorated expression forms. Adding expression-level decorators would require some careful design on its own.
• Emitters may still treat expression forms as declarations. E.g. if we do the simple thing, the Foo example above will likely result in a schema for a model Bar. This may be problematic because finding the actual source for this declaration may be difficult.

[markcowl]

• How would this impact recovery? [Nick]
  • Negative, but not fatal impact [more ambiguity in error cases]
• decorators: do we allow decorated expressions as decorator parameters

@extensible(@doc("foo") enum Options { @dec a, b })
@extensible(@doc("comment") 4) // error

• colorization might be a challenge

• Assess the impact on recovery and error/handling and discuss next week.

[nguerrera]

I looked at this a bit and I don't think the impact to error recovery is at all enough to stop this proposal from going forward. There will be some work and slight experience differences, like thinking a missing ) means a declaration is being passed to a decorator. Possibly we can refine this with some different heuristics. There's certainly work and impact on tooling, but we should just cost that in. I'd add 2-3 days for that to be safe.

[markcowl]

As part of this, make sure we think about naming expression forms, see: https://github.com/Azure/cadl-azure/issues/1025

[stefan-schweiger]

It's kind of hard to follow all the discussion around the topic of extensible enums. What would actually be generated for those extensible properties? I've seen mentioned a few times the x-ms-enum pattern or using anyOf.

For example there is the "zalando" way of doing it like this, which is what I would like to do:

DeliveryMethod:
  type: string
  x-extensible-enum:
    - Parcel
    - Letter
    - Email

There is an ongoing discussion in the OpenAPI specification about this topic. Maybe some comments in there could be a good inspiration for what people are currently using to define extensible enums, and it would be great if at least a few of the more common ones could be achieved with cadl.

OAI/OpenAPI-Specification#1552