docs: composition validation (#399)

Co-authored-by: Jean du Plessis <jean@upbound.io>
Co-authored-by: Pete Lumbis <plumbis@users.noreply.github.com>

content/master/concepts/composition.md

@@ -1168,6 +1168,38 @@ not considered to be 'empty', and thus will pass the readiness check.
 
 `None`. Considers the composed resource to be ready as soon as it exists.
 
+### Composition validation
+
+Crossplane uses a `Validating Webhook` to inform users of any potential
+errors in a `Composition`. By default webhooks only perform
+`logical checks`. `logical checks` enforce requirements that
+aren't explicitly defined in the schema but Crossplane assumes to hold at runtime.
+
+#### Experimental validation with schemas
+
+Enable experimental schema-aware validation in Crossplane
+through the `--enable-composition-webhook-schema-validation` feature flag. This
+enables Composition validation against available schemas in the cluster.
+For example, ensuring that `fieldPaths` are valid and source and destination
+types match taking into account provided transforms too.
+
+The `crossplane.io/composition-validation-mode` annotation on the Composition
+allows setting one of two modes for schema validation:
+
+-  `loose` (default): Validates Compositions against required schemas. If a 
+    required schema is missing, schema validation stops, emits a warning and 
+    falls back to `logical checks` only.
+-  `strict`: Validates Compositions against required schemas, and rejects them
+    when finding errors. Rejects any Compositions missing required schemas.
+
+See the [Composition Validating Webhook design document][validation-design-doc]
+for more information about future development around schema-aware validation.
+
+#### Disabling webhooks
+
+Crossplane enables webhooks by default. Turn off webhooks by
+`webhooks.enabled` to `false` in the provided Helm Chart.
+
 ### Missing Functionality
 
 You might find while reading through this reference that Crossplane is missing
@@ -1178,7 +1210,7 @@ understand that the Crossplane maintainers are growing the feature set of the
 community, but we also feel it's critical to avoid bloat and complexity. We
 therefore wish to carefully consider each new addition. We feel some features
 may be better suited for a real, expressive programming language and intend to
-build an alternative to the `Composition` type as it is documented here per
+build an alternative to the `Composition` type as it's documented here per
 [this proposal][issue-2524].
 
 ## Tips, Tricks, and Troubleshooting
@@ -1303,3 +1335,4 @@ so:
 [claims-and-xrs]: /media/composition-claims-and-xrs.svg
 [xr-ref]: {{<ref "#compositions" >}}
 [managed-resources]: {{<ref "managed-resources" >}}
+[validation-design-doc]: https://github.com/crossplane/crossplane/blob/master/design/design-doc-composition-validating-webhook.md