Add CreationParameters property to PaYamlV3 OM

schemas/pa-yaml/v3.0/pa.schema.yaml

@@ -56,7 +56,7 @@ definitions:
     type: object
     additionalProperties: false
     properties:
-      Variant: { $ref: "#/definitions/Control-variant-name" }
+      CreationParameters: { $ref: "#/definitions/InstanceCreationParameters" }
       Properties: { $ref: "#/definitions/Properties-formula-map" }
       Groups: { $ref: "#/definitions/Groups-of-controls" }
       Children: { $ref: "#/definitions/Children-Control-instance-sequence" }
@@ -165,11 +165,6 @@ definitions:
   ControlTypeId-1P-controls-enum:
     true
 
-  Control-variant-name:
-    description: The variant of a control template being instantiated.
-    allOf:
-      - $ref: "#/definitions/entity-name"
-
   Control-instance:
     type: object
     required: [Control]
@@ -207,11 +202,42 @@ definitions:
       additionalProperties: false
       properties:
         Control: true
-        Variant: { $ref: "#/definitions/Control-variant-name" }
+        CreationParameters: { $ref: "#/definitions/InstanceCreationParameters" }
         Properties: true
         Groups: { $ref: "#/definitions/Groups-of-controls" }
         Children: { $ref: "#/definitions/Children-Control-instance-sequence" }
 
+  InstanceCreationParameters:
+    description: A set of optional internal creation parameters coming from the Maker.
+    type: object
+    additionalProperties: false
+    properties:
+      Variant:
+        type: string
+        minLength: 1
+      Layout:
+        type: string
+        minLength: 1
+      ParentTemplate:
+        description: Metadata needed to identify the parent template that originally created this instance.
+        type: object
+        additionalProperties: false
+        properties:
+          CompositionName:
+            description: The name of the composition template that originally created this instance.
+            type: string
+            minLength: 1
+          Variant:
+            description: The variant of the parent template that originally created this instance.
+            type: string
+            minLength: 1
+      MetadataId:
+        type: string
+        minLength: 1
+      StyleName:
+        type: string
+        minLength: 1
+
   Groups-of-controls:
     description: |-
       A mapping of groups of controls under this container. The keys of this object represent the name of the Group.
@@ -424,10 +450,12 @@ definitions:
   entity-name:
     description: The base requirements for a named entity in an app.
     type: string
+    minLength: 1
 
   entity-property-name:
     description: The base requirements for a property of an entity in an app.
     type: string
+    minLength: 1
 
   pfx-function-parameters:
     type: array

src/Persistence/PaYaml/Models/ISupportsIsEmpty.cs

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.PowerPlatform.PowerApps.Persistence.PaYaml.Models;
+
+/// <summary>
+/// An interface for objects that can be checked for whether it can be considered 'empty', namely that a non-null instance may have no properties which are not considered empty.<br/>
+/// Often used in serialization to determine whether a property could be treated as a 'null'.
+/// </summary>
+public interface ISupportsIsEmpty
+{
+    bool IsEmpty();
+}
+
+public static class SupportsIsEmptyExtensions
+{
+    public static T? EmptyToNull<T>(this T? instance)
+        where T : notnull, ISupportsIsEmpty
+    {
+        return instance is null || instance.IsEmpty() ? default : instance;
+    }
+}

src/Persistence/PaYaml/Models/SchemaV3/ControlInstance.cs

@@ -20,12 +20,12 @@ public ControlInstance(string controlTypeId)
     [property: YamlMember(Alias = "Control")]
     public required string ControlTypeId { get; init; }
 
-    public string? Variant { get; init; }
-
     public string? ComponentName { get; init; }
 
     public string? ComponentLibraryUniqueName { get; init; }
 
+    public InstanceCreationParameters? CreationParameters { get; init; }
+
     public NamedObjectMapping<PFxExpressionYaml>? Properties { get; init; }
 
     public NamedObjectMapping<ControlGroup>? Groups { get; init; }

src/Persistence/PaYaml/Models/SchemaV3/InstanceCreationParameters.cs

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.PowerPlatform.PowerApps.Persistence.PaYaml.Models.SchemaV3;
+
+/// <summary>
+/// Optional parameters for creating an instance of a control or screen.
+/// This object only contains editor-state parameters which are not generally known to customers/authors, and is not expected to be modified by them.
+/// </summary>
+public record InstanceCreationParameters : ISupportsIsEmpty
+{
+    public string? Variant { get; init; }
+
+    public string? Layout { get; init; }
+
+    public ParentTemplateCreationParameter? ParentTemplate { get; init; }
+
+    public string? MetadataId { get; init; }
+
+    public string? StyleName { get; init; }
+
+    public bool IsEmpty()
+    {
+        return Variant == null
+            && Layout == null
+            && (ParentTemplate == null || ParentTemplate.IsEmpty())
+            && MetadataId == null
+            && StyleName == null;
+    }
+}
+
+public class ParentTemplateCreationParameter : ISupportsIsEmpty
+{
+    public string? CompositionName { get; init; }
+
+    public string? Variant { get; init; }
+
+    public bool IsEmpty()
+    {
+        return CompositionName == null && Variant == null;
+    }
+}

src/Persistence/PaYaml/Models/SchemaV3/ScreenInstance.cs

