Merge pull request #1692 from json-api/allow-relationship-paths-in-query-parameter-families

jelhan · web-flow · commit d990fe5bb96d · 2023-11-02T21:59:14.000+01:00
allow relationship paths in query parameter families
diff --git a/_format/1.1/index.md b/_format/1.1/index.md
@@ -2090,13 +2090,19 @@ family.
 
 A "query parameter family" is the set of all query parameters whose name starts
 with a "base name", followed by zero or more instances of empty square brackets
-(i.e. `[]`) or square-bracketed legal [member names]. The family is referred to
+(i.e. `[]`), square-bracketed legal [member names], or square-bracketed
+dot-separated lists of legal member names. The family is referred to
 by its base name.
 
 For example, the `filter` query parameter family includes parameters named:
 `filter`, `filter[x]`, `filter[]`, `filter[x][]`, `filter[][]`, `filter[x][y]`,
-etc. However, `filter[_]` is not a valid parameter name in the family, because
-`_` is not a valid [member name][member names].
+`filter[x.y]`, etc. However, `filter[_]` is not a valid parameter name in the
+family, because `_` is not a valid [member name][member names].
+
+> Note: Dot separated lists of legal member names are intended to be used for
+> relationship paths. For example, this allows filtering strategies using
+> relationship paths as defined for [sorting][fetching sorting] in query parameters
+> such as `GET /posts?sort=author.name&filter[author.status]=active`.
 
 ### <a href="#extension-query-parameters" id="extension-query-parameters" class="headerlink"></a> Extension-Specific Query Parameters
 
diff --git a/_format/1.2/index.md b/_format/1.2/index.md
@@ -2091,13 +2091,19 @@ family.
 
 A "query parameter family" is the set of all query parameters whose name starts
 with a "base name", followed by zero or more instances of empty square brackets
-(i.e. `[]`) or square-bracketed legal [member names]. The family is referred to
+(i.e. `[]`), square-bracketed legal [member names], or square-bracketed
+dot-separated lists of legal member names. The family is referred to
 by its base name.
 
 For example, the `filter` query parameter family includes parameters named:
 `filter`, `filter[x]`, `filter[]`, `filter[x][]`, `filter[][]`, `filter[x][y]`,
-etc. However, `filter[_]` is not a valid parameter name in the family, because
-`_` is not a valid [member name][member names].
+`filter[x.y]`, etc. However, `filter[_]` is not a valid parameter name in the
+family, because `_` is not a valid [member name][member names].
+
+> Note: Dot separated lists of legal member names are intended to be used for
+> relationship paths. For example, this allows filtering strategies using
+> relationship paths as defined for [sorting][fetching sorting] in query parameters
+> such as `GET /posts?sort=author.name&filter[author.status]=active`.
 
 ### <a href="#extension-query-parameters" id="extension-query-parameters" class="headerlink"></a> Extension-Specific Query Parameters
 
