From 1321004cf3308450d3e12352d076b35fb089eca3 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 21 Jun 2023 17:42:01 +0200 Subject: [PATCH 01/10] Small corrections specification after merging meta data and partial data. --- optimade.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/optimade.rst b/optimade.rst index ccfded5de..680c8b41f 100644 --- a/optimade.rst +++ b/optimade.rst @@ -455,7 +455,7 @@ How this list is provided is response format-dependent. For the JSON response format, see the description of the :field:`partial_data_links` field, nested under :field:`data` and then :field:`meta`, in the section `JSON Response Schema: Common Fields`_. The default partial data format is named "jsonlines" and is described in the Appendix `OPTIMADE JSON lines partial data format`_. -An implementation SHOULD always include this format as one of alternative partial data formats provided for a property that has been omitted from the response to the initial query. +An implementation SHOULD always include this format as one of the partial data formats provided for a property that has been omitted from the response to the initial query. Implementations MAY provide links to their own non-standard formats, but non-standard format names MUST be prefixed by a database-provider-specific prefix. Below follows an example of the :field:`data` and :field:`meta` parts of a response using the JSON response format that communicates that the property value has been omitted from the response, with three different links for different partial data formats provided. @@ -505,7 +505,7 @@ For example, the metadata property definition of the field :field:`_exmpl_exampl The reason for this limitation is to avoid name collisions with metadata fields defined by the OPTIMADE standard in the future that apply also to database-specific data fields. Implementation of the :field:`meta` field is OPTIONAL. -However, when an implementation supports the :field:`property_metadata` field, it SHOULD include metadata fields for all fields present in the data part of the response which has metadata. +However, when an implementation supports the :field:`property_metadata` field, it SHOULD include metadata fields for all fields, present in the data part of the response, which have metadata. Example of a response in the JSON response format with two structure entries that each include a metadata property for the attribute field :field:`element_ratios` and the database-specific per entry metadata field :field:`_exmpl_originates_from_project` : @@ -726,11 +726,11 @@ Every response SHOULD contain the following fields, and MUST contain at least :f - **partial_data_links**: an object used to list links which can be used to fetch data that has been omitted from the :field:`data` part of the response. The keys are the names of the fields in :field:`attributes` for which partial data links are available. - Each value is a list of items that MUST have the following keys: + Each value is a list of objects that MUST have the following keys: - **format**: String. - A name of the format provided via this link. - One of the items SHOULD be "jsonlines", which refers to the format in `OPTIMADE JSON lines partial data format`_. + The name of the format provided via this link. + For one of the objects this :field:`format` field SHOULD have the value "jsonlines", which refers to the format in `OPTIMADE JSON lines partial data format`_. - **link**: String. A `JSON API link `__ that points to a location from which the omitted data can be fetched. @@ -3605,7 +3605,7 @@ The markers have been deliberately designed to be valid JSON objects but *not* v Since the OPTIMADE list data type is defined as a list of values of the same data type or :val:`null`, the above markers cannot be encountered inside the actual data of an OPTIMADE property. **Implementation note:** the recognizable string values for the markers should make it possible to prescreen the raw text of the JSON data lines for the reference-marker string to determine which are the lines that one can exclude from further processing to resolve references (alternatively, this screening can be done by the string parser used by the JSON parser). - The undelying design idea is that for lines that have reference-markers, the time it takes to process the data structure to locate the markers should be negligible compared to the time it takes to resolve and handle the large data they reference. + The underlying design idea is that for lines that have reference-markers, the time it takes to process the data structure to locate the markers should be negligible compared to the time it takes to resolve and handle the large data they reference. Hence, the most relevant optimization is to avoid spending time processing data structures to find markers for lines where there are none. The full response MUST be valid `JSON Lines `__ that adheres to the following format: @@ -3631,8 +3631,8 @@ The header object MUST contain the keys: The following key is RECOMMENDED in the header object: -- :field:`"returned_ranges"`: Array of Object. - For dense layout, and sparse layout of one dimensional list properties, the array contains a single element which is a `slice object`_ representing the range of data present in the response. +- :field:`"returned_ranges"`: Array of Objects. + For one dimensional list properties, the array contains a single element which is a `slice object`_ representing the range of data present in the response. In the specific case of a hierarchy of list properties represented as a sparse multi-dimensional array, if the field :field:`"returned_ranges"` is given, it MUST contain one slice object per dimension of the multi-dimensional array, representing slices for each dimension that cover the data given in the response. The header object MAY also contain the keys: @@ -3670,7 +3670,7 @@ The header object MAY also contain the keys: The format and requirements on this schema are the same as for the inline schema field :field:`item_schema`. The format of data lines of the response (i.e., all lines except the first and the last) depends on whether the header object specifies the layout as :val:`"dense"` or :val:`"sparse"`. -- **Dense layout:** In the dense partial data layout, each data line reproduces one list item in the OPTIMADE list property being transmitted in JSON format. +- **Dense layout:** In the dense partial data layout, each data line reproduces one item from the OPTIMADE list property being transmitted in the JSON format. If OPTIMADE list properties are embedded inside the item, they can either be included in full or replaced with a reference-marker. If a list is replaced by a reference marker, the client MAY use the provided URL to obtain the list items. If the field :field:`"returned_ranges"` is omitted, then the client MUST assume that the data is a continuous range of data from the start of the array up to the number of elements given until reaching the end-of-data-marker or next-marker. From bb86541ef4404de5fa39827d744d7b496d561cce Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 26 Jun 2023 10:47:04 +0200 Subject: [PATCH 02/10] removed change description returned_ranges. --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 5c6d717e9..c586b7074 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3694,7 +3694,7 @@ The header object MUST contain the keys: The following key is RECOMMENDED in the header object: - :field:`"returned_ranges"`: Array of Objects. - For one dimensional list properties, the array contains a single element which is a `slice object`_ representing the range of data present in the response. + For dense layout, and sparse layout of one dimensional list properties, the array contains a single element which is a `slice object`_ representing the range of data present in the response. In the specific case of a hierarchy of list properties represented as a sparse multi-dimensional array, if the field :field:`"returned_ranges"` is given, it MUST contain one slice object per dimension of the multi-dimensional array, representing slices for each dimension that cover the data given in the response. The header object MAY also contain the keys: From 0c5f9cbd117eba59b542797fa175fe3bbba74f30 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 26 Jun 2023 14:44:49 +0200 Subject: [PATCH 03/10] Apply suggestions from code review Renaming some of the field types to their OPTIMADE name rather than JSON name. Co-authored-by: Andrius Merkys --- optimade.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/optimade.rst b/optimade.rst index c586b7074..910916ad1 100644 --- a/optimade.rst +++ b/optimade.rst @@ -749,9 +749,9 @@ Every response SHOULD contain the following fields, and MUST contain at least :f The values belonging to these keys are dictionaries containing the relevant metadata fields. See also `Metadata properties`_ - - **partial_data_links**: an object used to list links which can be used to fetch data that has been omitted from the :field:`data` part of the response. + - **partial_data_links**: a dictionary used to list links which can be used to fetch data that has been omitted from the :field:`data` part of the response. The keys are the names of the fields in :field:`attributes` for which partial data links are available. - Each value is a list of objects that MUST have the following keys: + Each value is a list of dictionaries that MUST have the following keys: - **format**: String. The name of the format provided via this link. @@ -3693,7 +3693,7 @@ The header object MUST contain the keys: The following key is RECOMMENDED in the header object: -- :field:`"returned_ranges"`: Array of Objects. +- :field:`"returned_ranges"`: List of Dictionaries. For dense layout, and sparse layout of one dimensional list properties, the array contains a single element which is a `slice object`_ representing the range of data present in the response. In the specific case of a hierarchy of list properties represented as a sparse multi-dimensional array, if the field :field:`"returned_ranges"` is given, it MUST contain one slice object per dimension of the multi-dimensional array, representing slices for each dimension that cover the data given in the response. From e606d0273acc35d2154da61723bca7399e4b2bd3 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 26 Jun 2023 14:48:40 +0200 Subject: [PATCH 04/10] Update optimade.rst --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 910916ad1..79e814471 100644 --- a/optimade.rst +++ b/optimade.rst @@ -506,7 +506,7 @@ For example, the metadata property definition of the field :field:`_exmpl_exampl The reason for this limitation is to avoid name collisions with metadata fields defined by the OPTIMADE standard in the future that apply also to database-specific data fields. Implementation of the :field:`meta` field is OPTIONAL. -However, when an implementation supports the :field:`property_metadata` field, it SHOULD include metadata fields for all fields, present in the data part of the response, which have metadata. +However, when an implementation supports the :field:`property_metadata` field, it SHOULD include metadata fields for all properties which have metadata and are present in the data part of the response. Example of a response in the JSON response format with two structure entries that each include a metadata property for the attribute field :field:`element_ratios` and the database-specific per entry metadata field :field:`_exmpl_originates_from_project` : From d8d77ef45566c94d17aaa17278286425b41d7f88 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 26 Jun 2023 15:04:20 +0200 Subject: [PATCH 05/10] Revert "Apply suggestions from code review " This reverts commit 0c5f9cbd117eba59b542797fa175fe3bbba74f30. --- optimade.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/optimade.rst b/optimade.rst index 79e814471..9f4abe372 100644 --- a/optimade.rst +++ b/optimade.rst @@ -749,9 +749,9 @@ Every response SHOULD contain the following fields, and MUST contain at least :f The values belonging to these keys are dictionaries containing the relevant metadata fields. See also `Metadata properties`_ - - **partial_data_links**: a dictionary used to list links which can be used to fetch data that has been omitted from the :field:`data` part of the response. + - **partial_data_links**: an object used to list links which can be used to fetch data that has been omitted from the :field:`data` part of the response. The keys are the names of the fields in :field:`attributes` for which partial data links are available. - Each value is a list of dictionaries that MUST have the following keys: + Each value is a list of objects that MUST have the following keys: - **format**: String. The name of the format provided via this link. @@ -3693,7 +3693,7 @@ The header object MUST contain the keys: The following key is RECOMMENDED in the header object: -- :field:`"returned_ranges"`: List of Dictionaries. +- :field:`"returned_ranges"`: Array of Objects. For dense layout, and sparse layout of one dimensional list properties, the array contains a single element which is a `slice object`_ representing the range of data present in the response. In the specific case of a hierarchy of list properties represented as a sparse multi-dimensional array, if the field :field:`"returned_ranges"` is given, it MUST contain one slice object per dimension of the multi-dimensional array, representing slices for each dimension that cover the data given in the response. From 40dd02bfe454ed4bc051924c7338f724421aa3a4 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 28 Jun 2023 16:08:49 +0200 Subject: [PATCH 06/10] changed name property indicating the version of the partial return to . --- optimade.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/optimade.rst b/optimade.rst index 9f4abe372..9cdd05b6b 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3684,9 +3684,9 @@ The header object MUST contain the keys: It MUST contain the following key: - - :field:`"format"`: String. + - :field:`"version"`: String. Specifies the minor version of the partial data format used. The string MUST be of the format "MAJOR.MINOR", referring to the version of the OPTIMADE standard that describes the format. The version number string MUST NOT be prefixed by, e.g., "v". In implementations of the present version of the standard, the value MUST be exactly :val:`1.2`. - A client MUST NOT expect to be able to parse the format if the field is not a string of the format MAJOR.MINOR or if the MAJOR version number is unrecognized. + A client MUST NOT expect to be able to parse the :field:`version` value if the field is not a string of the format MAJOR.MINOR or if the MAJOR version number is unrecognized. - :field:`"layout"`: String. A string either equal to :val:`"dense"` or :val:`"sparse"` to indicate whether the returned format uses a dense or sparse layout. @@ -3737,7 +3737,7 @@ The format of data lines of the response (i.e., all lines except the first and t If a list is replaced by a reference marker, the client MAY use the provided URL to obtain the list items. If the field :field:`"returned_ranges"` is omitted, then the client MUST assume that the data is a continuous range of data from the start of the array up to the number of elements given until reaching the end-of-data-marker or next-marker. -- **Sparse layout for one-dimensional list:** When the response sparsely communicates items for a one-dimensional OPTIMADE list property, each data line contains a JSON array on the format: +- **Sparse layout for one-dimensional list:** When the response sparsely communicates items for a one-dimensional OPTIMADE list property, each data line contains a JSON array of the format: - The first item of the array is the zero-based index of list property item being provided by this line. - The second item of the array is the list property item located at the indicated index, represented using the same format as each line in the dense layout. @@ -3766,7 +3766,7 @@ The request returns the first three items and provides the next-marker link to c .. code:: json - {"optimade-partial-data": {"format": "1.2.0"}, "layout": "dense", "returned_ranges": [{"start": 10, "stop": 20, "step": 2}]} + {"optimade-partial-data": {"version": "1.2.0"}, "layout": "dense", "returned_ranges": [{"start": 10, "stop": 20, "step": 2}]} 123 345 -12.6 @@ -3779,7 +3779,7 @@ The third provided item (index 14 in the original list) is only partially return .. code:: json - {"optimade-partial-data": {"format": "1.2.0"}, "layout": "dense", "returned_ranges": [{"start": 10, "stop": 20, "step": 2}]} + {"optimade-partial-data": {"version": "1.2.0"}, "layout": "dense", "returned_ranges": [{"start": 10, "stop": 20, "step": 2}]} [[10,20,21], [30,40,50]] ["PARTIAL-DATA-REF", ["https://example.db.org/value2"]] [[11, 110], ["PARTIAL-DATA-REF", ["https://example.db.org/value3"]], [550, 333]] @@ -3792,7 +3792,7 @@ The response below communicates the first item explicitly; the second one by def .. code:: json - {"optimade-partial-data": {"format": "1.2.0"}, "layout": "sparse"} + {"optimade-partial-data": {"version": "1.2.0"}, "layout": "sparse"} [3,5,19, [10,20,21,30]] [30,15,9, ["PARTIAL-DATA-REF", ["https://example.db.org/value1"]]] ["PARTIAL-DATA-NEXT", ["https://example.db.org/"]] @@ -3801,7 +3801,7 @@ An example of the sparse layout for multi-dimensional lists with three aggregate .. code:: json - {"optimade-partial-data": {"format": "1.2.0"}, "layout": "sparse"} + {"optimade-partial-data": {"version": "1.2.0"}, "layout": "sparse"} [3,5,19, 10] [30,15,9, 31] ["PARTIAL-DATA-NEXT", ["https://example.db.org/"]] @@ -3810,7 +3810,7 @@ An example of the sparse layout for multi-dimensional lists with three aggregate .. code:: json - {"optimade-partial-data": {"format": "1.2.0"}, "layout": "sparse"} + {"optimade-partial-data": {"version": "1.2.0"}, "layout": "sparse"} [3,5,19, [ [10,20,21], [30,40,50] ] ] [3,7,19, ["PARTIAL-DATA-REF", ["https://example.db.org/value2"]]] [4,5,19, [ [11, 110], ["PARTIAL-DATA-REF", ["https://example.db.org/value3"]], [550, 333]]] From 99ea26794cfa4bca8c977010c0c2f80fb12b33b7 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 7 Aug 2023 12:24:20 +0200 Subject: [PATCH 07/10] Apply suggestions from code review suggestions Vaitkus Co-authored-by: Antanas Vaitkus --- optimade.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 9cdd05b6b..131b14e3f 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3685,7 +3685,9 @@ The header object MUST contain the keys: It MUST contain the following key: - :field:`"version"`: String. - Specifies the minor version of the partial data format used. The string MUST be of the format "MAJOR.MINOR", referring to the version of the OPTIMADE standard that describes the format. The version number string MUST NOT be prefixed by, e.g., "v". In implementations of the present version of the standard, the value MUST be exactly :val:`1.2`. + Specifies the minor version of the partial data format used. + The string MUST be of the format "MAJOR.MINOR", referring to the version of the OPTIMADE standard that describes the format. + The version number string MUST NOT be prefixed by, e.g., "v". In implementations of the present version of the standard, the value MUST be exactly :val:`1.2`. A client MUST NOT expect to be able to parse the :field:`version` value if the field is not a string of the format MAJOR.MINOR or if the MAJOR version number is unrecognized. - :field:`"layout"`: String. @@ -3695,7 +3697,7 @@ The following key is RECOMMENDED in the header object: - :field:`"returned_ranges"`: Array of Objects. For dense layout, and sparse layout of one dimensional list properties, the array contains a single element which is a `slice object`_ representing the range of data present in the response. - In the specific case of a hierarchy of list properties represented as a sparse multi-dimensional array, if the field :field:`"returned_ranges"` is given, it MUST contain one slice object per dimension of the multi-dimensional array, representing slices for each dimension that cover the data given in the response. + In the specific case of a hierarchy of list properties represented as a sparse multidimensional array, if the field :field:`"returned_ranges"` is given, it MUST contain one slice object per dimension of the multi-dimensional array, representing slices for each dimension that cover the data given in the response. The header object MAY also contain the keys: From 4ffa986a477a606d42f36dbffe7ac3c56916b338 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 7 Aug 2023 12:27:19 +0200 Subject: [PATCH 08/10] Changed multi-dimensional to multidimensional. --- optimade.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/optimade.rst b/optimade.rst index 9cdd05b6b..1d0003dd7 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3695,7 +3695,7 @@ The following key is RECOMMENDED in the header object: - :field:`"returned_ranges"`: Array of Objects. For dense layout, and sparse layout of one dimensional list properties, the array contains a single element which is a `slice object`_ representing the range of data present in the response. - In the specific case of a hierarchy of list properties represented as a sparse multi-dimensional array, if the field :field:`"returned_ranges"` is given, it MUST contain one slice object per dimension of the multi-dimensional array, representing slices for each dimension that cover the data given in the response. + In the specific case of a hierarchy of list properties represented as a sparse multidimensional array, if the field :field:`"returned_ranges"` is given, it MUST contain one slice object per dimension of the multidimensional array, representing slices for each dimension that cover the data given in the response. The header object MAY also contain the keys: @@ -3743,7 +3743,7 @@ The format of data lines of the response (i.e., all lines except the first and t - The second item of the array is the list property item located at the indicated index, represented using the same format as each line in the dense layout. In the same way as for the dense layout, reference-markers are allowed inside the item data for embedded lists that do not fit in the response (see example below). -- **Sparse layout for multi-dimensional lists:** the server MAY use a specific sparse layout for the case that the OPTIMADE property represents a series of directly hierarchically embedded lists (i.e., a multidimensional sparse array). +- **Sparse layout for multidimensional lists:** the server MAY use a specific sparse layout for the case that the OPTIMADE property represents a series of directly hierarchically embedded lists (i.e., a multidimensional sparse array). In this case, each data line contains a JSON array of the format: - All array items except the last one are integer zero-based indices of the list property item being provided by this line; these indices refer to the aggregated dimensions in the order of outermost to innermost. @@ -3785,7 +3785,7 @@ The third provided item (index 14 in the original list) is only partially return [[11, 110], ["PARTIAL-DATA-REF", ["https://example.db.org/value3"]], [550, 333]] ["PARTIAL-DATA-NEXT", ["https://example.db.org/value4"]] -Below follows an example of the sparse layout for multi-dimensional lists with three aggregated dimensions. +Below follows an example of the sparse layout for multidimensional lists with three aggregated dimensions. The underlying property value can be taken to be sparse data in lists in four dimensions of 10000 x 10000 x 10000 x N, where the innermost list is a non-sparse list of arbitrary length of numbers. The only non-null items in the outer three dimensions are, say, [3,5,19], [30,15,9], and [42,54,17]. The response below communicates the first item explicitly; the second one by deferring the innermost list using a reference-marker; and the third item is not included in this response, but deferred to another page via a next-marker. @@ -3797,7 +3797,7 @@ The response below communicates the first item explicitly; the second one by def [30,15,9, ["PARTIAL-DATA-REF", ["https://example.db.org/value1"]]] ["PARTIAL-DATA-NEXT", ["https://example.db.org/"]] -An example of the sparse layout for multi-dimensional lists with three aggregated dimensions and integer values: +An example of the sparse layout for multidimensional lists with three aggregated dimensions and integer values: .. code:: json @@ -3806,7 +3806,7 @@ An example of the sparse layout for multi-dimensional lists with three aggregate [30,15,9, 31] ["PARTIAL-DATA-NEXT", ["https://example.db.org/"]] -An example of the sparse layout for multi-dimensional lists with three aggregated dimensions and values that are multidimensional lists of integers of arbitrary lengths: +An example of the sparse layout for multidimensional lists with three aggregated dimensions and values that are multidimensional lists of integers of arbitrary lengths: .. code:: json From c152bf33799a70faada9bfd346f1e7fd59a57445 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 7 Aug 2023 13:25:00 +0200 Subject: [PATCH 09/10] revert changing format to version. --- optimade.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/optimade.rst b/optimade.rst index 74c4d4ae4..28c4f85a6 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3684,11 +3684,11 @@ The header object MUST contain the keys: It MUST contain the following key: - - :field:`"version"`: String. + - :field:`"format"`: String. Specifies the minor version of the partial data format used. The string MUST be of the format "MAJOR.MINOR", referring to the version of the OPTIMADE standard that describes the format. The version number string MUST NOT be prefixed by, e.g., "v". In implementations of the present version of the standard, the value MUST be exactly :val:`1.2`. - A client MUST NOT expect to be able to parse the :field:`version` value if the field is not a string of the format MAJOR.MINOR or if the MAJOR version number is unrecognized. + A client MUST NOT expect to be able to parse the :field:`format` value if the field is not a string of the format MAJOR.MINOR or if the MAJOR version number is unrecognized. - :field:`"layout"`: String. A string either equal to :val:`"dense"` or :val:`"sparse"` to indicate whether the returned format uses a dense or sparse layout. @@ -3768,7 +3768,7 @@ The request returns the first three items and provides the next-marker link to c .. code:: json - {"optimade-partial-data": {"version": "1.2.0"}, "layout": "dense", "returned_ranges": [{"start": 10, "stop": 20, "step": 2}]} + {"optimade-partial-data": {"format": "1.2.0"}, "layout": "dense", "returned_ranges": [{"start": 10, "stop": 20, "step": 2}]} 123 345 -12.6 @@ -3781,7 +3781,7 @@ The third provided item (index 14 in the original list) is only partially return .. code:: json - {"optimade-partial-data": {"version": "1.2.0"}, "layout": "dense", "returned_ranges": [{"start": 10, "stop": 20, "step": 2}]} + {"optimade-partial-data": {"format": "1.2.0"}, "layout": "dense", "returned_ranges": [{"start": 10, "stop": 20, "step": 2}]} [[10,20,21], [30,40,50]] ["PARTIAL-DATA-REF", ["https://example.db.org/value2"]] [[11, 110], ["PARTIAL-DATA-REF", ["https://example.db.org/value3"]], [550, 333]] @@ -3794,7 +3794,7 @@ The response below communicates the first item explicitly; the second one by def .. code:: json - {"optimade-partial-data": {"version": "1.2.0"}, "layout": "sparse"} + {"optimade-partial-data": {"format": "1.2.0"}, "layout": "sparse"} [3,5,19, [10,20,21,30]] [30,15,9, ["PARTIAL-DATA-REF", ["https://example.db.org/value1"]]] ["PARTIAL-DATA-NEXT", ["https://example.db.org/"]] @@ -3803,7 +3803,7 @@ An example of the sparse layout for multidimensional lists with three aggregated .. code:: json - {"optimade-partial-data": {"version": "1.2.0"}, "layout": "sparse"} + {"optimade-partial-data": {"format": "1.2.0"}, "layout": "sparse"} [3,5,19, 10] [30,15,9, 31] ["PARTIAL-DATA-NEXT", ["https://example.db.org/"]] @@ -3812,7 +3812,7 @@ An example of the sparse layout for multidimensional lists with three aggregated .. code:: json - {"optimade-partial-data": {"version": "1.2.0"}, "layout": "sparse"} + {"optimade-partial-data": {"format": "1.2.0"}, "layout": "sparse"} [3,5,19, [ [10,20,21], [30,40,50] ] ] [3,7,19, ["PARTIAL-DATA-REF", ["https://example.db.org/value2"]]] [4,5,19, [ [11, 110], ["PARTIAL-DATA-REF", ["https://example.db.org/value3"]], [550, 333]]] From 1fe318e1867ac72346117595b13892503f06c0d8 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Mon, 7 Aug 2023 15:57:17 +0200 Subject: [PATCH 10/10] Undid changing 'Array of Object' to 'Array of Objects' awaiting a bigger discussion about this point. --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 28c4f85a6..b91b89d43 100644 --- a/optimade.rst +++ b/optimade.rst @@ -3695,7 +3695,7 @@ The header object MUST contain the keys: The following key is RECOMMENDED in the header object: -- :field:`"returned_ranges"`: Array of Objects. +- :field:`"returned_ranges"`: Array of Object. For dense layout, and sparse layout of one dimensional list properties, the array contains a single element which is a `slice object`_ representing the range of data present in the response. In the specific case of a hierarchy of list properties represented as a sparse multidimensional array, if the field :field:`"returned_ranges"` is given, it MUST contain one slice object per dimension of the multidimensional array, representing slices for each dimension that cover the data given in the response.