@@ -7,7 +7,7 @@ namespace Microsoft.PowerPlatform.PowerApps.Persistence.PaYaml.Models.SchemaV3;
 
 public record ScreenInstance : IPaControlInstanceContainer
 {
-    public string? Variant { get; init; }
+    public InstanceCreationParameters? CreationParameters { get; init; }
 
     public NamedObjectMapping<PFxExpressionYaml>? Properties { get; init; }
 

src/schemas-tests/pa-yaml/v3.0/Examples/Src/Screens/FormsScreen2.pa.yaml

@@ -4,7 +4,8 @@ Screens:
     Children:
       - ScreenContainer1:
           Control: GroupContainer
-          Variant: horizontalAutoLayoutContainer
+          CreationParameters:
+            Variant: horizontalAutoLayoutContainer
           Properties:
             Fill: =RGBA(245, 245, 245, 1)
             Height: =Parent.Height
@@ -21,7 +22,8 @@ Screens:
           Children:
             - LeftContainer1:
                 Control: GroupContainer
-                Variant: verticalAutoLayoutContainer
+                CreationParameters:
+                  Variant: verticalAutoLayoutContainer
                 Properties:
                   Fill: =RGBA(255, 255, 255, 1)
                   LayoutDirection: =LayoutDirection.Vertical
@@ -45,7 +47,8 @@ Screens:
                       Children:
                         - "First Name_DataCard1":
                             Control: TypedDataCard
-                            Variant: textualEditCard
+                            CreationParameters:
+                              Variant: textualEditCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="firstname"
@@ -120,7 +123,8 @@ Screens:
 
                         - "Last Name_DataCard1":
                             Control: TypedDataCard
-                            Variant: textualEditCard
+                            CreationParameters:
+                              Variant: textualEditCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="lastname"
@@ -195,7 +199,8 @@ Screens:
 
                         - "Company Name_DataCard1":
                             Control: TypedDataCard
-                            Variant: blankPolymorphicEditCard
+                            CreationParameters:
+                              Variant: blankPolymorphicEditCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="_parentcustomerid_value"
@@ -211,7 +216,8 @@ Screens:
 
                         - "Job Title_DataCard1":
                             Control: TypedDataCard
-                            Variant: textualEditCard
+                            CreationParameters:
+                              Variant: textualEditCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="jobtitle"
@@ -286,7 +292,8 @@ Screens:
 
                         - "Mobile Phone_DataCard1":
                             Control: TypedDataCard
-                            Variant: textualEditCard
+                            CreationParameters:
+                              Variant: textualEditCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="mobilephone"
@@ -361,7 +368,8 @@ Screens:
 
                         - "User Name_DataCard1":
                             Control: TypedDataCard
-                            Variant: textualEditCard
+                            CreationParameters:
+                              Variant: textualEditCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="adx_identity_username"
@@ -436,7 +444,8 @@ Screens:
 
                         - "Address 1_DataCard1":
                             Control: TypedDataCard
-                            Variant: textualViewCard
+                            CreationParameters:
+                              Variant: textualViewCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="address1_composite"
@@ -478,7 +487,8 @@ Screens:
 
                         - Website_DataCard1:
                             Control: TypedDataCard
-                            Variant: urlEditCard
+                            CreationParameters:
+                              Variant: urlEditCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="websiteurl"
@@ -551,7 +561,8 @@ Screens:
 
                         - Birthday_DataCard1:
                             Control: TypedDataCard
-                            Variant: dateEditCard
+                            CreationParameters:
+                              Variant: dateEditCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="birthdate"
@@ -623,7 +634,8 @@ Screens:
 
                         - Description_DataCard1:
                             Control: TypedDataCard
-                            Variant: textualMultiLineEditCard
+                            CreationParameters:
+                              Variant: textualMultiLineEditCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="description"
@@ -698,7 +710,8 @@ Screens:
 
                         - "Full Name_DataCard1":
                             Control: TypedDataCard
-                            Variant: textualViewCard
+                            CreationParameters:
+                              Variant: textualViewCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="fullname"
@@ -740,7 +753,8 @@ Screens:
 
                         - Email_DataCard1:
                             Control: TypedDataCard
-                            Variant: textualEditCard
+                            CreationParameters:
+                              Variant: textualEditCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="emailaddress1"
@@ -815,7 +829,8 @@ Screens:
 
                         - "Business Phone_DataCard1":
                             Control: TypedDataCard
-                            Variant: textualEditCard
+                            CreationParameters:
+                              Variant: textualEditCard
                             Properties:
                               BorderStyle: =BorderStyle.Solid
                               DataField: ="telephone1"
@@ -890,7 +905,8 @@ Screens:
 
             - RightContainer1:
                 Control: GroupContainer
-                Variant: verticalAutoLayoutContainer
+                CreationParameters:
+                  Variant: verticalAutoLayoutContainer
                 Properties:
                   Fill: =RGBA(255, 255, 255, 1)
                   LayoutDirection: =LayoutDirection.Vertical

src/schemas-tests/pa-yaml/v3.0/Examples/Src/Screens/Screen1.pa.yaml

@@ -35,7 +35,8 @@ Screens:
             Y: =138
       - Gallery1:
           Control: Gallery
-          Variant: BrowseLayout_Vertical_TwoTextOneImageVariant_ver5.0
+          CreationParameters:
+            Variant: BrowseLayout_Vertical_TwoTextOneImageVariant_ver5.0
           Properties:
             DelayItemLoading: =true
             Height: =479
@@ -53,7 +54,8 @@ Screens:
                   OnSelect: =Select(Parent)
             - NextArrow1:
                 Control: Icon
-                Variant: ChevronRight
+                CreationParameters:
+                  Variant: ChevronRight
                 Properties:
                   AccessibleLabel: =Self.Tooltip
                   Color: =RGBA(166, 166, 166, 1)