Applied changes from code review

Co-authored-by: Adam Fekete <fekad@users.noreply.github.com>

openapi/index_openapi.json

@@ -1422,7 +1422,7 @@
                 "$ref": "#/components/schemas/Relationships"
               }
             ],
-            "description": "a relationships object describing relationships between the resource and other JSON API resources."
+            "description": "Relationships object describing relationships between the resource and other JSON API resources."
           }
         },
         "description": "Resource objects appear in a JSON API document to represent resources."
@@ -1477,19 +1477,19 @@
           "api_version": {
             "title": "Api Version",
             "type": "string",
-            "description": "a string containing the version of the API implementation, e.g. v0.9.5"
+            "description": "A string containing the version of the API implementation, e.g. v0.9.5"
           },
           "time_stamp": {
             "title": "Time Stamp",
             "type": "string",
-            "description": "a timestamp containing the date and time at which the query was executed.",
+            "description": "A timestamp containing the date and time at which the query was executed.",
             "format": "date-time"
           },
           "data_returned": {
             "title": "Data Returned",
             "minimum": 0.0,
             "type": "integer",
-            "description": "an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination."
+            "description": "An integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination."
           },
           "more_data_available": {
             "title": "More Data Available",
@@ -1508,7 +1508,7 @@
           "data_available": {
             "title": "Data Available",
             "type": "integer",
-            "description": "an integer containing the total number of data resource objects available in the database for the endpoint."
+            "description": "An integer containing the total number of data resource objects available in the database for the endpoint."
           },
           "last_id": {
             "title": "Last Id",

openapi/openapi.json

@@ -1037,7 +1037,7 @@
                 "$ref": "#/components/schemas/Relationships"
               }
             ],
-            "description": "a relationships object describing relationships between the resource and other JSON API resources."
+            "description": "Relationships object describing relationships between the resource and other JSON API resources."
           }
         },
         "description": "Resource objects appear in a JSON API document to represent resources."
@@ -2596,7 +2596,7 @@
                 "$ref": "#/components/schemas/Relationships"
               }
             ],
-            "description": "a relationships object describing relationships between the resource and other JSON API resources."
+            "description": "Relationships object describing relationships between the resource and other JSON API resources."
           }
         },
         "description": "Resource objects appear in a JSON API document to represent resources."
