Changes from code review

Co-authored-by: Casper Welzel Andersen <CasperWA@users.noreply.github.com>

openapi/index_openapi.json

@@ -709,7 +709,7 @@
           "is_index": {
             "title": "Is Index",
             "type": "boolean",
-            "description": "If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for `is_index` to be false)."
+            "description": "This must be `true` since this is an index meta-database (see section Index Meta-Database)."
           }
         },
         "description": "Attributes for Base URL Info endpoint for an Index Meta-Database"
@@ -757,7 +757,7 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/IndexRelationship"
             },
-            "description": "Reference to the child identifier object under the `links` endpoint that the provider has chosen as their 'default' OPTIMADE API database.\nA client SHOULD present this database as the first choice when an end-user chooses this provider."
+            "description": "Reference to the Links identifier object under the `links` endpoint that the provider has chosen as their 'default' OPTIMADE API database.\nA client SHOULD present this database as the first choice when an end-user chooses this provider."
           }
         },
         "description": "Index Meta-Database Base URL Info endpoint resource"
@@ -840,7 +840,7 @@
                 "$ref": "#/components/schemas/RelatedLinksResource"
               }
             ],
-            "description": "JSON API resource linkage.\nIt MUST be either `null` or contain a single Links identifier object with the fields `id` and `type`"
+            "description": "[JSON API resource linkage](http://jsonapi.org/format/1.0/#document-links).\nIt MUST be either `null` or contain a single Links identifier object with the fields `id` and `type`"
           }
         },
         "description": "Index Meta-Database relationship"
@@ -937,7 +937,7 @@
                 "$ref": "#/components/schemas/LinksResourceAttributes"
               }
             ],
-            "description": "A dictionary containing key-value pairs representing the entry's properties."
+            "description": "A dictionary containing key-value pairs representing the Links resource's properties."
           },
           "relationships": {
             "title": "Relationships",
@@ -1018,7 +1018,7 @@
               "external",
               "providers"
             ],
-            "description": "The link type of the represented resource in relation to this implementation.\nMUST be one of these values: 'child', 'root', 'external', 'providers'."
+            "description": "The type of the linked relation.\nMUST be one of these values: 'child', 'root', 'external', 'providers'."
           },
           "aggregate": {
             "title": "Aggregate",
@@ -1340,7 +1340,7 @@
                 ]
               }
             ],
-            "description": "A link to itself"
+            "description": "A link for the relationship itself (a 'relationship link').\nThis link allows the client to directly manipulate the relationship.\nWhen fetched successfully, this link returns the [linkage](https://jsonapi.org/format/1.0/#document-resource-object-linkage) for the related resources as its primary data.\n(See [Fetching Relationships](https://jsonapi.org/format/1.0/#fetching-relationships).)"
           },
           "related": {
             "title": "Related",
@@ -1362,7 +1362,7 @@
             "description": "A related resource link"
           }
         },
-        "description": "A resource object **MAY** contain references to other resource objects (\"relationships\").\nRelationships may be to-one or to-many.\nRelationships can be specified by including a member in a resource's links object."
+        "description": "A [related resource link](https://jsonapi.org/format/1.0/#document-resource-object-related-resource-links). "
       },
       "Relationships": {
         "title": "Relationships",
@@ -1422,7 +1422,7 @@
                 "$ref": "#/components/schemas/Relationships"
               }
             ],
-            "description": "Relationships object describing relationships between the resource and other JSON API resources."
+            "description": "[Relationships object](https://jsonapi.org/format/1.0/#document-resource-object-relationships)\ndescribing relationships between the resource and other JSON API resources."
           }
         },
         "description": "Resource objects appear in a JSON API document to represent resources."
@@ -1472,12 +1472,12 @@
                 "$ref": "#/components/schemas/ResponseMetaQuery"
               }
             ],
-            "description": "information on the query that was requested"
+            "description": "Information on the Query that was requested"
           },
           "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."
           },
           "time_stamp": {
             "title": "Time Stamp",

openapi/openapi.json

@@ -988,7 +988,7 @@
           "is_index": {
             "title": "Is Index",
             "type": "boolean",
-            "description": "If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for `is_index` to be false).",
+            "description": "If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for `is_index` to be `false`).",
             "default": false
           }
         },
@@ -1037,7 +1037,7 @@
                 "$ref": "#/components/schemas/Relationships"
               }
             ],
-            "description": "Relationships object describing relationships between the resource and other JSON API resources."
+            "description": "[Relationships object](https://jsonapi.org/format/1.0/#document-resource-object-relationships)\ndescribing relationships between the resource and other JSON API resources."
           }
         },
         "description": "Resource objects appear in a JSON API document to represent resources."
