Tagged union type declarations

[jeskew]

Is your feature request related to a problem? Please describe.
When declaring an object parameter, a template author may wish to accept a strict enumeration of object shapes that are not necessarily mutually compatible. This is most likely to come up in conjunction with #9229, as resource types within the az namespace frequently use discriminated object types.

Describe the solution you'd like
There should be a simple way to declare a custom tagged union within a template. Following TypeScript's example, this might look something like:

type snap = {
  type: 'snap'
  value: string
}

type crackle = {
  type: 'crackle'
  value: int
}

type pop = {
  type: 'pop'
  value: bool
}

type cereal = snap | crackle | pop

The above approach requires the compiler to detect that the union can be collapsed to a tagged union of objects, as other union types that would be permitted in TypeScript (e.g., string | int) are not permitted in the ARM runtime. This syntax might strike users not accustomed to TypeScript as verbose since the tag name needs to be repeated in each union member.

Another possible syntax would borrow from Rust's enums:

@discriminator('type')
type cereal = {
  snap { value: string }
  crackle { value: int }
  pop { value: bool }
}

The distinction between an enum with three members and an object with three properties might be a bit subtle (both for users and for the compiler), as it's only communicated here via the lack of colon (:) tokens following each tag value.

There will also need to be a way to express such a constraint in the compiled JSON template.

[jeskew]

Alternative syntax proposal from @WhitWaldo in #9369:

What I'd really like to have is something like the following similar to what I previously requested in my interfaces request, but modified to reflect the current custom types styling. I suggest borrowing TypeScript's 'extends' keyword to allow a type to inherit all the properties of another type as well as abstract to indicate that instance cannot be created of the abstract type itself, but one can only use those types that inherit from it.

abstract type partitionScheme = { //Note the use of abstract here because we don't want any values simply passing in a plain > partitionScheme
 partitionScheme: string
}

type namedPartitionScheme extends partitionScheme = { //Note the use of TypeScript's 'extends' keyword
 partitionScheme: 'Named' //I can set constants today, but here it would be required per its existence in partitionScheme
 names: string[]
}

type singletonPartitionScheme extends partitionScheme = {
 partitionScheme: 'Singleton'
}

type uniformInt64RangedPartitionScheme extends partitionScheme = {
 partitionScheme: 'UniformInt64Range'
 count: int
 low: -9223372036854775808
 high: 9223372036854775807
}

type serviceFabricService = {
 name: string
 properties: {
   partitionDescription: partitionScheme //Allowing anything that implements partitionScheme to be set here, absent partitionScheme itself because of the abstract keyword
 }
}

[slavizh]

The last proposal seems the most easier to read for me if that is the only thing we classify upon.

[jeskew]

Just wanted to add some strawman syntax variations for comparison. To give a more complete example, each snippet describes the shape of the CertificateProperties shape from Microsoft.AppPlatform@2022-12-01.

Unions via inheritance

Based on the proposal in #9369

abstract type CertificateProperties = {
  type: string
  activateDate: string
  dnsNames: string[]
  expirationDate: string
  issuedDate: string
  issuer: string
  provisioningState: 'Creating' | 'Deleting' | 'Failed' | 'Succeeded' | 'Updating'
  subjectName: string
  thumbprint: string
}

type ContentCertificateProperties extends CertificateProperties = {
  type: 'ContentCertificate'
  content: string
}

type KeyVaultCertificateProperties extends CertificateProperties = {
  type: 'KeyVaultCertificate'
  certVersion: string
  excludePrivateKey: bool
  keyVaultCertName: string
  vaultUri: string
}

If this were implemented, abstract and extends would be highlighted as keywords (the same color and font weight as type).

TypeScript-style discriminated unions

type ContentCertificateProperties = {
  type: 'ContentCertificate'
  activateDate: string
  dnsNames: string[]
  expirationDate: string
  issuedDate: string
  issuer: string
  provisioningState: 'Creating' | 'Deleting' | 'Failed' | 'Succeeded' | 'Updating'
  subjectName: string
  thumbprint: string
  content: string
}

type KeyVaultCertificateProperties = {
  type: 'KeyVaultCertificate'
  activateDate: string
  dnsNames: string[]
  expirationDate: string
  issuedDate: string
  issuer: string
  provisioningState: 'Creating' | 'Deleting' | 'Failed' | 'Succeeded' | 'Updating'
  subjectName: string
  thumbprint: string
  certVersion: string
  excludePrivateKey: bool
  keyVaultCertName: string
  vaultUri: string
}

type CertificateProperties = ContentCertificateProperties | KeyVaultCertificateProperties;

The comparison between this option and the above is a bit unfair, since there's no way inherent to the union (|) operator to declare shared properties. Let's assume the existence of an intersection (&) operator and see if that makes the example more compact.

TypeScript-style discriminated union (but with structural inheritance via &)

type CertificatePropertiesSharedProps = {
  activateDate: string
  dnsNames: string[]
  expirationDate: string
  issuedDate: string
  issuer: string
  provisioningState: 'Creating' | 'Deleting' | 'Failed' | 'Succeeded' | 'Updating'
  subjectName: string
  thumbprint: string
}

type ContentCertificateProperties = CertificatePropertiesSharedProps & {
  type: 'ContentCertificate'
  content: string
}

type KeyVaultCertificateProperties = CertificatePropertiesSharedProps & {
  type: 'KeyVaultCertificate'
  certVersion: string
  excludePrivateKey: bool
  keyVaultCertName: string
  vaultUri: string
}

type CertificateProperties = ContentCertificateProperties | KeyVaultCertificateProperties;

The intersection (&) operator could presumably be used to extend object types outside of the context of a discriminated union, too.

Inspired by Rust enums

type CertificateProperties = {
  activateDate: string
  dnsNames: string[]
  expirationDate: string
  issuedDate: string
  issuer: string
  provisioningState: 'Creating' | 'Deleting' | 'Failed' | 'Succeeded' | 'Updating'
  subjectName: string
  thumbprint: string

  discriminator type: {
    ContentCertificate: {
      content: string
    }

    KeyVaultCertificate: {
      certVersion: string
      excludePrivateKey: bool
      keyVaultCertName: string
      vaultUri: string
    }
  }
}

If this were implemented, discriminator would be highlighted as a keyword.

I'm partial to this one mostly because it would be the easiest to implement of the three. There is no need to infer which property is the discriminator, and shared properties are explicitly defined.

[kalbert312]

This feature still needs be reenabled. It is temporarily disabled while backend features wait to go out to support it.