Clarify guidance on operations having data-dependent output shapes

spec/API_specification/indexing.md

@@ -160,6 +160,12 @@ _Rationale: this is consistent with bounds-checking for single-axis indexing. An
 
 ## Boolean Array Indexing
 
+:::{admonition} Data-dependent output shape
+:class: important
+
+For common boolean array use cases (e.g., using a dynamically-sized boolean array mask to filter the values of another array), the shape of the output array is data-dependent; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find boolean array indexing difficult to implement. Accordingly, such libraries may choose to omit boolean array indexing. See {ref}`data-dependent-output-shapes` section for more details.
+:::
+
 An array must support indexing where the **sole index** is an `M`-dimensional boolean array `B` with shape `S1 = (s1, ..., sM)` according to the following rules. Let `A` be an `N`-dimensional array with shape `S2 = (s1, ..., sM, ..., sN)`.
 
 -   If `N >= M`, then `A[B]` must replace the first `M` dimensions of `A` with a single dimension having a size equal to the number of `True` elements in `B`. The values in the resulting array must be in row-major (C-style order); this is equivalent to `A[nonzero(B)]`.

spec/API_specification/searching_functions.md

@@ -69,6 +69,12 @@ Returns the indices of the minimum values along a specified axis. When the minim
 (function-nonzero)=
 ### nonzero(x, /)
 
+:::{admonition} Data-dependent output shape
+:class: important
+
+The shape of the output array for this function depends on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details.
+:::
+
 Returns the indices of the array elements which are non-zero.
 
 #### Parameters

spec/API_specification/set_functions.md

@@ -15,6 +15,12 @@ A conforming implementation of the array API standard must provide and support t
 (function-unique)=
 ### unique(x, /, *, return_counts=False, return_index=False, return_inverse=False)
 
+:::{admonition} Data-dependent output shape
+:class: important
+
+The shapes of one or more of output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details.
+:::
+
 Returns the unique elements of an input array `x`.
 
 #### Parameters

spec/design_topics/data_dependent_output_shapes.md

@@ -0,0 +1,15 @@
+(data-dependent-output-shapes)=
+
+# Data-dependent output shapes
+
+Array libraries which build computation graphs commonly employ static analysis that relies upon known shapes. For example, JAX requires known array sizes when compiling code, in order to perform static memory allocation. Functions and operations which are value-dependent present difficulties for such libraries, as array sizes cannot be inferred ahead of time without also knowing the contents of the respective arrays.
+
+While value-dependent functions and operations are not impossible to implement for array libraries which build computation graphs, this specification does not want to impose an undue burden on such libraries and permits omission of value-dependent operations. All other array libraries are expected, however, to implement the value-dependent operations included in this specification in order to be array specification compliant.
+
+Value-dependent operations are demarcated in this specification using an admonition similar to the following:
+
+:::{admonition} Data-dependent output shape
+:class: important
+
+The shape of the output array for this function/operation depends on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function/operation difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details.
+:::

spec/design_topics/index.rst

@@ -6,6 +6,7 @@ Design topics & constraints
    :maxdepth: 1
 
    copies_views_and_mutation
+   data_dependent_output_shapes
    data_interchange
    device_support
    static_typing