Merge pull request #6240 from segmentio/array-operator-clarification

PROT-5203: Add section clarifying the .$ operator

Author: mschasz

src/connections/sources/schema/index.md

@@ -25,6 +25,10 @@ The Schema shows "Page Viewed" for all Page calls under the **Track** tab.
 
 The Source Schema UI changes slightly depending on whether you have a [Protocols Tracking Plan](https://segment.com/docs/protocols/tracking-plan/create/){:target='_blank’} connected to the source. If you have a Tracking Plan connected to your source, the UI displays a **Planned** column that will indicate if the event is planned or unplanned. This allows you to quickly identify unplanned events and take action to align your schema with your Tracking Plan. If there is no Tracking Plan connected to the source, the UI will display a toggle next to each event where, if you're a Business Tier customer, you can simply block or allow that event at the source level.  
 
+> info ""
+> Array properties are represented with an additional nested property representing the array's items. The nested property is the property's name with a `.$` suffix.
+> If an array property in the connected Tracking Plan does not include the `items` nested property, nested properties might be marked as unplanned in the Source Schema.
+
 ## Event filters
 
 If you no longer want to track a specific event, you can either remove it from your code or, if you're on the Business plan and don't have a Tracking Plan connected, you can block track calls from the Segment UI. To do so, click on the Schema tab in a Source and toggle the event to enable or block an event.

src/protocols/tracking-plan/create.md

@@ -128,6 +128,9 @@ Segment supports object and array data types in the Tracking Plan editor. These
 1. Create a new property row and set the Data Type to `Object` or `Array`.
 2. Click the **(+)** next to the property name to add key value pairs in the object, or objects to an array of objects.
 
+> info ""
+> When creating array properties in your Tracking Plan, add the `items` nested property, denoted by the name of the array property with a `.$` suffix, to ensure that the nested property is marked as planned in the Source Schema. 
+
 ### Add Identify or Group traits
 You can define which traits you expect to see passed in Identify or Group calls like how you would add Track calls to the Tracking Plan. Navigate to the **Identify** or **Group** tab in your Tracking Plan and click the **(+)** button to add a new trait.