Add getApiMaturityFromXML() in conformance-xml-parser: if apiMaturity is (#1699)

set on the element, use it; otherwise treat conformance as provisional when
the parsed expression includes provisional (including otherwiseConform with
provisionalConform plus other branches).
Use it from zcl-loader-silabs for clusters, commands, args, attributes,
events, event fields, enums, enum items, bitmaps, bitmap fields, features,
structs, and struct items.
Extend test/resource/meta/api_maturity.xml and gen-matter-api-maturity tests
for plain provisionalConform, otherwiseConform+provisional, and explicit
apiMaturity winning over conflicting conformance.

- update schema
- Github: ZAP #1664

Author: brdandu

docs/api.md

@@ -21346,6 +21346,7 @@ This module provides utilities for parsing conformance data from XML into expres
     * [~parseConformanceFromXML(operand)](#module_Validation API_ Parse conformance data from XML..parseConformanceFromXML) ⇒
     * [~parseConformanceRecursively(operand, depth, parentJoinChar)](#module_Validation API_ Parse conformance data from XML..parseConformanceRecursively) ⇒
     * [~getOptionalAttributeFromXML(element, elementType)](#module_Validation API_ Parse conformance data from XML..getOptionalAttributeFromXML) ⇒
+    * [~getApiMaturityFromXML(element)](#module_Validation API_ Parse conformance data from XML..getApiMaturityFromXML) ⇒ <code>string</code> \| <code>null</code>
 
 <a name="module_Validation API_ Parse conformance data from XML..parseConformanceFromXML"></a>
 
@@ -21424,6 +21425,22 @@ Log warnings to zap.log if both optional attribute and conformance are defined
 | element | <code>\*</code> | 
 | elementType | <code>\*</code> | 
 
+<a name="module_Validation API_ Parse conformance data from XML..getApiMaturityFromXML"></a>
+
+### Validation API: Parse conformance data from XML~getApiMaturityFromXML(element) ⇒ <code>string</code> \| <code>null</code>
+Determine the effective apiMaturity for an Data Model XML element.
+
+If the element has an explicit 'apiMaturity' attribute, return it as-is.
+Otherwise, if the element's conformance contains a <provisionalConform/>
+(including nested conformance tags), return 'provisional'.
+Return null when neither source specifies maturity.
+
+**Kind**: inner method of [<code>Validation API: Parse conformance data from XML</code>](#module_Validation API_ Parse conformance data from XML)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| element | <code>\*</code> | XML element from xml2js |
+
 <a name="module_Validation API_ Validation APIs"></a>
 
 ## Validation API: Validation APIs

src-electron/validation/conformance-xml-parser.js

@@ -194,5 +194,34 @@ function getOptionalAttributeFromXML(element, elementType) {
   }
 }
 
+/**
+ * Determine the effective apiMaturity for an Data Model XML element.
+ *
+ * If the element has an explicit 'apiMaturity' attribute, return it as-is.
+ * Otherwise, if the element's conformance contains a <provisionalConform/>
+ * (including nested conformance tags), return 'provisional'.
+ * Return null when neither source specifies maturity.
+ *
+ * @param {*} element XML element from xml2js
+ * @returns {string|null}
+ */
+function getApiMaturityFromXML(element) {
+  if (element && element.$ && element.$.apiMaturity) {
+    return element.$.apiMaturity
+  }
+  let conformance = parseConformanceFromXML(element)
+  if (
+    conformance &&
+    conformEvaluator.checkIfExpressionHasOperand(
+      conformance,
+      dbEnum.conformanceTag.provisional
+    )
+  ) {
+    return dbEnum.conformanceVal.provisional
+  }
+  return null
+}
+
 exports.parseConformanceFromXML = parseConformanceFromXML
 exports.getOptionalAttributeFromXML = getOptionalAttributeFromXML
+exports.getApiMaturityFromXML = getApiMaturityFromXML

src-electron/zcl/zcl-loader-silabs.js

@@ -502,7 +502,7 @@ function prepareCluster(cluster, context, isExtension = false) {
       }
       ret.introducedIn = cluster.$.introducedIn
       ret.removedIn = cluster.$.removedIn
-      ret.apiMaturity = cluster.$.apiMaturity
+      ret.apiMaturity = conformParser.getApiMaturityFromXML(cluster)
     }
   }
 
@@ -536,7 +536,7 @@ function prepareCluster(cluster, context, isExtension = false) {
           command.$.disableDefaultResponse == 'true' ? false : true,
         isFabricScoped: command.$.isFabricScoped == 'true',
         isLargeMessage: quality ? quality.largeMessage == 'true' : false,
-        apiMaturity: command.$.apiMaturity
+        apiMaturity: conformParser.getApiMaturityFromXML(command)
       }
       cmd.access = extractAccessIntoArray(command)
       if (cmd.manufacturerCode == null) {
@@ -571,7 +571,7 @@ function prepareCluster(cluster, context, isExtension = false) {
               fieldIdentifier: lastFieldId,
               introducedIn: arg.$.introducedIn,
               removedIn: arg.$.removedIn,
-              apiMaturity: arg.$.apiMaturity
+              apiMaturity: conformParser.getApiMaturityFromXML(arg)
             })
         })
       }
