Clarify and fix the descriptions of parsedSections for JS API

Core/CMP API Specification.md

@@ -176,22 +176,113 @@ cmpDisplayStatus: String, // possible values: hidden, visible, disabled
 
 signalStatus : String, // possible values: not ready, ready
 
-supportedAPIs : Array of string, // list of supported APIs (section ids and prefix strings), e.g. used while loading. Example: ["2:tcfeuv2","6:uspv1"] 
+// List of supported APIs (section ids and prefix strings).
+// Example: ["2:tcfeuv2","6:uspv1"] 
+supportedAPIs : Array of string,
 
-cmpId : Number, // IAB assigned CMP ID, may be 0 during stub/loading. Reference the above CMP ID section for additional information.
+// IAB assigned CMP ID, may be 0 during stub/loading. Refer the above CMP ID section for additional information.
+cmpId : Number,
 
 sectionList : Array of Number, // may be empty during loading of the CMP
 
-applicableSections: Array of Number, // Section ID considered to be in force for this transaction. In most cases, this field should have a single section ID. In rare occasions where such a single section ID can not be determined, the field may contain up to 2 values. During the transition period which ends on September 30, 2023, the legacy USPrivacy section may be determined as applicable along with another US section. In this case, the field may contain up to 3 values where one of the values is 6, representing the legacy USPrivacy section. The value can be 0 or a Section ID specified by the Publisher / Advertiser, during stub / load. When no section is applicable, the value will be [-1].
+// Section ID considered to be in force for this transaction.
+// In most cases, this field should have a single section ID. In rare occasions where such a single section ID
+// can not be determined, the field may contain up to 2 values. During the transition period which ends on
+// September 30, 2023, the legacy USPrivacy section may be determined as applicable along with another US section.
+// In this case, the field may contain up to 3 values where one of the values is 6, representing the
+// legacy USPrivacy section. The value can be 0 or a Section ID specified by the Publisher / Advertiser, during
+// stub / load.
+// When no section is applicable, the value will be [-1].
+applicableSections: Array of Number,
 
 gppString: String // the complete encoded GPP string, may be empty during CMP load
 
-parsedSections: Object // The parsedSections property represents an object of all parsed sections of the gppString property that are supported by the API on this page (see supportedAPIs property). The object contains one property for each supported API with the name of the API as the property name and the value as a parsed representation of this section (similar to getSection command). If a section is supported but not represented in the gppString, it is omitted in the parsedSections object.
+// The parsedSections property represents an object of all parsed sections of the gppString property that are supported
+// by the API on this page (see supportedAPIs property). The object contains one property for each supported API with
+// the name of the API as the property name and the value as a parsed representation of this section with exactly the
+// same return as the getSection command, which may include subsections. If a section is supported but not represented
+// in the gppString, it is omitted in the parsedSections object.
+// Please refer to each section's spec for the exact field names and data types in JavaScript. The sections here should
+// be consistent with the GPP string, not placeholder values.
+parsedSections: Object
 
 }
 
 ```
 
+In JavaScript, a `parsedSections` object should be a native JS object that maps from the section's API prefix names
+enumerated [here](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/Section%20Information.md#section-ids)
+to the section's JS representation according to its spec. Each section's is represented as an array of objects, and each
+object corresponds to a sub-section (segment) in that section. Follow this [table of data type mapping](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding)
+to map each spec's GPP field types to JavaScript native data
+types. Examples:
+```javascript
+/* Example of a `parsedSections` that holds two sections: tcfcav1, tcfeuv2 */
+{
+  /* See "GPPExtension: IAB Canada TCF.md". */
+  tcfcav1: [
+    /* Core Sub-section */
+    {
+      Version: 1,
+      Created: new Date ("Thu Apr 13 2023 18:07:12 GMT+0200"),
+      LastUpdated: new Date ("Thu Apr 13 2023 18:07:12 GMT+0200"),
+      CmpId: 31, 
+      CmpVersion: 123,
+      ConsentScreen: 5,
+      ...
+    }, 
+    /* Publisher Purposes Sub-section */
+    {
+      SubsectionType: 3, 
+      PubPurposesExpressConsent: [1,2,3,4,5],
+      PubPurposesImpliedConsent: [6,7,8,9],
+      ...
+    } 
+  ],
+
+  /* See "GPPExtension: IAB Europe TCF.md". */
+  tcfeuv2: [
+    /* Core Segment */
+    {
+      Version: 2, 
+      Created: new Date ("Thu Nov 10 2024 12:08:22 GMT+0200"),
+      LastUpdated: new Date ("Thu Nov 10 2024 12:08:2 GMT+0200"),
+      CmpId: 10, 
+      CmpVersion: 56,
+      ConsentScreen: 0,
+      VendorConsent: [1,2,4,6],
+      ...
+    }, 
+    /* Disclosed Vendors Segment */
+    {
+      SegmentType: 1, 
+      ...
+    }
+    /* This example doesn't contain the optional Publisher Purposes Segment */
+  ]
+}
+```
+```javascript
+/* Example of a `parsedSections` that holds one section: usnat */
+{
+  /* See "IAB Privacy's Multi-State Privacy Agreement (MSPA) US National Technical Specification.md". */
+  usnat: [
+    /* Core Segment */
+    {
+      Version: 1,
+      SharingNotice: 1,
+      KnownChildSensitiveDataConsents: [0, 0],
+      MspaCoveredTransaction: 2,
+      ...
+    },
+    /* GPC Sub-section */
+    {
+      SubsectionType: 1,
+      Gpc: true
+    }
+  ]
+}
+```
 
 **Ping Status Codes**
 
@@ -617,27 +708,27 @@ For example, client can ask the CMP to get the IAB TCF CA v1.0 TCData:
 __gpp('getSection', myFunction, "tcfcav1"); 
 ```
 
