Tests and documentation for wrong property tags issue

common/changes/@itwin/core-backend/abhi-wrong-property-tags-testing_2025-01-29-12-36.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-backend",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-backend"
+}

common/changes/@itwin/ecschema-metadata/abhi-wrong-property-tags-testing_2025-01-29-12-36.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/ecschema-metadata",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/ecschema-metadata"
+}

core/backend/src/test/ecdb/ECSqlStatement.test.ts

@@ -3127,8 +3127,8 @@ describe("ECSqlStatement", () => {
           <ECProperty propertyName="booleanProperty" typeName="boolean"/>
           <ECProperty propertyName="blobProperty" typeName="binary"/>
           <ECProperty propertyName="doubleProperty" typeName="double"/>
-          <ECProperty propertyName="customIdProperty" typeName="id"/>
-          <ECProperty propertyName="customIdSetProperty" typeName="idSet"/>
+          <ECProperty propertyName="customIdProperty" typeName="string"/>
+          <ECProperty propertyName="customIdSetProperty" typeName="string"/>
           <ECProperty propertyName="intProperty" typeName="int"/>
           <ECProperty propertyName="longProperty" typeName="long"/>
           <ECProperty propertyName="stringProperty" typeName="string"/>

core/ecschema-metadata/src/test/Metadata/Schema.test.ts

@@ -1235,6 +1235,49 @@ describe("Schema", () => {
         deserializeAndTestJSONSync(JSON.stringify(schemaJson), testRelationshipStrength);
         await testSerialization(_schema, false, unsupportedVersionError);
       });
+
+      it("should throw an error for version previous to current, when encountered an unknown type", async () => {
+        const schemaXml = `<?xml version="1.0" encoding="utf-8"?>
+            <ECSchema schemaName="Test" alias="test" version="1.0.0" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.${Schema.currentECSpecMajorVersion}.${Schema.currentECSpecMinorVersion}">
+          <ECStructClass typeName="PrimStruct">
+            <ECProperty propertyName="p2d" typeName="Point2d" />
+            <ECProperty propertyName="p3d" typeName="Point3d" />
+          </ECStructClass>
+          <ECEntityClass typeName="UseOfWrongPropertyTags">
+            <ECProperty propertyName="Struct" typeName="PrimStruct" />
+            <ECStructArrayProperty propertyName="Struct_Array" typeName="PrimStruct" />
+          </ECEntityClass>
+          </ECSchema>`;
+
+          _schema = new Schema(_context);
+          try {
+            await _xmlReader.readSchema(_schema, new DOMParser().parseFromString(schemaXml));
+          } catch (err: any) {
+            assert.equal(err.message, `The provided primitive type, Test.PrimStruct, is not a valid PrimitiveType or Enumeration.`);
+          }
+      });
+
+      it("should throw an error for current version, when encountered an unknown type", async () => {
+        const schemaXml = `<?xml version="1.0" encoding="utf-8"?>
+            <ECSchema schemaName="Test" alias="test" version="1.0.0" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.${Schema.currentECSpecMajorVersion}.${Schema.currentECSpecMinorVersion - 1}">
+          <ECStructClass typeName="PrimStruct">
+            <ECProperty propertyName="p2d" typeName="Point2d" />
+            <ECProperty propertyName="p3d" typeName="Point3d" />
+          </ECStructClass>
+          <ECEntityClass typeName="UseOfWrongPropertyTags">
+            <ECProperty propertyName="Struct" typeName="PrimStruct" />
+            <ECStructArrayProperty propertyName="Struct_Array" typeName="PrimStruct" />
+          </ECEntityClass>
+          </ECSchema>`;
+
+          _schema = new Schema(_context);
+          try {
+            await _xmlReader.readSchema(_schema, new DOMParser().parseFromString(schemaXml));
+          } catch (err: any) {
+            assert.equal(err.message, `The provided primitive type, Test.PrimStruct, is not a valid PrimitiveType or Enumeration.`);
+          }
+      });
+
     });
   });
 

docs/learning/backend/HandlingUnknownAndWrongSchemaElements.md

@@ -0,0 +1,12 @@
+## Handling of schemas with unknown/wrong elements
+
+All schemas using the current or older ECXml versions will fail to deserialize if they encounter incorrect or unknown property tags.
+When this occurs, an error will be logged, clearly stating the cause of failure and explaining that deserialization process cannot proceed
+due to the unrecognized properties.
+
+### Behavior of wrong property tags across different versions during deserialization
+
+| Version | Behavior during deserialization |
+| - | - |
+| Versions older than latest (known to ECDb runtime) | Throws an error |
+| Latest Version | Throws an error |

docs/learning/backend/HandlingUnknownSchemaElements.md → docs/learning/backend/HandlingUnknownAndWrongSchemaElementsForNewerVersions.md

@@ -1,11 +1,8 @@
 ## Handling of newer schemas by older ECDb runtimes
 
-A schema with a newer ECXml version might contain elements not known to the ECDb runtime being used as it's older.
-A read compatible but write incompatible schema (only ECXml minor version incremented) cannot be imported into the iModel.
-However, the schema can be deserialized and loaded into memory.
-This schema is also then restricted from being serialized to a file or a string.
+A schema with a newer ECXml version might contain elements not recognized by the older ECDb runtime. Additionally, a schema might include incorrect elements, such as an ECProperty tag used to denote a struct inside an entity class. A read-compatible but write-incompatible schema (with only an ECXml minor version increment) cannot be imported into the iModel. However, any schema, except for version 3.2 of the ECXml schema, can be deserialized and loaded into memory. This schema version is also restricted from being serialized to a file or a string.
 
-### Behavior during deserialization
+### Behavior of newer schemas during deserialization
 
 | Schema Element or Attribute | Behavior during deserialization |
 | - | - |
@@ -17,7 +14,6 @@ This schema is also then restricted from being serialized to a file or a string.
 | Unknown backing type in ECEnumeration | Defaults to `string` |
 | Unknown relationship class strength | Defaults to `referencing` |
 
-
 ### Reading a newer schema already present in a newer iModel
 
 A newer iModel may be containing schemas that are write incompatible due to elements unknown to the ECDb runtime being used.
@@ -33,4 +29,4 @@ When reading such a schema with an older ECDb runtime, a reduced form of the sch
 | Unknown backing type in ECEnumeration | The enumeration will not be loaded |
 | Unknown relationship class strength | The relationship class and it's corresponding navigation properties will not be loaded |
 | Unknown relationship class direction | The relationship class and it's corresponding navigation properties will not be loaded |
-| Unknown navigation property direction | The navigation property will not be loaded |
+| Unknown navigation property direction | The navigation property will not be loaded |

docs/learning/backend/IModelDb.md

@@ -52,6 +52,6 @@ With the general evolution of schemas, there may come a time when a schema has b
 A write-incompatable schema can be loaded, but it can be neither imported into an iModel, nor can it be serialized to a file or string.
 
 Such a schema is likely to contain elements that are unknown to the current ECDb runtime being used.
-To know more about how these unknown elements are handled, refer to [Handling Unknown Schema Elements](./HandlingUnknownSchemaElements.md)
+To know more about how these unknown elements are handled, refer to [Handling Unknown And Wrong Schema Elements For Newer Versions](./HandlingUnknownAndWrongSchemaElementsForNewerVersions.md)
 
-To be able to perform read and write operations on a schema with a newer ECXml version, it us recommended to upgrade the ECDb runtime to a version that supports the ECXml version.
+To be able to perform read and write operations on a schema with a newer ECXml version, it us recommended to upgrade the ECDb runtime to a version that supports the ECXml version.