@@ -1121,7 +1121,7 @@
               "dictionary",
               "unknown"
             ],
-            "description": "String.\nThe type of the property's value.\n\nThis MUST be any of the types defined in the Data types section.\nFor the purpose of compatibility with future versions of this specification, a client MUST accept values that are not `string` values specifying any of the OPTIMADE Data types, but MUST then also disregard the `type` field.\nNote, if the value is a nested type, only the outermost type should be reported.\nE.g., for the entry resource `structures`, the `species` property is defined as a list of dictionaries, hence its `type` value would be `list`.\nData type of value. Must equal a valid OPTIMADE data type as listed and defined under 'Data types'."
+            "description": "The type of the property's value.\n\nThis MUST be any of the types defined in the Data types section.\nFor the purpose of compatibility with future versions of this specification, a client MUST accept values that are not `string` values specifying any of the OPTIMADE Data types, but MUST then also disregard the `type` field.\nNote, if the value is a nested type, only the outermost type should be reported.\nE.g., for the entry resource `structures`, the `species` property is defined as a list of dictionaries, hence its `type` value would be `list`."
           }
         }
       },
@@ -1146,7 +1146,7 @@
           "description": {
             "title": "Description",
             "type": "string",
-            "description": "Description of the entry"
+            "description": "Description of the entry."
           },
           "properties": {
             "title": "Properties",
@@ -1733,7 +1733,7 @@
                 "$ref": "#/components/schemas/LinksResourceAttributes"
               }
             ],
-            "description": "A dictionary containing key-value pairs representing the entry's properties."
+            "description": "A dictionary containing key-value pairs representing the Links resource's properties."
           },
           "relationships": {
             "title": "Relationships",
@@ -1814,7 +1814,7 @@
               "external",
               "providers"
             ],
-            "description": "The link type of the represented resource in relation to this implementation.\nMUST be one of these values: 'child', 'root', 'external', 'providers'."
+            "description": "The type of the linked relation.\nMUST be one of these values: 'child', 'root', 'external', 'providers'."
           },
           "aggregate": {
             "title": "Aggregate",
@@ -2514,7 +2514,7 @@
                 ]
               }
             ],
-            "description": "A link to itself"
+            "description": "A link for the relationship itself (a 'relationship link').\nThis link allows the client to directly manipulate the relationship.\nWhen fetched successfully, this link returns the [linkage](https://jsonapi.org/format/1.0/#document-resource-object-linkage) for the related resources as its primary data.\n(See [Fetching Relationships](https://jsonapi.org/format/1.0/#fetching-relationships).)"
           },
           "related": {
             "title": "Related",
@@ -2536,7 +2536,7 @@
             "description": "A related resource link"
           }
         },
-        "description": "A resource object **MAY** contain references to other resource objects (\"relationships\").\nRelationships may be to-one or to-many.\nRelationships can be specified by including a member in a resource's links object."
+        "description": "A [related resource link](https://jsonapi.org/format/1.0/#document-resource-object-related-resource-links). "
       },
       "Relationships": {
         "title": "Relationships",
@@ -2596,7 +2596,7 @@
                 "$ref": "#/components/schemas/Relationships"
               }
             ],
-            "description": "Relationships object describing relationships between the resource and other JSON API resources."
+            "description": "[Relationships object](https://jsonapi.org/format/1.0/#document-resource-object-relationships)\ndescribing relationships between the resource and other JSON API resources."
           }
         },
         "description": "Resource objects appear in a JSON API document to represent resources."
@@ -2646,12 +2646,12 @@
                 "$ref": "#/components/schemas/ResponseMetaQuery"
               }
             ],
-            "description": "information on the query that was requested"
+            "description": "Information on the Query that was requested"
           },
           "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."
           },
           "time_stamp": {
             "title": "Time Stamp",

optimade/models/baseinfo.py

@@ -74,7 +74,7 @@ class BaseInfoAttributes(BaseModel):
         default=False,
         description="If true, this is an index meta-database base URL (see section Index Meta-Database). "
         "If this member is not provided, the client MUST assume this is not an index meta-database base URL "
-        "(i.e., the default is for `is_index` to be false).",
+        "(i.e., the default is for `is_index` to be `false`).",
     )
 
     @validator("entry_types_by_format", check_fields=False)

optimade/models/entries.py