-Example value of data passed to the callback: 
+Example value of data passed to the callback, according to [GPPExtension: IAB Canada TCF.md](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/Canada/GPPExtension%3A%20IAB%20Canada%20TCF.md): 
 ```javascript
 [
- /* Core Sub-section */
- {
-  Version:1, 
-  Created: Date (Thu Apr 13 2023 18:07:12 GMT+0200),
-  LastUpdated: Date (Thu Apr 13 2023 18:07:12 GMT+0200),
-  CmpId: 31, 
-  CmpVersion: 123,
-  ConsentScreen: 5,
-  ...
+  /* Core Sub-section */
+  {
+    Version: 1,
+    Created: new Date ("Thu Apr 13 2023 18:07:12 GMT+0200"),
+    LastUpdated: new Date ("Thu Apr 13 2023 18:07:12 GMT+0200"),
+    CmpId: 31, 
+    CmpVersion: 123,
+    ConsentScreen: 5,
+    ...
   }, 
   /* Publisher Purposes Sub-section (optional) */
- {
-  subsectionType:3, 
-  PubPurposesExpressConsent : [1,2,3,4,5],
-  PubPurposesImpliedConsent  : [6,7,8,9],
-  ...
+  {
+    SubsectionType: 3, 
+    PubPurposesExpressConsent: [1,2,3,4,5],
+    PubPurposesImpliedConsent: [6,7,8,9],
+    ...
   } 
- ]
+]
 ```
 
 ______

Sections/Canada/GPPExtension: IAB Canada TCF.md

@@ -25,6 +25,7 @@
 </div>
 <h2>Section encoding</h2>
 <p>The IAB TCF Canada will be using the following encoding for the GPP section. If already familiar with the IAB TCF Europe encoding, you may view the detailed differences between the two on the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/tree/main/Sections/Canada/TCF%20EU%20TCF%20CA%20Comparison.md" target="_blank" rel="noopener">IAB Europe TCF with IAB Canada TCF Signal Definition</a> documentation.</p>
+<p>Note on the JS representation of the section: the field name should be in UpperCamelCase, with exactly the same spelling as the names in column "Field name". Follow <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding" target="_blank" rel="noopener">this table</a> to map the GPP field types to JavaScript native data types. Please refer to the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md#pingreturn-" target="_blank" rel="noopener">PingReturn's parsedSections object</a> for an example.<p>
 <h3>Core sub-section</h3>
 <p>The core sub-section must always be present. It consists of the following fields:</p>
 <div>

Sections/EEA/GPPExtension: IAB Europe TCF.md