@@ -588,7 +588,7 @@ function prepareCluster(cluster, context, isExtension = false) {
         side: event.$.side,
         conformance: conformParser.parseConformanceFromXML(event),
         priority: event.$.priority,
-        apiMaturity: event.$.apiMaturity,
+        apiMaturity: conformParser.getApiMaturityFromXML(event),
         description: event.description ? event.description[0].trim() : '',
         isOptional: conformParser.getOptionalAttributeFromXML(event, 'event'),
         isFabricSensitive: event.$.isFabricSensitive == 'true'
@@ -617,7 +617,7 @@ function prepareCluster(cluster, context, isExtension = false) {
               fieldIdentifier: lastFieldId,
               introducedIn: field.$.introducedIn,
               removedIn: field.$.removedIn,
-              apiMaturity: field.$.apiMaturity
+              apiMaturity: conformParser.getApiMaturityFromXML(field)
             })
           }
         })
@@ -726,7 +726,7 @@ function prepareCluster(cluster, context, isExtension = false) {
         isFabricSensitive: isAccessFabricSensitive(attribute),
         entryType: attribute.$.entryType,
         mustUseTimedWrite: attribute.$.mustUseTimedWrite == 'true',
-        apiMaturity: attribute.$.apiMaturity,
+        apiMaturity: conformParser.getApiMaturityFromXML(attribute),
         isChangeOmitted: quality ? quality.changeOmitted == 'true' : false,
         persistence: quality ? quality.persistence : null
       }
@@ -1410,7 +1410,7 @@ function prepareEnumOrBitmap(db, packageId, a, dataType, typeMap) {
         ? [{ $: { code: a.$.cluster_code[0] } }]
         : null, // else case: Treating features in a cluster as a bitmap
     discriminator_ref: dataType,
-    apiMaturity: a.$.apiMaturity
+    apiMaturity: conformParser.getApiMaturityFromXML(a)
   }
 }
 
@@ -1467,7 +1467,7 @@ async function processEnumItems(db, filePath, packageId, knownPackages, data) {
           name: item.$.name,
           value: parseInt(item.$.value),
           fieldIdentifier: lastFieldId,
-          apiMaturity: item.$.apiMaturity
+          apiMaturity: conformParser.getApiMaturityFromXML(item)
         })
       })
     }
@@ -1570,7 +1570,7 @@ async function processBitmapFields(
             name: item.$.name,
             mask: parseInt(item.$.mask),
             fieldIdentifier: lastFieldId,
-            apiMaturity: item.$.apiMaturity
+            apiMaturity: conformParser.getApiMaturityFromXML(item)
           })
         })
       }
@@ -1605,7 +1605,7 @@ async function processBitmapFields(
           name: item.$.name,
           mask: 1 << itemBit,
           fieldIdentifier: itemBit,
-          apiMaturity: item.$.apiMaturity
+          apiMaturity: conformParser.getApiMaturityFromXML(item)
         })
       })
     )
@@ -1631,7 +1631,7 @@ function prepareStruct(a, dataType) {
     cluster_code: a.cluster ? a.cluster : null,
     discriminator_ref: dataType,
     isFabricScoped: a.$.isFabricScoped == 'true',
-    apiMaturity: a.$.apiMaturity
+    apiMaturity: conformParser.getApiMaturityFromXML(a)
   }
 }
 
@@ -1691,7 +1691,7 @@ async function processStructItems(db, filePath, packageIds, data, context) {
           isNullable: item.$.isNullable == 'true' ? true : false,
           isOptional: item.$.optional == 'true' ? true : false,
           isFabricSensitive: item.$.isFabricSensitive == 'true' ? true : false,
-          apiMaturity: item.$.apiMaturity
+          apiMaturity: conformParser.getApiMaturityFromXML(item)
         })
       })
     }

