Document that Mendix Long values can exceed JavaScript's safe integer

content/en/docs/refguide/modeling/integration/odata-services/published-odata-services/odata-representation.md

@@ -39,6 +39,23 @@ In OData 4, IDs are annotated with vocabulary annotation `Com.Mendix.IsAttribute
 
 In OData 3, IDs are marked with `isAttribute="false"`, using a Mendix-specific XML attribute in the `http://www.mendix.com/Protocols/MendixData` namespace.
 
+### Large Long Values and JavaScript {#large-long-values}
+
+A Mendix Long can hold values up to 2^63 − 1. In JavaScript, the largest safe integer is `Number.MAX_SAFE_INTEGER`, which is 2^53 − 1 (9007199254740991). 
+
+When a client parses a larger integer as a JavaScript number, it can lose precision, so it no longer has the exact Long value. This can affect data in a browser. For example, consider the following OData response:
+
+```json
+{"@odata.context":"...snip...","value":[{"LongValue":12345678901234567}]}
+```
+
+Depending on the browser and how it parses and displays the response, the value of `LongValue` can appear as `12345678901234568`.
+
+This loss of precision is not caused by Mendix. However, you should take it into account when modeling published services. To avoid it, consider the following:
+
+* In the domain model, change the attribute type to String.
+* Do not expose the Mendix [ID](#id-representation). Large values frequently occur in IDs because of the way they are constructed.
+
 ## Associations {#associations}
 
 In the settings of the OData service, you can choose how associations are represented. There are two options, which are described below.

content/en/docs/refguide/modeling/integration/odata-services/published-odata-services/published-odata-entity.md

@@ -93,7 +93,7 @@ Selecting a key is required when the **Readable** capability is enabled.
 Selecting more than one attribute as the key is only available for published OData services that use OData v4.
 {{% /alert %}}
 
-Mendix recommends that you do not use the entity [ID](/refguide/odata-representation/#id-representation) as a key as it has no meaning outside the Mendix app. 
+Mendix recommends that you do not use the entity [ID](/refguide/odata-representation/#id-representation) as a key as it has no meaning outside the Mendix app. In addition, an ID can exceed JavaScript's largest safe integer (`Number.MAX_SAFE_INTEGER`), which can cause a loss of precision when parsed as a JavaScript number. For more information, see the [Large Long Values and JavaScript](/refguide/odata-representation/#large-long-values) section of *OData Representation*.
 
 ## Capabilities {#capabilities}
 

content/en/docs/refguide/modeling/integration/rest-services/published-rest-services/published-rest-service/published-rest-operation.md

@@ -121,6 +121,10 @@ The import mapping is also used to generate object schemas for operation respons
 
 This defines the response of the operation. You see the type of the microflow result and specify the export mapping applied to it (if any).
 
+{{% alert color="info" %}}
+A Mendix Long can exceed JavaScript's largest safe integer (`Number.MAX_SAFE_INTEGER`, which is 2^53 − 1). When a JavaScript client parses such a value as a JavaScript number in a JSON response, it can lose precision. For attributes that may exceed this limit and will be consumed by JavaScript clients, consider mapping the values to strings. For more information, see the [Large Long Values and JavaScript](/refguide/odata-representation/#large-long-values) section of *OData Representation*.
+{{% /alert %}}
+
 ##### Type
 
 This shows the result type of the microflow.

content/en/docs/refguide10/modeling/integration/odata-services/published-odata-services/odata-representation.md

@@ -39,6 +39,23 @@ In OData 4, IDs are annotated with vocabulary annotation `Com.Mendix.IsAttribute
 
 In OData 3, IDs are marked with `isAttribute="false"`, using a Mendix-specific XML attribute in the `http://www.mendix.com/Protocols/MendixData` namespace.
 
+### Large Long Values and JavaScript {#large-long-values}
+
+A Mendix Long can hold values up to 2^63 − 1. In JavaScript, the largest safe integer is `Number.MAX_SAFE_INTEGER`, which is 2^53 − 1 (9007199254740991). 
+
+When a client parses a larger integer as a JavaScript number, it can lose precision, so it no longer has the exact Long value. This can affect data in a browser. For example, consider the following OData response:
+
+```json
+{"@odata.context":"...snip...","value":[{"LongValue":12345678901234567}]}
+```
+
+Depending on the browser and how it parses and displays the response, the value of `LongValue` can appear as `12345678901234568`.
+
+This loss of precision is not caused by Mendix. However, you should take it into account when modeling published services. To avoid it, consider the following:
+
+* In the domain model, change the attribute type to String.
+* Do not expose the Mendix [ID](#id-representation). Large values frequently occur in IDs because of the way they are constructed.
+
 ## Associations {#associations}
 
 In the settings of the OData service, you can choose how associations are represented. There are two options, which are described below.

content/en/docs/refguide10/modeling/integration/odata-services/published-odata-services/published-odata-entity.md

@@ -97,7 +97,7 @@ Selecting a key is required when the **Readable** capability is enabled.
 Selecting more than one attribute as the key is only available for published OData services that use OData v4.
 {{% /alert %}}
 
-Mendix recommends that you do not use the entity [ID](/refguide10/odata-representation/#id-representation) as a key as it has no meaning outside the Mendix app. 
+Mendix recommends that you do not use the entity [ID](/refguide10/odata-representation/#id-representation) as a key as it has no meaning outside the Mendix app. In addition, an ID can exceed JavaScript's largest safe integer (`Number.MAX_SAFE_INTEGER`), which can cause a loss of precision when parsed as a JavaScript number. For more information, see the [Large Long Values and JavaScript](/refguide10/odata-representation/#large-long-values) section of *OData Representation*.
 
 ## Capabilities {#capabilities}
 

content/en/docs/refguide10/modeling/integration/rest-services/published-rest-services/published-rest-service/published-rest-operation.md

@@ -121,6 +121,10 @@ The import mapping is also used to generate object schemas for operation respons
 
 This defines the response of the operation. You can specify the type of the microflow result and the export mapping applied to it (if any).
 
+{{% alert color="info" %}}
+A Mendix Long can exceed JavaScript's largest safe integer (`Number.MAX_SAFE_INTEGER`, which is 2^53 − 1). When a JavaScript client parses such a value as a JavaScript number in a JSON response, it can lose precision. For attributes that may exceed this limit and will be consumed by JavaScript clients, consider mapping the values to strings. For more information, see the [Large Long Values and JavaScript](/refguide10/odata-representation/#large-long-values) section of *OData Representation*.
+{{% /alert %}}
+
 ##### Type
 
 This shows the result type of the microflow.

content/en/docs/refguide9/modeling/integration/odata-services/published-odata-services/odata-representation.md

@@ -38,6 +38,23 @@ In OData 4, IDs are annotated with vocabulary annotation `Com.Mendix.IsAttribute
 
 In OData 3, IDs are marked with `isAttribute="false"`, using a Mendix-specific XML attribute in the `http://www.mendix.com/Protocols/MendixData` namespace.
 
+### Large Long Values and JavaScript {#large-long-values}
+
+A Mendix Long can hold values up to 2^63 − 1. In JavaScript, the largest safe integer is `Number.MAX_SAFE_INTEGER`, which is 2^53 − 1 (9007199254740991). 
+
+When a client parses a larger integer as a JavaScript number, it can lose precision, so it no longer has the exact Long value. This can affect data in a browser. For example, consider the following OData response:
+
+```json
+{"@odata.context":"...snip...","value":[{"LongValue":12345678901234567}]}
+```
+
+Depending on the browser and how it parses and displays the response, the value of `LongValue` can appear as `12345678901234568`.
+
+This loss of precision is not caused by Mendix. However, you should take it into account when modeling published services. To avoid it, consider the following:
+
+* In the domain model, change the attribute type to String.
+* Do not expose the Mendix [ID](#id-representation). Large values frequently occur in IDs because of the way they are constructed.
+
 ## Associations {#associations}
 
 In the settings of the OData service, you can choose how associations are represented. There are two options, which are described below.

content/en/docs/refguide9/modeling/integration/odata-services/published-odata-services/published-odata-resource.md

@@ -106,7 +106,7 @@ Default: *10000*
 
 ## Key {#key}
 
-Every entity in Mendix has an [ID](/refguide9/odata-representation/#id-representation) that is used internally to store the object in the database. However, this ID is not stable over time, since it can change in certain scenarios (such as data migration). That means that a published OData resource should not use the ID as a key, and needs to have a combination of attributes that form a key instead. The attribute(s) can be of type **Integer**, **Long**, **String**, or **AutoNumber**.
+Every entity in Mendix has an [ID](/refguide9/odata-representation/#id-representation) that is used internally to store the object in the database. However, this ID is not stable over time, since it can change in certain scenarios (such as data migration). That means that a published OData resource should not use the ID as a key, and needs to have a combination of attributes that form a key instead. The attribute(s) can be of type **Integer**, **Long**, **String**, or **AutoNumber**. An ID can also exceed JavaScript's largest safe integer (`Number.MAX_SAFE_INTEGER`), which can cause a loss of precision when parsed as a JavaScript number. For more information, see the [Large Long Values and JavaScript](/refguide9/odata-representation/#large-long-values) section of *OData Representation*.
 
 Select a combination of attributes with the following constraints:
 

content/en/docs/refguide9/modeling/integration/rest-services/published-rest-services/published-rest-service/published-rest-operation.md

@@ -121,6 +121,10 @@ The import mapping is also used to generate object schemas for operation respons
 
 This defines the response of the operation. You can specify the type of the microflow result and the export mapping applied to it (if any).
 
+{{% alert color="info" %}}
+A Mendix Long can exceed JavaScript's largest safe integer (`Number.MAX_SAFE_INTEGER`, which is 2^53 − 1). When a JavaScript client parses such a value as a JavaScript number in a JSON response, it can lose precision. For attributes that may exceed this limit and will be consumed by JavaScript clients, consider mapping the values to strings. For more information, see the [Large Long Values and JavaScript](/refguide9/odata-representation/#large-long-values) section of *OData Representation*.
+{{% /alert %}}
+
 ##### Type
 
 This shows the result type of the microflow.