Add docs

Author: swallez

docs/behaviors.md

@@ -6,18 +6,25 @@ Behaviors should be used via `implements` in the specification.
 
 You can find all the special classes and aliases in in the [modeling guide](./modeling-guide.md).
 
-## AdditionalProperties
+## AdditionalProperties & AdditionalProperty
 
 In some places in the specification an object consists of the union of a set of known properties
-and a set of runtime injected properties. Meaning that object should theoretically extend Dictionary but expose
-a set of known keys and possibly. The object might already be part of an object graph and have a parent class.
-This puts it into a bind that needs a client specific solution.
+and a set of runtime injected properties. Meaning that object should theoretically extend `Dictionary` but expose
+a set of known keys. The object might also be part of an object graph and have a parent class.
+This puts it into a bin that needs a client specific solution.
 We therefore document the requirement to behave like a dictionary for unknown properties with this interface.
 
 ```ts
 class IpRangeBucket implements AdditionalProperties<AggregateName, Aggregate> {}
 ```
 
+There are also many places where we expect only one runtime-defined property, such as in field-related queries. To capture that uniqueness constraint, we can use the `AdditionalProperty` (singular) behavior.
+
+```ts
+class GeoBoundingBoxQuery extends QueryBase
+  implements AdditionalProperty<Field, BoundingBox>
+```
+
 ## CommonQueryParameters
 
 Implements a set of common query parameters all API's support.

docs/modeling-guide.md

@@ -317,6 +317,25 @@ class AggregationContainer {
   avg?: AverageAggregation
   ...
 ```
+
+### Shortcut properties
+
+In many places Elasticsearch accepts a property value to be either a complete data structure or a single value, that value being a shortcut for a property in the data structure.
+
+A typical example can be found in queries such as term query: `{"term": {"some_field": {"value": "some_text"}}}` can also be written as `{"term": {"some_field": "some_text"}}`.
+
+This could be modelled as a union of `SomeClass | string`, but this notation doesn't capture the relation between the string variant and the corresponding field (`value` in the above example).
+
+To capture this information and also simplify the spec by avoiding the union, we use the `@shortcut_property` JSDoc tag:
+
+```ts
+/** @shortcut_property value */
+export class TermQuery extends QueryBase {
+  value: string | float | boolean
+  case_insensitive?: boolean
+}
+```
+
 ### Additional information
 
 If needed, you can specify additional information on each type with the approariate JSDoc tag.