test/gen-matter-api-maturity.test.js

@@ -103,6 +103,25 @@ test(
       'optional int8u attribute provisionalAttribute = 1 (provisional);'
     )
 
+    // apiMaturity is derived from conformance ONLY when no explicit
+    // apiMaturity attribute is present on the XML element.
+    expect(ept).toContain(
+      'optional int8u attribute conformProvisionalAttr = 5 (provisional);'
+    )
+    expect(ept).toContain(
+      'optional int8u attribute otherwiseProvisionalAttr = 6 (provisional);'
+    )
+    // An explicit apiMaturity attribute is authoritative: conformance never
+    // overrides it, even when the two disagree.
+    expect(ept).toContain(
+      'optional int8u attribute contradictoryApiMaturityAttr = 7 (deprecated);'
+    )
+    expect(ept).not.toContain('contradictoryApiMaturityAttr = 7 (provisional)')
+    // Explicit 'internal' apiMaturity is preserved regardless of conformance.
+    expect(ept).toContain(
+      'optional int8u attribute internalWithMandatoryConformAttr = 8 (internal);'
+    )
+
     // Maturity for structures should be correct
     expect(ept).toContain('struct StableStruct {')
     expect(ept).toContain('struct ProvisionalStruct (provisional) {')

test/resource/meta/api_maturity.xml

@@ -67,6 +67,23 @@ limitations under the License.
     <attribute side="server" code="0x0003" define="STRUCT_ATTR_1" type="StableStruct" writable="true" optional="true">StructAttr1</attribute>
     <attribute side="server" code="0x0004" define="STRUCT_ATTR_2" type="ProvisionalStruct" writable="true" optional="true">StructAttr2</attribute>
 
+    <!-- No 'apiMaturity' attribute; <provisionalConform/> fills it in as 'provisional'. -->
+    <attribute side="server" code="0x0005" define="CONFORM_PROVISIONAL_ATTR" type="INT8U" writable="true" optional="true">ConformProvisionalAttr<provisionalConform/></attribute>
+    <!-- No 'apiMaturity' attribute; provisional under <otherwiseConform> (spec-style). -->
+    <attribute side="server" code="0x0006" define="OTHERWISE_PROVISIONAL_ATTR" type="INT8U" writable="true" optional="true">OtherwiseProvisionalAttr<otherwiseConform>
+      <provisionalConform/>
+      <mandatoryConform>
+        <greaterOrEqualTerm>
+          <revision value="current"/>
+          <revision value="2"/>
+        </greaterOrEqualTerm>
+      </mandatoryConform>
+    </otherwiseConform></attribute>
+    <!-- Explicit 'apiMaturity' always wins; conformance never overrides it even when they disagree. -->
+    <attribute apiMaturity="deprecated" side="server" code="0x0007" define="CONTRADICTORY_ATTR" type="INT8U" writable="true" optional="true">ContradictoryApiMaturityAttr<provisionalConform/></attribute>
+    <!-- Explicit 'internal' is Silabs-specific and preserved regardless of conformance. -->
+    <attribute apiMaturity="internal" side="server" code="0x0008" define="INTERNAL_WITH_M_ATTR" type="INT8U" writable="true" optional="true">InternalWithMandatoryConformAttr<mandatoryConform/></attribute>
+
     <command source="client" code="0x00" name="StableCommand" response="StableCommandResponse" optional="false" apiMaturity="provisional">
       <description>A Test command</description>
       <access op="invoke" privilege="administer"/>

zcl-builtin/shared/schema/zcl.xsd

@@ -585,6 +585,8 @@ This schema describes the format of the XML files, that describe the ZCL specifi
         <xs:element ref="otherwiseConform"/>
         <xs:element ref="deprecateConform"/>
         <xs:element ref="describedConform"/>
+        <xs:element ref="provisionalConform"/>
+        <xs:element ref="disallowConform"/>
       </xs:choice>
       <xs:attribute name="cli"/>
       <xs:attribute name="cliFunctionName" type="xs:string"/>
@@ -617,6 +619,8 @@ This schema describes the format of the XML files, that describe the ZCL specifi
         <xs:element ref="otherwiseConform"/>
         <xs:element ref="deprecateConform"/>
         <xs:element ref="describedConform"/>
+        <xs:element ref="provisionalConform"/>
+        <xs:element ref="disallowConform"/>
       </xs:choice>
       <xs:attribute name="code" type="zclCode" use="optional"/>
       <xs:attribute name="default" use="optional"/>