diff --git a/optimade.rst b/optimade.rst index 6a5cf3156..747ae9383 100644 --- a/optimade.rst +++ b/optimade.rst @@ -1314,6 +1314,7 @@ Example: }, "available_endpoints": [ "structures", + "collections", "calculations", "info", "links" @@ -3180,6 +3181,93 @@ structure\_features - A structure having implicit atoms and using assemblies: :val:`["assemblies", "implicit_atoms"]` +Collections Entries +------------------- + +Collections entries are used to define a set of Entries of any types. +For example, a collection of Structure entries can be used to indicate that they are conceptually related, such as structures representing aluminium unit cells with point defects, or structures that comprise a training set for a particular interatomic potential. +The set of entries that belong to the collection is defined using one-to-many relationships from the collection to each entry (OPTIMADE relationships are defined in `Relationships`_). +A collection can contain other collections. +Furthermore, implementations are suggested to add database-specific properties for additional metadata they want to store about the collections. +An OPTIMADE response representing a collection with all referenced entries included via the JSON API field :field:`included` (or equivalent in other response formats) can be used as a universal format for storage or transfer of a subset of (or all) data in an OPTIMADE database. + +The following example shows how relationships from a collection to other entries defines the contents of the collection: + +.. code:: jsonc + + { + "data": { + "type": "collections", + "id": "42", + "attributes": { + "name": "Results set for vacancies in FCC Al" + "category": "results_set" + }, + "relationships": { + "structures": { + "data": [ + { "type": "structures", "id": "example.com:structures:4711" }, + { "type": "structures", "id": "example.com:structures:4712" }, + { "type": "structures", "id": "example.com:structures:4713" } + ] + }, + "calculations": { + "data": [ + { "type": "calculations", "id": "example.com:calculations:1899" } + ] + } + } + }, + } + +Collections entries have the properties described above in section `Properties Used by Multiple Entry Types`_, as well as the following additional properties: + +name +~~~~ + +- **Description**: A name for the collection +- **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:`"Results set for vacancies in FCC Al"` + - :val:`"Training set for the 'Si-001' interatomic potential."` + +description +~~~~~~~~~~~ + +- **Description**: A longer text that describes the collection +- **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:`"This collection contains structures used in an investigation into point defects in Al"` + - :val:`"Training set of structures, forces and energies used to construct the interatomic potential 'Si-001' for silicon, with associated bibliographic references."` + +category +~~~~~~~~ + +- **Description**: A free-form text categorizing the collection. + It is suggested that individual collections with similar purposes are assigned the same category to aid browsing and searching. +- **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:`"results_set"` + - :val:`"training_set"` + Calculations Entries --------------------