@@ -150,14 +150,12 @@ class EntryInfoProperty(BaseModel):
 
     type: Optional[DataType] = Field(
         None,
-        description="""String.
-The type of the property's value.
+        description="""The type of the property's value.
 
 This MUST be any of the types defined in the Data types section.
 For the purpose of compatibility with future versions of this specification, a client MUST accept values that are not `string` values specifying any of the OPTIMADE Data types, but MUST then also disregard the `type` field.
 Note, if the value is a nested type, only the outermost type should be reported.
-E.g., for the entry resource `structures`, the `species` property is defined as a list of dictionaries, hence its `type` value would be `list`.
-Data type of value. Must equal a valid OPTIMADE data type as listed and defined under 'Data types'.""",
+E.g., for the entry resource `structures`, the `species` property is defined as a list of dictionaries, hence its `type` value would be `list`.""",
     )
 
 
@@ -167,7 +165,7 @@ class EntryInfoResource(BaseModel):
         ..., description="List of output formats available for this type of entry."
     )
 
-    description: str = Field(..., description="Description of the entry")
+    description: str = Field(..., description="Description of the entry.")
 
     properties: Dict[str, EntryInfoProperty] = Field(
         ...,

optimade/models/index_metadb.py

@@ -28,9 +28,7 @@ class IndexInfoAttributes(BaseInfoAttributes):
     is_index: bool = Field(
         default=True,
         const=True,
-        description="If true, this is an index meta-database base URL (see section Index Meta-Database). "
-        "If this member is not provided, the client MUST assume this is not an index meta-database base URL "
-        "(i.e., the default is for `is_index` to be false).",
+        description="This must be `true` since this is an index meta-database (see section Index Meta-Database).",
     )
 
 
@@ -45,7 +43,7 @@ class IndexRelationship(BaseModel):
 
     data: Union[None, RelatedLinksResource] = Field(
         ...,
-        description="""JSON API resource linkage.
+        description="""[JSON API resource linkage](http://jsonapi.org/format/1.0/#document-links).
 It MUST be either `null` or contain a single Links identifier object with the fields `id` and `type`""",
     )
 
@@ -56,6 +54,6 @@ class IndexInfoResource(BaseInfoResource):
     attributes: IndexInfoAttributes = Field(...)
     relationships: Union[None, Dict[DefaultRelationship, IndexRelationship]] = Field(
         ...,
-        description="""Reference to the child identifier object under the `links` endpoint that the provider has chosen as their 'default' OPTIMADE API database.
+        description="""Reference to the Links identifier object under the `links` endpoint that the provider has chosen as their 'default' OPTIMADE API database.
 A client SHOULD present this database as the first choice when an end-user chooses this provider.""",
     )

optimade/models/jsonapi.py

@@ -137,13 +137,15 @@ class BaseResource(BaseModel):
 
 
 class RelationshipLinks(BaseModel):
-    """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.
+    """A [related resource link](https://jsonapi.org/format/1.0/#document-resource-object-related-resource-links). """
 
-    """
-
-    self: Optional[Union[AnyUrl, Link]] = Field(None, description="A link to itself")
+    self: Optional[Union[AnyUrl, Link]] = Field(
+        None,
+        description="""A link for the relationship itself (a 'relationship link').
+This link allows the client to directly manipulate the relationship.
+When fetched successfully, this link returns the [linkage](https://jsonapi.org/format/1.0/#document-resource-object-linkage) for the related resources as its primary data.
+(See [Fetching Relationships](https://jsonapi.org/format/1.0/#fetching-relationships).)""",
+    )
     related: Optional[Union[AnyUrl, Link]] = Field(
         None, description="A related resource link"
     )
@@ -255,7 +257,8 @@ class Resource(BaseResource):
     )
     relationships: Optional[Relationships] = Field(
         None,
-        description="Relationships object describing relationships between the resource and other JSON API resources.",
+        description="""[Relationships object](https://jsonapi.org/format/1.0/#document-resource-object-relationships)
+describing relationships between the resource and other JSON API resources.""",
     )
 
 

optimade/models/links.py

@@ -59,7 +59,7 @@ class LinksResourceAttributes(Attributes):
 
     link_type: LinkType = Field(
         ...,
-        description="""The link type of the represented resource in relation to this implementation.
+        description="""The type of the linked relation.
 MUST be one of these values: 'child', 'root', 'external', 'providers'.""",
     )
 
@@ -95,7 +95,7 @@ class LinksResource(EntryResource):
 
     attributes: LinksResourceAttributes = Field(
         ...,
-        description="A dictionary containing key-value pairs representing the entry's properties.",
+        description="A dictionary containing key-value pairs representing the Links resource's properties.",
     )
 
     @root_validator(pre=True)

optimade/models/optimade_json.py

@@ -233,12 +233,11 @@ class ResponseMeta(jsonapi.Meta):
     """
 
     query: ResponseMetaQuery = Field(
-        ..., description="information on the query that was requested"
+        ..., description="Information on the Query that was requested"
     )
 
     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.",
     )
 
     time_stamp: datetime = Field(