Address comments

content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md

@@ -716,7 +716,7 @@ CustomResourceDefinition schemas using the `x-kubernetes-validations` extension.
 The Rule is scoped to the location of the `x-kubernetes-validations` extension in the schema.
 And `self` variable in the CEL expression is bound to the scoped value.
 
-Note all the validation rules specified there are scoped to the current object, and nothing cross-object or stateful would be enabled by this.
+Note all the validation rules are scoped to the current object, no cross-object or stateful validation rules are supported.
 
 For example:
 
@@ -996,18 +996,13 @@ Here is the declarations type mapping between OpenAPIv3 and CEL type:
 xref: [CEL types](https://github.com/google/cel-spec/blob/v0.6.0/doc/langdef.md#values), [OpenAPI
 types](https://swagger.io/specification/#data-types), [Kubernetes Structural Schemas](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema).
 
+#### Function Library
+
 Here is the function library available:
  - CEL standard functions, defined in the[list of standard definitions](https://github.com/google/cel-spec/blob/v0.7.0/doc/langdef.md#list-of-standard-definitions)
  - CEL standard [macros](https://github.com/google/cel-spec/blob/v0.7.0/doc/langdef.md#macros)
  - CEL [extended string function library](https://pkg.go.dev/github.com/google/cel-go@v0.11.2/ext#Strings)
  - Kubernetes [CEL extension library](https://pkg.go.dev/k8s.io/apiextensions-apiserver@v0.24.0-alpha.4/pkg/apiserver/schema/cel/library#pkg-functions)
- - `isSorted`
- - `sum`
- - `join`, `replace`, `split`, `lowerAscii`
- - `indexOf`/`lastIndexOf`
- - URL parsing: `url(string) URL`, `string(URL) string` (conversion), `getScheme(URL) string`, `getUserInfo(URL) string`, `getHost(URL) string`, `getPort(URL) string`, `getPath(URL) string`, `getQuery(URL) string`, `getFragment(URL) string`
- - regex `find(string) string`, `findAll(string) []string`
-
 
 #### Transition Rules
 
@@ -1027,6 +1022,9 @@ Errors will be generated on CRD writes if a schema node contains a transition ru
 applied, e.g. "*path*: update rule *rule* cannot be set on schema because the schema or its parent
 schema is not mergeable".
 
+Transition rules are only allowed on "correlatable" portions of a schema. 
+A portion of the schema is correlatable if all `array` parent schemas are of type `x-kubernetes-list-type=map`; any `set`or `atomic`array parent schemas make it impossible to unambiguously correlate a `self` with `oldSelf`.
+
 ##### Use Cases
 
 | Use Case | Rule
@@ -1048,7 +1046,7 @@ CEL expressions have the potential to consume unacceptable amounts of API server
 
 Guidelines for working with estimated limits:
 - Adding MaxItems, MaxProperties and MaxLength limits on all data accessed by CEL rules is the best practice.
-- O(n) - For simple rules, you can sometimes get away with iterating across a single map/list/string without a limit, but adding limits on all data accessed by CEL rules is the best practice
+- O(n) - For simple rules, it is possible to iterate across a single map/list/string without exceeding the limit, but adding limits on all data accessed by CEL rules is the best practice
 - O(n^2)+ the product of the max lengths usually needs to be <1,000,000. E.g. 1000 for 2 levels of nesting, 100 for 3 levels of nesting
 - O(n^3) - should generally be avoided