Syntax ideas for supporting extension resources with lexical nesting

[anthony-c-martin]

Syntax ideas for supporting extension resources with lexical nesting

This is an open discussion thread to come up with a syntax for declaring extension resources in a manner compatible with #1363. To get started, here are the options I see:

1. Try to infer it

a) Use the fact that the fully-qualified type must be supplied

resource myParent 'My.Rp/parent@2020-01-01' = {
  name: ...

  // this is an extension resource (type contains a single '/' character)
  resource myExtension 'My.OtherRp/extension@2020-01-01' = {
    name: ...
  }

  // this is a child resource (type does not contain any '/' characters)
  resource myChild 'child@2020-01-01' = {
    name: ...
  }
}

• Pros
  • Simple and ties in with the child resource declaration.
  • No special syntax required to declare an extension resource.
• Cons
  • Subtle, possible to introduce accidental bugs.
  • Doesn't map cleanly to the proposed 'parent' syntax for refactoring.
  • Intellisense for child resource types won't be as clean as it'll have to also show all possible extension resources.

b) Use a list of known extension types to understand whether or not the provided type string is an extension resource

Not considered - this removes the 'day 0 resource support' promise.

2. Some indicator of intent in the language or type string

a) Keyword

resource myParent 'My.Rp/parent@2020-01-01' = {
  name: ...

  // 'extension' keyword
  resource myExtension 'My.OtherRp/extension@2020-01-01' extension = {
    name: ...
  }
}

b) Prefix in the type string

resource myParent 'My.Rp/parent@2020-01-01' = {
  name: ...

  // prefix for the type string (option i)
  resource myExtension 'ext://My.OtherRp/extension@2020-01-01' = {
    name: ...
  }

  // prefix for the type string (option ii)
  resource myExtension '/My.OtherRp/extension@2020-01-01' = {
    name: ...
  }

  // option iii - some other prefix (not shown)
}

• Pros
  • Author's intent is clear and unambiguous.
  • Intellisense should be able to help with suggestions.
  • Clear mapping to/from the 'scope' property.
• Cons
  • Doesn't feel very natural, will probably require looking up the syntax each time.

Current state of the 'top-level' extension/child syntax (for reference)

resource myParent 'My.Rp/parent@2020-01-01' = {
  name: ...
}

// Extension resource
// NOTE - the type string for the resource being extended is not present in this declaration
// NOTE - there's also a potential proposal to rename 'scope' => 'extends'
resource myExtension 'My.OtherRp/extension@2020-01-01' = {
  name: ...
  // declare the resource that this one is extending
  scope: myParent
}

// Child resource
// NOTE - the type string is the fully-qualified type string instead of just 'child'. This is to permit intellisense before the 'parent' property has been entered.
resource myChild 'My.Rp/parent/child@2020-01-01' = {
  name: ...
  // declare the resource that this one is a child of
  parent: myParent
}

Notes

If picking option 1, it feels like it would make sense to come up with a consistent mapping between the 'top-level' syntax and the 'nested' syntax which combines both the 'parent' & 'scope' property into one.

[rynowak]

Dumb question (I am good at those): it seems like this is functionally different because these two concepts have a different effect on how the resources are emitted....

1. Are those differences significant enough that the compiler really needs to know the difference? IDK what extensions codegen does so I can't answer this myself.
2. Are there enough semantic difference between a child resource vs an extension resource that we'll want to build tooling experiences around it?

Basically what I'm probing at, given the current state example - these look really similar (scope vs parent). Are the differences truly cosmetic or semantic?

[anthony-c-martin]

Not a dumb question at all!
They are in fact very similar concepts, but IMO different enough that the compiler does need to understand them to an extent:

• Regular resource declarations are mapped to ARM URIs by pairing up the provider, type & name segments.
• For a child resource of type Microsoft.Compute/virtualMachines/extensions with name myVm/myExtension, we would generate a URI ../Microsoft.Compute/virtualMachines/myVm/extensions/myExtension.
• Trying to work backwards from an extension resource URI (which we need to come up with some mapping for), .../Microsoft.Compute/virtualMachines/myVm/providers/Microsoft.Insights/diagnosticSettings/mySettings - this is problematic as you would have to interpret the provider as Microsoft.Compute, the type as Microsoft.Compute/virtualMachines/providers/diagnosticSettings, and the name as myVm/Microsoft.Insights/mySettings - which would mean that trying to fit to the proposed nested syntax you'd have to do something like:

  resource myVm 'Microsoft.Compute/virtualMachines@2020-06-01' = {
    name: 'myVm'
  
    // this part is odd
    resource providers 'providers' existing = {
      name: 'Microsoft.Insights'
  
      // we now need to use the parent type AND name to make a decision about the type validation
      resource diagSettings 'diagnosticSettings' = {
        name: 'mySettings'
  
        ...
      }
    }
  }

