Collections endpoint

optimade.rst

@@ -1088,6 +1088,7 @@ Example:
           },
           "available_endpoints": [
             "structures",
+            "collections",
             "calculations",
             "info",
             "links"
@@ -2808,6 +2809,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
 --------------------