@@ -31,6 +31,7 @@ The global standard [GPP](https://github.com/InteractiveAdvertisingBureau/Global
 The GPP section for the IAB Europe TCF (Section ID 2) will use the following encoding.
 Note that the resulting TC String produced is expected to be exactly the same as the TC String produced when using the [TCF specification](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20Consent%20string%20and%20vendor%20list%20formats%20v2.md). The GPP introduces new data types that are For full details about the TC String, please refer to the [Consent string and vendor list format v2](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20Consent%20string%20and%20vendor%20list%20formats%20v2.md).
 
+Note on the JS representation of the section: the field name should be in UpperCamelCase, with exactly the same spelling as the names in column "Field name". Follow [this table](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding) to map the GPP field types to JavaScript native data types. Please refer to the [PingReturn's parsedSections object](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md#pingreturn-) for an example.
 
 ### Core segment
 
@@ -177,7 +178,7 @@ The core segment must always be present. It consists of the following fields:
 > **Note:** Fields marked with * are only included in the string encoded version of the GPP segment but will not be returned by the client side API. Instead, the client side API will return an array of int with the corresponding IDs.
 
 
-## Disclosed Vendors Segment
+### Disclosed Vendors Segment
 
 The disclosed vendors segment is appended to the core segment by using the “.” (dot) delimiter. This is an optional TC String segment. It may be used by a CMP while storing TC Strings, but must not be included in the TC String when returned by the CMP API. The segment fields are:
 
@@ -201,7 +202,7 @@ The disclosed vendors segment is appended to the core segment by using the “.
 
 
 
-## Publisher Purposes Segment
+### Publisher Purposes Segment
 
 The publisher purposes segment is appended to the core segment by using the “.” (dot) delimiter. The segment is optional. The segment fields are:
 

Sections/US-National/IAB Privacy’s Multi-State Privacy Agreement (MSPA) US National Technical Specification.md

@@ -57,6 +57,8 @@ Implementers should employ the MSPA US National Privacy Section to adhere to the
 </div>
 
 <h3>Section encoding</h3>
+<p>Note on the JS representation of the section: the field name should be in UpperCamelCase, with exactly the same spelling as the names in column "Field name". Follow <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding" target="_blank" rel="noopener">this table</a> to map the GPP field types to JavaScript native data types. Please refer to the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md#pingreturn-" target="_blank" rel="noopener">PingReturn's parsedSections object</a> for an example.<p>
+
 <h4>Core Segment</h4>
 <p>The core segment must always be present. Where terms are capitalized in the &lsquo;description&rsquo; field they are defined terms in applicable State Privacy Laws and the MSPA. It consists of the following fields:</p>
 

Sections/US-States/CA/GPP Extension: California Privacy Technical Specification.md

@@ -49,6 +49,7 @@
 </tbody>
 </table>
 <h3 id="section-encoding">Section encoding</h3>
+<p>Note on the JS representation of the section: the field name should be in UpperCamelCase, with exactly the same spelling as the names in column "Field name". Follow <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding" target="_blank" rel="noopener">this table</a> to map the GPP field types to JavaScript native data types. Please refer to the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md#pingreturn-" target="_blank" rel="noopener">PingReturn's parsedSections object</a> for an example.<p>
 <h4 id="core-section">Core Sub-section</h4>
 <p>The core sub-section must always be present. Where terms are capitalized in the ‘description’ field they are defined terms in Cal. Civ. Code 1798.140. It consists of the following fields:
 </p>

Sections/US-States/CO/GPP Extension: Colorado Privacy Technical Specification.md

@@ -46,6 +46,7 @@
 </tbody>
 </table>
 <h3 id="section-encoding">Section encoding</h3>
+<p>Note on the JS representation of the section: the field name should be in UpperCamelCase, with exactly the same spelling as the names in column "Field name". Follow <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding" target="_blank" rel="noopener">this table</a> to map the GPP field types to JavaScript native data types. Please refer to the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md#pingreturn-" target="_blank" rel="noopener">PingReturn's parsedSections object</a> for an example.<p>
 <h4 id="core-segment">Core Segment</h4>
 <p>The core segment must always be present. Where terms are capitalized in the ‘description’ field they are defined terms in Colo. Rev. Stat. 6-1-1303. It consists of the following fields:</p>
 <table>

Sections/US-States/CT/GPP Extension: Connecticut Privacy Technical Specification.md

@@ -46,6 +46,7 @@
 </tbody>
 </table>
 <h3 id="section-encoding">Section encoding</h3>
+<p>Note on the JS representation of the section: the field name should be in UpperCamelCase, with exactly the same spelling as the names in column "Field name". Follow <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding" target="_blank" rel="noopener">this table</a> to map the GPP field types to JavaScript native data types. Please refer to the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md#pingreturn-" target="_blank" rel="noopener">PingReturn's parsedSections object</a> for an example.<p>
 <h4 id="core-segment">Core Segment</h4>
 <p>The core segment must always be present. Where terms are capitalized in the ‘description’ field they are defined terms in Conn. PA No. 22-15, Sec. 1 [Pending codification]. It consists of the following fields:</p>
 <table>

Sections/US-States/DE/GPP Extension: IAB Privacy’s Delaware Privacy Technical Specification.md

@@ -52,6 +52,7 @@
   </table>
 </div>
 <h3>Section encoding</h3>
+<p>Note on the JS representation of the section: the field name should be in UpperCamelCase, with exactly the same spelling as the names in column "Field name". Follow <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding" target="_blank" rel="noopener">this table</a> to map the GPP field types to JavaScript native data types. Please refer to the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md#pingreturn-" target="_blank" rel="noopener">PingReturn's parsedSections object</a> for an example.<p>
 <h4>Core Segment</h4>
 <p>The core sub-section must always be present. Where terms are capitalized in the ‘description’ field they are defined in Del. Code Ann. tit. 6, § 12D-102. It consists of the following fields:</p>
 <div>

Sections/US-States/FL/GPP Extension: IAB Privacy’s Florida Privacy Technical Specification.md

@@ -52,6 +52,7 @@
   </table>
 </div>
 <h3>Section encoding</h3>
+<p>Note on the JS representation of the section: the field name should be in UpperCamelCase, with exactly the same spelling as the names in column "Field name". Follow <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding" target="_blank" rel="noopener">this table</a> to map the GPP field types to JavaScript native data types. Please refer to the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md#pingreturn-" target="_blank" rel="noopener">PingReturn's parsedSections object</a> for an example.<p>
 <h4>Core Segment</h4>
 <p>The core sub-section must always be present. Where terms are capitalized in the ‘description’ field they are defined terms in Fla. Stat. § 501.702. It consists of the following fields:</p>
 <div>

Sections/US-States/IA/GPP Extension: IAB Privacy’s Iowa Privacy Technical Specification.md

@@ -52,6 +52,7 @@
   </table>
 </div>
 <h3>Section encoding</h3>
+<p>Note on the JS representation of the section: the field name should be in UpperCamelCase, with exactly the same spelling as the names in column "Field name". Follow <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding" target="_blank" rel="noopener">this table</a> to map the GPP field types to JavaScript native data types. Please refer to the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md#pingreturn-" target="_blank" rel="noopener">PingReturn's parsedSections object</a> for an example.<p>
 <h4>Core Segment</h4>
 <p>The core sub-section must always be present. Where terms are capitalized in the ‘description’ field they are defined in the Iowa Act Relating to Consumer Data Protection, Iowa Code § 715D.1. It consists of the following fields:</p>
 <div>

Sections/US-States/MT/GPP Extension: IAB Privacy’s Montana Privacy Technical Specification.md

@@ -52,6 +52,7 @@
   </table>
 </div>
 <h3>Section encoding</h3>
+<p>Note on the JS representation of the section: the field name should be in UpperCamelCase, with exactly the same spelling as the names in column "Field name". Follow <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding" target="_blank" rel="noopener">this table</a> to map the GPP field types to JavaScript native data types. Please refer to the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md#pingreturn-" target="_blank" rel="noopener">PingReturn's parsedSections object</a> for an example.<p>
 <h4>Core Segment</h4>
 <p>The core sub-section must always be present. Where terms are capitalized in the ‘description’ field they are defined terms in Montana Act, Sec. 2 [Pending Codification]. It consists of the following fields:</p>
 <div>

Sections/US-States/NE/GPP Extension: IAB Privacy’s Nebraska Privacy Technical Specification.md

@@ -52,6 +52,7 @@
   </table>
 </div>
 <h3>Section encoding</h3>
+<p>Note on the JS representation of the section: the field name should be in UpperCamelCase, with exactly the same spelling as the names in column "Field name". Follow <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/Consent%20String%20Specification.md#section-encoding" target="_blank" rel="noopener">this table</a> to map the GPP field types to JavaScript native data types. Please refer to the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md#pingreturn-" target="_blank" rel="noopener">PingReturn's parsedSections object</a> for an example.<p>
 <h4>Core Segment</h4>
 <p>The core sub-section must always be present. Where terms are capitalized in the ‘description’ field they are defined in the Nebraska Act, Sec. 2 [Pending Codification]. It consists of the following fields:</p>
 <div>