@@ -2651,19 +2651,19 @@
           "api_version": {
             "title": "Api Version",
             "type": "string",
-            "description": "a string containing the version of the API implementation, e.g. v0.9.5"
+            "description": "A string containing the version of the API implementation, e.g. v0.9.5"
           },
           "time_stamp": {
             "title": "Time Stamp",
             "type": "string",
-            "description": "a timestamp containing the date and time at which the query was executed.",
+            "description": "A timestamp containing the date and time at which the query was executed.",
             "format": "date-time"
           },
           "data_returned": {
             "title": "Data Returned",
             "minimum": 0.0,
             "type": "integer",
-            "description": "an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination."
+            "description": "An integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination."
           },
           "more_data_available": {
             "title": "More Data Available",
@@ -2682,7 +2682,7 @@
           "data_available": {
             "title": "Data Available",
             "type": "integer",
-            "description": "an integer containing the total number of data resource objects available in the database for the endpoint."
+            "description": "An integer containing the total number of data resource objects available in the database for the endpoint."
           },
           "last_id": {
             "title": "Last Id",
@@ -2849,7 +2849,7 @@
           "type": {
             "title": "Type",
             "type": "string",
-            "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n    - **Query**: MUST be a queryable property with support for all mandatory filter features.\n    - **Response**: REQUIRED in the response.\n    - MUST be an existing entry type.\n    - The entry of type `<type>` and ID `<id>` MUST be returned in response to a request for `/<type>/<id>` under the versioned base URL.\n\n- **Example**: `\"structures\"`"
+            "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n    - **Query**: MUST be a queryable property with support for all mandatory filter features.\n    - **Response**: REQUIRED in the response.\n    - MUST be an existing entry type.\n    - The entry of type `<type>` and ID `<id>` MUST be returned in response to a request for `/<type>/<id>` under the versioned base URL.\n\n- **Examples**:\n    - `\"structures\"`"
           },
           "links": {
             "title": "Links",
@@ -2925,7 +2925,7 @@
           "nelements": {
             "title": "Nelements",
             "type": "integer",
-            "description": "Number of different elements in the structure as an integer.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n    - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Example**: `3`\n\n- **Querying**:\n    - Note: queries on this property can equivalently be formulated using `elements LENGTH`.\n    - A filter that matches structures that have exactly 4 elements: `nelements=4`.\n    - A filter that matches structures that have between 2 and 7 elements: `nelements>=2 AND nelements<=7`."
+            "description": "Number of different elements in the structure as an integer.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n    - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n    - `3`\n\n- **Querying**:\n    - Note: queries on this property can equivalently be formulated using `elements LENGTH`.\n    - A filter that matches structures that have exactly 4 elements: `nelements=4`.\n    - A filter that matches structures that have between 2 and 7 elements: `nelements>=2 AND nelements<=7`."
           },
           "elements_ratios": {
             "title": "Elements Ratios",

optimade/models/jsonapi.py

@@ -137,7 +137,7 @@ class BaseResource(BaseModel):
 
 
 class RelationshipLinks(BaseModel):
-    """ A resource object **MAY** contain references to other resource objects (\"relationships\").
+    """A resource object **MAY** contain references to other resource objects (\"relationships\").
     Relationships may be to-one or to-many.
     Relationships can be specified by including a member in a resource's links object.
 
@@ -255,7 +255,7 @@ class Resource(BaseResource):
     )
     relationships: Optional[Relationships] = Field(
         None,
-        description="a relationships object describing relationships between the resource and other JSON API resources.",
+        description="Relationships object describing relationships between the resource and other JSON API resources.",
     )
 
 

optimade/models/optimade_json.py

@@ -238,17 +238,17 @@ class ResponseMeta(jsonapi.Meta):
 
     api_version: str = Field(
         ...,
-        description="a string containing the version of the API implementation, e.g. v0.9.5",
+        description="A string containing the version of the API implementation, e.g. v0.9.5",
     )
 
     time_stamp: datetime = Field(
         ...,
-        description="a timestamp containing the date and time at which the query was executed.",
+        description="A timestamp containing the date and time at which the query was executed.",
     )
 
     data_returned: int = Field(
         ...,
-        description="an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination.",
+        description="An integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination.",
         ge=0,
     )
 
@@ -263,7 +263,7 @@ class ResponseMeta(jsonapi.Meta):
 
     data_available: Optional[int] = Field(
         None,
-        description="an integer containing the total number of data resource objects available in the database for the endpoint.",
+        description="An integer containing the total number of data resource objects available in the database for the endpoint.",
     )
 
     last_id: Optional[str] = Field(

optimade/models/references.py

@@ -111,7 +111,7 @@ class ReferenceResourceAttributes(EntryResourceAttributes):
 
 
 class ReferenceResource(EntryResource):
-    """ The `references` entries describe bibliographic references.
+    """The `references` entries describe bibliographic references.
     The following properties are used to provide the bibliographic details:
 
     - **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **volume**, **year**: meanings of these properties match the [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf), values are strings;

optimade/models/structures.py

@@ -45,7 +45,7 @@ class StructureFeatures(Enum):
 
 
 class Species(BaseModel):
-    """ A list describing the species of the sites of this structure.
+    """A list describing the species of the sites of this structure.
     Species can represent pure chemical elements, virtual-crystal atoms representing a
     statistical occupation of a given site by multiple chemical elements, and/or a
     location to which there are attached atoms, i.e., atoms whose precise location are
@@ -245,7 +245,8 @@ class StructureResourceAttributes(EntryResourceAttributes):
     - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
     - **Query**: MUST be a queryable property with support for all mandatory filter features.
 
-- **Example**: `3`
+- **Examples**:
+    - `3`
 
 - **Querying**:
     - Note: queries on this property can equivalently be formulated using `elements LENGTH`.
@@ -884,7 +885,8 @@ class StructureResource(EntryResource):
     - MUST be an existing entry type.
     - The entry of type `<type>` and ID `<id>` MUST be returned in response to a request for `/<type>/<id>` under the versioned base URL.
 
-- **Example**: `"structures"`""",
+- **Examples**:
+    - `"structures"`""",
     )
 
     attributes: StructureResourceAttributes