• The top-level declaration also becomes similarly confusing:

  resource myVm 'Microsoft.Compute/virtualMachines@2020-06-01' = {
    name: 'myVm'
  }
  
  resource providers 'Microsoft.Compute/virtualMachines/providers@2020-06-01' existing = {
    name: 'Microsoft.Insights'
    parent: myVm
  }
  
  // the 'type string' here becomes ambiguous because it doesn't refer to 'Microsoft.Insights' at any point
  resource diagSettings 'Microsoft.Compute/virtualMachines/providers/diagnosticSettings@2020-06-01' = {
    name: 'mySettings'
    parent: providers
  }

Basically, this boils down to the fact that if you try to interpret an extension resourceId using child resource semantics, you end up with an ambiguous type, and some type information interpreted as the name.

[alex-frankel]

I think if we can say with 100% certainty that if the RP namespace is present (My.OtherRp) it means this should be processed as an extension, then we shouldn't have any additional syntax to express that and go with option 1 - infer it.

And if the above is true, then we should use a single property name for the parent/scope when declared as a top level resource and use the same logic to distinguish between the two cases.

Basically, if there are no computationally ambiguous cases, then let's not add anything. It is a subtle different in how we process the code, but I think functionally user's don't need to care about the difference in semantics. They will know that extensions like DiagnosticSettings or Locks require the RP name.

[anthony-c-martin]

If we're happy using the type string to differentiate in the nested case, then I think we can be 100% certain:

1. If the type string contains 0 / characters, it's a child resource.
2. If the type string contains 1 / character, it's an extension resource.
3. Anything else is rejected.

The equivalent in trying to combine the scope/parent property into 1:

1. If the type string contains 1 more / character than the parent, and the parent's type is the 'parent type', it's a child resource.
2. If the type string has 1 / character, it's an extension resource.
3. Anything else is rejected.

It's a little subtle, but I think it is at least logically consistent.

[anthony-c-martin]

Some concrete examples of my previous comment.

• Nested:

  resource myParent 'My.Rp/parent@2020-01-01' = {
    name: ...
  
    // Example of (1) - child resource since the type contains 0 '/'s
    resource myChild 'child@2020-01-01' = {
      name: ...
    }
  
    // Example of (2) - extension resource since the type contains a single '/'
    resource myExtension 'My.OtherRp/extension@2020-01-01' = {
      name: ...
    }
  
    // Example of (3) - this should be rejected as there are >1 '/'s
    resource myExtension 'My.OtherRp/extension/child@2020-01-01' = {
      name: ...
    }
  }

• Combined scope/parent:

  resource myParent 'My.Rp/parent@2020-01-01' = {
    name: ...
  }
  
  // Example of (1) - child resource since the type is a child type of myParent, and contains a single extra '/'
  resource myChild My.Rp/parent/child@2020-01-01' = {
    parent: myParent
    name: ...
  }
  
  // Example of (2) - extension resource since the type contains a single '/'
  resource myExtension 'My.OtherRp/extension@2020-01-01' = {
    parent: myParent
    name: ...
  }
  
  // Example of (3) - this should be rejected as there are >1 '/'s and the type is not a child type of myParent
  resource myExtension 'My.OtherRp/extension/child@2020-01-01' = {
    parent: myParent
    name: ...
  }

[brwilkinson]

@anthony-c-martin I believe this is still an open topic ?

is this the related issue?

• Iteration with a child resource Error: required properties: "scope" #6010

[alex-frankel]

Intellisense for child resource types won't be as clean as it'll have to also show all possible extension resources.

I happen to think this is a pro, not a con. Intellisense is going to show me all possible "nested" types that I can include in a resource -- both children and extension.

[bmoore-msft]

When I look at 2b - it really makes me think we're complicating rather than simplifying (or rather we already have the answer)... To me, the cleanest is building off of the parent property (and scope as mentioned above) and then using the correct property for the correct scenario makes it much easier to master. We may not get the intellisense we want but maybe we need to solve that differently than we do today if that's the only thing we're stuck on... so I do think we need to bring this into the conversation:

resource kid 'blob' = {
  parent: storage // creates a child resource
}

resource extender 'Microsoft.Insights/diagnosticSettings' = {
  extends: storage // create an extension resource
}

From a user perspective - I'm not sure what's missing from that... (and now that I type it, not sure what's missing for intellisense/autocomplete either)

[brwilkinson]

@anthony-c-martin should we move this to an issue?

Or consolidate to:

• Proposal - simplifying resource referencing (part 2) #2246 etc?

[brwilkinson]

actually, I guess we can now close this as completed?

• Lexically scoped child resources #1516

supported syntax

param nicName string = 'aeu1peaksd2sadiag-pl-blob-snFE01.nic.b6edf073-f1e9-4b68-bb87-11f94c018aa1'
param ipconfigName string = 'privateEndpointIpConfig.c2a3a073-38c5-42ea-b1f8-4df4a13e02af'

resource nic 'Microsoft.Network/networkInterfaces@2022-11-01' existing = {
    name: nicName

    resource ipconfig 'ipConfigurations' existing = {
        name: ipconfigName
    }
}

output nic string = nic::ipconfig.properties.privateIPAddress

[brwilkinson]

I feel like there is still a related item open for extension resources ?

[brwilkinson]

moved to new issue, will close here.

• Syntax ideas for supporting extension resources with lexical nesting #10780