From 318c2b5fa5c594c2ce30bd747c97cc92c7d7d810 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Mon, 7 Jun 2021 21:29:02 +0300 Subject: [PATCH 01/29] Adding a scaffold to describe files endpoint. --- optimade.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/optimade.rst b/optimade.rst index 35a2196eb..8f54c2e44 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2371,6 +2371,21 @@ Example: } } +Files Entries +------------- + +The :entry:`files` entries describe files. +The following properties are used to do so: + +name +~~~~ + +url +~~~ + +content\_type +~~~~~~~~~~~~~ + Database-Provider-Specific Entry Types -------------------------------------- From 6c37306987ede809886be9dfeea35015124117ae Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Tue, 8 Jun 2021 08:00:32 +0300 Subject: [PATCH 02/29] Describing attributes of files endpoint. --- optimade.rst | 53 ++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/optimade.rst b/optimade.rst index 8f54c2e44..4f7c5b98b 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2377,14 +2377,59 @@ Files Entries The :entry:`files` entries describe files. The following properties are used to do so: +url +~~~ + +- **Description**: The URL to get the contents of a file. +- **Type**: string. +- **Requirements/Conventions**: + + - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - **Response**: REQUIRED in the response. + +- **Examples**: + + - :val:`"https://www.crystallography.net/cod/1000000.cif"` + name ~~~~ -url -~~~ +- **Description**: base name of a file. +- **Type**: string. +- **Requirements/Conventions**: -content\_type -~~~~~~~~~~~~~ + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + +- **Examples**: + + - :val:`"1000000.cif"` + +media\_type +~~~~~~~~~~~ + +- **Description**: media type identifier for a file. +- **Type**: string. +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + +- **Examples**: + + - :val:`"chemical/x-cif"` + +version +~~~~~~~ + +- **Description**: version information of a file (e.g. commit, revision, timestamp) +- **Type**: string. +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - If provided, it MUST be guaranteed that file contents pertaining to the same combination of :field:`id` and :field:`version` are the same. Database-Provider-Specific Entry Types -------------------------------------- From 5fc402c78b87c52a1cce677750b17eaf6a931ec2 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Tue, 8 Jun 2021 08:16:14 +0300 Subject: [PATCH 03/29] Listing files endpoint under 'Relationships Used by Multiple Entry Types'. --- optimade.rst | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/optimade.rst b/optimade.rst index 4f7c5b98b..a38d3f612 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2522,6 +2522,41 @@ Relationships with calculations MAY be used to indicate provenance where a struc At the moment the database providers are suggested to extend their API the way they choose, always using their database-provider-specific prefix in non-standardized fields. +Files +~~~~~ + +Relationships with files MAY be used to relate an entry with any number of :entry:`files` entries. +Alternatively, they MAY be used to provide file representations of entries. + +.. code:: jsonc + + { + "data": { + "type": "structures", + "id": "example.db:structs:1234", + "attributes": { + "formula": "H2O" + }, + "relationships": { + "files": { + "data": [ + { "type": "files", "id": "example.db:files:1234" } + ] + } + } + }, + "included": [ + { + "type": "files", + "id": "example.db:files:1234", + "attributes": { + "media_type": "chemical/x-cif", + "url": "https://example.db/files/1234.cif" + } + } + ] + } + Appendices ========== From 6a06bde6169bec6acfcb38edde622a75cb2ae0b8 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Tue, 8 Jun 2021 13:09:11 +0300 Subject: [PATCH 04/29] Simplifying the description of relationships with Files entries. --- optimade.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index a38d3f612..141603399 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2525,8 +2525,7 @@ Relationships with calculations MAY be used to indicate provenance where a struc Files ~~~~~ -Relationships with files MAY be used to relate an entry with any number of :entry:`files` entries. -Alternatively, they MAY be used to provide file representations of entries. +Relationships with files may be used to relate an entry with any number of :entry:`files` entries. .. code:: jsonc From c1b1227f6d5619f44742c1a3485824d4c00c3cb5 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 8 Sep 2021 10:09:02 +0300 Subject: [PATCH 05/29] Update optimade.rst Co-authored-by: Rickard Armiento --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 1968ad8bb..3cda5c90c 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2392,7 +2392,7 @@ url - **Examples**: - - :val:`"https://www.crystallography.net/cod/1000000.cif"` + - :val:`"https://example.org/files/cifs/1000000.cif"` name ~~~~ From 57b18d63ce5da908b7117505bf88cca9714b85b8 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 8 Sep 2021 15:11:57 +0300 Subject: [PATCH 06/29] Update optimade.rst Co-authored-by: Rickard Armiento --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 1ffd1f046..903fb675e 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2550,7 +2550,7 @@ Relationships with files may be used to relate an entry with any number of :entr "id": "example.db:files:1234", "attributes": { "media_type": "chemical/x-cif", - "url": "https://example.db/files/1234.cif" + "url": "https://example.org/files/cifs/1234.cif" } } ] From f3ced3e9ff92513e8acbbbfb75c3f4ae85fe331a Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Mon, 27 Sep 2021 10:16:16 +0300 Subject: [PATCH 07/29] Introducing `description` property for free-form text. --- optimade.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/optimade.rst b/optimade.rst index 903fb675e..7e589e2b7 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2431,6 +2431,20 @@ version - **Query**: Support for queries on this property is OPTIONAL. - If provided, it MUST be guaranteed that file contents pertaining to the same combination of :field:`id` and :field:`version` are the same. +description +~~~~~~~~~~~ + +- **Description**: free-form description of a file. +- **Type**: string. +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + +- **Examples**: + + - :val:`"POSCAR format file"` + Database-Provider-Specific Entry Types -------------------------------------- From 04193741898c0dabfeb3351cf0754bf97e1fa300 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Mon, 27 Sep 2021 10:24:53 +0300 Subject: [PATCH 08/29] Describing `media_type` as RFC 6838 string. --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 7e589e2b7..bf9bde607 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2409,7 +2409,7 @@ name media\_type ~~~~~~~~~~~ -- **Description**: media type identifier for a file. +- **Description**: media type identifier for a file as per `RFC 6838 Media Type Specifications and Registration Procedures `__. - **Type**: string. - **Requirements/Conventions**: From 24e290796c860f99dc7b7f0dc453162dbfcdb7f1 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Mon, 22 Nov 2021 16:10:35 +0200 Subject: [PATCH 09/29] Including `atime`, `ctime` and `mtime` as per @sauliusg request. --- optimade.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/optimade.rst b/optimade.rst index bf9bde607..32691c726 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2445,6 +2445,36 @@ description - :val:`"POSCAR format file"` +atime +~~~~~ + +- **Description**: time of last access of a file. +- **Type**: timestamp. +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + +ctime +~~~~~ + +- **Description**: time of last status change of a file. +- **Type**: timestamp. +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + +mtime +~~~~~ + +- **Description**: time of last modification of a file. +- **Type**: timestamp. +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + Database-Provider-Specific Entry Types -------------------------------------- From fb187a74e4ae0e6d4395244d362520487684aba3 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Fri, 26 Nov 2021 10:54:09 +0200 Subject: [PATCH 10/29] Redefining `url` as JSON API links object. --- optimade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 32691c726..bdc6ffee1 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2380,8 +2380,8 @@ The following properties are used to do so: url ~~~ -- **Description**: The URL to get the contents of a file. -- **Type**: string. +- **Description**: a `JSON API links object `__ with a URL to get the contents of a file. +- **Type**: `JSON API links object `__. - **Requirements/Conventions**: - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`. From 82f3d11f32b08d86c9b13fde09d36db7acf4564c Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Fri, 26 Nov 2021 11:21:03 +0200 Subject: [PATCH 11/29] Including `size` as per @ml-evs request. --- optimade.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/optimade.rst b/optimade.rst index bdc6ffee1..a7d8c0ee1 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2406,6 +2406,19 @@ name - :val:`"1000000.cif"` +size +~~~~ + +- **Description**: size of a file in bytes. +- **Type**: integer +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - If provided, it MUST be guaranteed that either exact size of a file is given or its upper bound. + This way if a client reserves a static buffer or truncates the download stream after this many bytes the whole file would be received. + Such provision is included to allow the providers to serve on-the-fly compressed files. + media\_type ~~~~~~~~~~~ From e535aa14e1d0caa0231e577531db54409c347c9c Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Fri, 26 Nov 2021 11:25:40 +0200 Subject: [PATCH 12/29] Starting each sentence with a capital letter. Removing excess periods. --- optimade.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/optimade.rst b/optimade.rst index a7d8c0ee1..160718be3 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2380,7 +2380,7 @@ The following properties are used to do so: url ~~~ -- **Description**: a `JSON API links object `__ with a URL to get the contents of a file. +- **Description**: A `JSON API links object `__ with a URL to get the contents of a file. - **Type**: `JSON API links object `__. - **Requirements/Conventions**: @@ -2395,7 +2395,7 @@ url name ~~~~ -- **Description**: base name of a file. +- **Description**: Base name of a file. - **Type**: string. - **Requirements/Conventions**: @@ -2409,7 +2409,7 @@ name size ~~~~ -- **Description**: size of a file in bytes. +- **Description**: Size of a file in bytes. - **Type**: integer - **Requirements/Conventions**: @@ -2422,8 +2422,8 @@ size media\_type ~~~~~~~~~~~ -- **Description**: media type identifier for a file as per `RFC 6838 Media Type Specifications and Registration Procedures `__. -- **Type**: string. +- **Description**: Media type identifier for a file as per `RFC 6838 Media Type Specifications and Registration Procedures `__. +- **Type**: string - **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. @@ -2436,8 +2436,8 @@ media\_type version ~~~~~~~ -- **Description**: version information of a file (e.g. commit, revision, timestamp) -- **Type**: string. +- **Description**: Version information of a file (e.g. commit, revision, timestamp). +- **Type**: string - **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. @@ -2447,8 +2447,8 @@ version description ~~~~~~~~~~~ -- **Description**: free-form description of a file. -- **Type**: string. +- **Description**: Free-form description of a file. +- **Type**: string - **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. @@ -2461,8 +2461,8 @@ description atime ~~~~~ -- **Description**: time of last access of a file. -- **Type**: timestamp. +- **Description**: Time of last access of a file. +- **Type**: timestamp - **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. @@ -2471,8 +2471,8 @@ atime ctime ~~~~~ -- **Description**: time of last status change of a file. -- **Type**: timestamp. +- **Description**: Time of last status change of a file. +- **Type**: timestamp - **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. @@ -2481,8 +2481,8 @@ ctime mtime ~~~~~ -- **Description**: time of last modification of a file. -- **Type**: timestamp. +- **Description**: Time of last modification of a file. +- **Type**: timestamp - **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. From d68037073f099a7be290296cf8ae15f1be92ad84 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 8 Dec 2021 17:53:11 +0200 Subject: [PATCH 13/29] Revert "Redefining `url` as JSON API links object." This reverts commit fb187a74e4ae0e6d4395244d362520487684aba3. --- optimade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 160718be3..e49fdab9c 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2380,8 +2380,8 @@ The following properties are used to do so: url ~~~ -- **Description**: A `JSON API links object `__ with a URL to get the contents of a file. -- **Type**: `JSON API links object `__. +- **Description**: The URL to get the contents of a file. +- **Type**: string - **Requirements/Conventions**: - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`. From 32e265e75288682244d5bcebf317ec4a6f1f7277 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 8 Dec 2021 17:56:47 +0200 Subject: [PATCH 14/29] Removing excess period ('.'). --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index e49fdab9c..37b26ab70 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2396,7 +2396,7 @@ name ~~~~ - **Description**: Base name of a file. -- **Type**: string. +- **Type**: string - **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. From 467d117369111aa75c6d28100a3bbd61cf42a260 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 8 Dec 2021 18:01:46 +0200 Subject: [PATCH 15/29] Making support for 'name' mandatory. --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 37b26ab70..47c5d45d2 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2399,7 +2399,7 @@ name - **Type**: string - **Requirements/Conventions**: - - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. - **Examples**: From 574a27c92ed9426f32725ef78026987698e533d8 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Thu, 9 Dec 2021 17:45:42 +0200 Subject: [PATCH 16/29] File name extension is an integral part of a file name. --- optimade.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/optimade.rst b/optimade.rst index 47c5d45d2..a21436f34 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2401,6 +2401,7 @@ name - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. + - File name extension is an integral part of a file name and, if available, MUST be included. - **Examples**: From 63b492d237ba02c76fbe7277824113a2f3a602f9 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Thu, 9 Dec 2021 17:47:31 +0200 Subject: [PATCH 17/29] Mentioning POSIX in `xtime` definitions. --- optimade.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/optimade.rst b/optimade.rst index a21436f34..898c7c384 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2462,7 +2462,7 @@ description atime ~~~~~ -- **Description**: Time of last access of a file. +- **Description**: Time of last access of a file as per POSIX standard. - **Type**: timestamp - **Requirements/Conventions**: @@ -2472,7 +2472,7 @@ atime ctime ~~~~~ -- **Description**: Time of last status change of a file. +- **Description**: Time of last status change of a file as per POSIX standard. - **Type**: timestamp - **Requirements/Conventions**: @@ -2482,7 +2482,7 @@ ctime mtime ~~~~~ -- **Description**: Time of last modification of a file. +- **Description**: Time of last modification of a file as per POSIX standard. - **Type**: timestamp - **Requirements/Conventions**: From 1b3bbfdbf8050016ea43f7c5cab1d7419f1acc06 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Thu, 9 Dec 2021 17:58:14 +0200 Subject: [PATCH 18/29] Describing the relation between `mtime` and `last_modified`. --- optimade.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/optimade.rst b/optimade.rst index 898c7c384..2a5f842c2 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2488,6 +2488,9 @@ mtime - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. + - It should be noted that the values of :field:`mtime` and :field:`last_modified` do not necessary match. + :field:`mtime` pertains to the modification of the file, while :field:`last_modified` pertains to its contents. + For example, appending an empty string to a file would result in the change of :field:`mtime` in some operating systems, but this would not be deemed as a modification of its contents. Database-Provider-Specific Entry Types -------------------------------------- From 6959f5fe3fff843e9b9faaf7847eeba4799ee17f Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Thu, 9 Dec 2021 18:00:42 +0200 Subject: [PATCH 19/29] Introducing `md5sum` and `sha1sum`. --- optimade.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/optimade.rst b/optimade.rst index 2a5f842c2..19674073b 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2459,6 +2459,26 @@ description - :val:`"POSCAR format file"` +md5sum +~~~~~~ + +- **Description**: MD5 checksum of file contents. +- **Type**: string +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + +sha1sum +~~~~~~~ + +- **Description**: SHA1 checksum of file contents. +- **Type**: string +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + atime ~~~~~ From 5d7e9d4952eb45101b3b6c1dc8a37a248e529c60 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Fri, 10 Dec 2021 10:05:56 +0200 Subject: [PATCH 20/29] Adding `url_stable_until`. --- optimade.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/optimade.rst b/optimade.rst index 19674073b..0c34b15cd 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2392,6 +2392,18 @@ url - :val:`"https://example.org/files/cifs/1000000.cif"` +url_stable_until +~~~~~~~~~~~~~~~~ + +- **Description**: Point in time until which the URL in `url` is guaranteed to stay stable. +- **Type**: timestamp +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - :val:`null` means that there is no stability guarantee for the URL in `url`. + Indefinite support could be communicated by providing a date sufficiently far in the future, for example, :val:`9999-12-31`. + name ~~~~ From d3e5c9b4807f88705e720b9b3ba4e8b62e11f810 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Fri, 10 Dec 2021 10:23:31 +0200 Subject: [PATCH 21/29] Adding `modification_timestamp`. --- optimade.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/optimade.rst b/optimade.rst index 0c34b15cd..d0770cb52 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2457,6 +2457,17 @@ version - **Query**: Support for queries on this property is OPTIONAL. - If provided, it MUST be guaranteed that file contents pertaining to the same combination of :field:`id` and :field:`version` are the same. +modification_timestamp +~~~~~~~~~~~~~~~~~~~~~~ + +- **Description**: Timestamp of the last modification of file contents. + A modification is understood as an addition, change or deletion of one or more bytes, resulting in file contents different from the previous. +- **Type**: timestamp +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + description ~~~~~~~~~~~ From 3d6f3b215b3c9296093e9bdb3fbff8a467074c40 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Fri, 10 Dec 2021 10:50:38 +0200 Subject: [PATCH 22/29] Describing the relation between `last_modified`, `modification_timestamp` and `mtime` a bit better. --- optimade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index d0770cb52..a89b38f9c 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2531,8 +2531,8 @@ mtime - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. - - It should be noted that the values of :field:`mtime` and :field:`last_modified` do not necessary match. - :field:`mtime` pertains to the modification of the file, while :field:`last_modified` pertains to its contents. + - It should be noted that the values of :field:`last_modified`, :field:`modification_timestamp` and :field:`mtime` do not necessary match. + :field:`last_modified` pertains to the modification of the OPTIMADE metadata, :field:`modification_timestamp` pertains to file contents and :field:`mtime` pertains to the modification of the file (not necessary changing its contents). For example, appending an empty string to a file would result in the change of :field:`mtime` in some operating systems, but this would not be deemed as a modification of its contents. Database-Provider-Specific Entry Types From b85e16d9ffb6def420156f85a8f49a4e69a4ccb9 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Tue, 14 Dec 2021 10:47:57 +0200 Subject: [PATCH 23/29] Values for `modification_timestamp` SHOULD be increasing (as per @JPBergsma suggestion). --- optimade.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/optimade.rst b/optimade.rst index a89b38f9c..b62501b4f 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2467,6 +2467,7 @@ modification_timestamp - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. + - Timestamps of subsequent file modifications SHOULD be increasing (not earlier than previous timestamps). description ~~~~~~~~~~~ From 1b3d80f14293bf7af6b9f79d3f5bf1d38f1f75c0 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 1 Jun 2022 10:36:24 +0200 Subject: [PATCH 24/29] Clarifying that an URL has to point to actual raw contents of a file. --- optimade.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/optimade.rst b/optimade.rst index 7b875960d..4e83e568d 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2414,6 +2414,8 @@ url ~~~ - **Description**: The URL to get the contents of a file. + The URL MUST point to the actual contents of a file (i.e. octet stream), not an intermediate (preview) representation. + For example, if referring to a file on GitHub, a link should point to raw contents. - **Type**: string - **Requirements/Conventions**: From ae07299769c8a7b92d00f0864c14b5717e1ab9e5 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 1 Jun 2022 11:40:44 +0200 Subject: [PATCH 25/29] Moving the explanation of restrictions for `url` usage lower. --- optimade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 4e83e568d..a3caa44d2 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2414,14 +2414,14 @@ url ~~~ - **Description**: The URL to get the contents of a file. - The URL MUST point to the actual contents of a file (i.e. octet stream), not an intermediate (preview) representation. - For example, if referring to a file on GitHub, a link should point to raw contents. - **Type**: string - **Requirements/Conventions**: - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. - **Response**: REQUIRED in the response. + - The URL MUST point to the actual contents of a file (i.e. octet stream), not an intermediate (preview) representation. + For example, if referring to a file on GitHub, a link should point to raw contents. - **Examples**: From 93e92ca8f7d04d98e84555de5b2953ac9bba6578 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 1 Jun 2022 11:51:28 +0200 Subject: [PATCH 26/29] Substituting: "octet stream" -> "byte stream". --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index a3caa44d2..95a5084b7 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2420,7 +2420,7 @@ url - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. - **Response**: REQUIRED in the response. - - The URL MUST point to the actual contents of a file (i.e. octet stream), not an intermediate (preview) representation. + - The URL MUST point to the actual contents of a file (i.e. byte stream), not an intermediate (preview) representation. For example, if referring to a file on GitHub, a link should point to raw contents. - **Examples**: From 210131f420d4a33d3e818f467d10d4954fc5546f Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 1 Jun 2022 11:57:21 +0200 Subject: [PATCH 27/29] Escaping `_` in property names used for subsection titles. --- optimade.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/optimade.rst b/optimade.rst index 95a5084b7..a436dba0d 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2427,8 +2427,8 @@ url - :val:`"https://example.org/files/cifs/1000000.cif"` -url_stable_until -~~~~~~~~~~~~~~~~ +url\_stable\_until +~~~~~~~~~~~~~~~~~~ - **Description**: Point in time until which the URL in `url` is guaranteed to stay stable. - **Type**: timestamp @@ -2492,8 +2492,8 @@ version - **Query**: Support for queries on this property is OPTIONAL. - If provided, it MUST be guaranteed that file contents pertaining to the same combination of :field:`id` and :field:`version` are the same. -modification_timestamp -~~~~~~~~~~~~~~~~~~~~~~ +modification\_timestamp +~~~~~~~~~~~~~~~~~~~~~~~ - **Description**: Timestamp of the last modification of file contents. A modification is understood as an addition, change or deletion of one or more bytes, resulting in file contents different from the previous. From e9d0274fa8b53f1be701dd0812559fc95cb4ac2e Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 1 Jun 2022 13:00:35 +0300 Subject: [PATCH 28/29] Update optimade.rst Co-authored-by: Matthew Evans <7916000+ml-evs@users.noreply.github.com> --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index a436dba0d..d50d2b58f 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2674,7 +2674,7 @@ Relationships with files may be used to relate an entry with any number of :entr "type": "structures", "id": "example.db:structs:1234", "attributes": { - "formula": "H2O" + "chemical_formula_descriptive": "H2O" }, "relationships": { "files": { From e05b0f398eec3792588798c11dca34f6fdd617b9 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 1 Jun 2022 17:18:28 +0200 Subject: [PATCH 29/29] Moving all checksums to `checksums` property. --- optimade.rst | 22 +++++++--------------- 1 file changed, 7 insertions(+), 15 deletions(-) diff --git a/optimade.rst b/optimade.rst index f77350ccf..59b5ad5af 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2518,25 +2518,17 @@ description - :val:`"POSCAR format file"` -md5sum -~~~~~~ - -- **Description**: MD5 checksum of file contents. -- **Type**: string -- **Requirements/Conventions**: - - - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - - **Query**: Support for queries on this property is OPTIONAL. - -sha1sum -~~~~~~~ +checksums +~~~~~~~~~ -- **Description**: SHA1 checksum of file contents. -- **Type**: string -- **Requirements/Conventions**: +* **Description**: Dictionary providing checksums of file contents. +* **Type**: dictionary with keys identifying checksum functions and values (strings) giving the actual checksums +* **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. + - Supported dictionary keys: :property:`md5`, :property:`sha1`, :property:`sha224`, :property:`sha256`, :property:`sha384`, :property:`sha512`. + Checksums outside this list MAY be used, but their names MUST be prefixed by database-provider-specific namespace prefix (see appendix `Database-Provider-Specific Namespace Prefixes`_). atime ~~~~~