diff --git a/optimade.rst b/optimade.rst index 874ed765b..2c33f9461 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2423,6 +2423,165 @@ Example: } } +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. + - 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**: + + - :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 +~~~~ + +- **Description**: Base name 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. + - File name extension is an integral part of a file name and, if available, MUST be included. + +- **Examples**: + + - :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 +~~~~~~~~~~~ + +- **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`. + - **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. + +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. + - Timestamps of subsequent file modifications SHOULD be increasing (not earlier than previous timestamps). + +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"` + +checksums +~~~~~~~~~ + +* **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 +~~~~~ + +- **Description**: Time of last access of a file as per POSIX standard. +- **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 as per POSIX standard. +- **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 as per POSIX standard. +- **Type**: timestamp +- **Requirements/Conventions**: + + - **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:`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 -------------------------------------- @@ -2514,6 +2673,40 @@ 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. + +.. code:: jsonc + + { + "data": { + "type": "structures", + "id": "example.db:structs:1234", + "attributes": { + "chemical_formula_descriptive": "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.org/files/cifs/1234.cif" + } + } + ] + } + Appendices ==========