document "JSON Representation of Cadenza Object Data"

DisyInformationssysteme · Dec 27, 2023 · 80354cf · 80354cf
1 parent 9620d37
commit 80354cf
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 3 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+### Added
+- Documentation for the "JSON Representation of Cadenza Object Data"
 
 ## 2.2.1 - 2023-12-12
 ### Fixed

diff --git a/README.md b/README.md
@@ -322,3 +322,23 @@ By default, the sandbox expects Cadenza to run on http://localhost:8080/cadenza.
   export CADENZA_URL=http://localhost:8000/my-cadenza
   npm run sandbox
   ```
+
+## JSON Representation of Cadenza Object Data
+
+[JSON](https://www.json.org/) is a simple data-interchange format, which is also used in the Cadenza API. It does not support all the attribute types of Cadenza objects, that's why there are some rules for representing Cadenza object data in JSON.
+
+
+| Cadenza Attribute Type | JSON Type | JSON Example Value       | Notes |
+|------------------------|-----------|--------------------------|-------|
+| BigDecimal             | string    | `"1.23"`                 | The `BigDecimal` value range exceeds the range of the JSON `number` type. So it's represented as a string. |
+| Boolean                | boolean   | `true`                   | |
+| Date                   | string    | `"1999-12-31T23:00:00Z"` | A `Date` value is represented as an [ISO string in universal time](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC)). |
+| Double                 | number    | `1.23`                   |
+| Duration               | number    | `1`                      | A `Duration` is represented by its numeric value. |
+| Geometry               | object    | <pre lang="json">{<br>  "type": "Point"<br>  "coordinates": [125.6, 10.1]<br>}</pre> | A `Geometry` is represented as a [GeoJSON](https://geojson.org/) object.<br>_Note:_ By default, coordinates in GeoJSON use the WGS84 projection. |
+| Int                    | number    | `1`                      | |
+| Lob                    | string    |                          | |
+| Long                   | string    | `"1"`                    | The `Long` value range exceeds the range of the JSON `number` type. So it's represented as a string.
+| String                 | string    | `"Text"`                 | |
+| IpAddress              | string    | `"127.0.0.1"`            | |
+| Url                    | String    | `"http://example.com"`   | |
diff --git a/src/cadenza.js b/src/cadenza.js
@@ -82,7 +82,11 @@ globalThis.cadenza = Object.assign(
  */
 /** @typedef {[number,number,number,number]} Extent - An array of numbers representing an extent: [minx, miny, maxx, maxy] */
 
-/** @typedef {'csv' | 'excel' | 'json' | 'pdf'} DataType - A data type */
+/**
+ * @typedef {'csv' | 'excel' | 'json' | 'pdf'} DataType - A data type
+ *
+ * See [JSON Representation of Cadenza Object Data](../index.html#md:json-representation-of-cadenza-object-data) for JSON data.
+ */
 /** @typedef {'columns' | 'values' | 'totals'} TablePart - A part of a table to export */
 /** @typedef {Record<string, string | number | Date>} FilterVariables - Filter variable names and values */
 /**
@@ -194,9 +198,12 @@ export class CadenzaClient {
    * @return {Promise<void>} A Promise for when the iframe is loaded
    * @throws For invalid arguments
    * @fires `drillThrough` - When the user executed a POST message drill-through.
-   *   The event includes a row of values for each row in the workbook selection, each row consisting of the values of
+   *   <p>
+   *   The event includes a data row for every item in the workbook selection, each row consisting of the values of
    *   the attributes that were selected for the POST message content. If the drill-through was executed from a map
-   *   view, each row includes the geometry of the select object as the last value.
+   *   view, each row includes the geometry of the selected object as the last value.
+   *   <p>
+   *   See also: [JSON Representation of Cadenza Object Data](../index.html#md:json-representation-of-cadenza-object-data)
    */
   show(
     source,