Update model descriptions and openapi.json for 1.0.0-rc2

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

@@ -52,125 +52,126 @@ class EntryResourceAttributes(Attributes):
 
     immutable_id: Optional[str] = Field(
         None,
-        description="""The entry's immutable ID (e.g., an UUID).
-This is important for databases having preferred IDs that point to "the latest version" of a record, but still offer access to older variants.
-This ID maps to the version-specific record, in case it changes in the future.
+        description="""The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to "the latest version" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.
+
 - **Type**: string.
-- **Requirements/Conventions**:
 
-  - **Support**: OPTIONAL, i.e., MAY be :val:`null`.
-  - **Query**: MUST be a queryable property with support for all mandatory filter features.
+- **Requirements/Conventions**:
+    - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.
+    - **Query**: MUST be a queryable property with support for all mandatory filter features.
 
 - **Examples**:
-
-  - :val:`"8bd3e750-b477-41a0-9b11-3a799f21b44f"`
-  - :val:`"fjeiwoj,54;@=%<>#32"` (Strings that are not URL-safe are allowed.)""",
+    - `"8bd3e750-b477-41a0-9b11-3a799f21b44f"`
+    - `"fjeiwoj,54;@=%<>#32"` (Strings that are not URL-safe are allowed.)""",
     )
 
     last_modified: datetime = Field(
         ...,
         description="""Date and time representing when the entry was last modified.
+
 - **Type**: timestamp.
-- **Requirements/Conventions**:
 
-  - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`.
-  - **Query**: MUST be a queryable property with support for all mandatory filter features.
-  - **Response**: REQUIRED in the response unless the query parameter :query-param:`response_fields` is present and does not include this property.
+- **Requirements/Conventions**:
+    - **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.
+    - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.
 
 - **Example**:
-
-  - As part of JSON response format: :VAL:`"2007-04-05T14:30Z"` (i.e., encoded as an `RFC 3339 Internet Date/Time Format <https://tools.ietf.org/html/rfc3339#section-5.6>`__ string.)""",
+    - As part of JSON response format: `"2007-04-05T14:30:20Z"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)""",
     )
 
 
 class EntryResource(Resource):
 
     id: str = Field(
         ...,
-        description="""An entry's ID as defined in section `Definition of Terms`_.
+        description="""An entry's ID as defined in section Definition of Terms.
+
 - **Type**: string.
-- **Requirements/Conventions**:
 
-  - **Support**: REQUIRED, MUST NOT be :val:`null`.
-  - **Query**: MUST be a queryable property with support for all mandatory filter features.
-  - **Response**: REQUIRED in the response.
-  - See section `Definition of Terms`_.
+- **Requirements/Conventions**:
+    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.
+    - **Query**: MUST be a queryable property with support for all mandatory filter features.
+    - **Response**: REQUIRED in the response.
 
 - **Examples**:
-
-  - :val:`"db/1234567"`
-  - :val:`"cod/2000000"`
-  - :val:`"cod/2000000@1234567"`
-  - :val:`"nomad/L1234567890"`
-  - :val:`"42"`""",
+    - `"db/1234567"`
+    - `"cod/2000000"`
+    - `"cod/2000000@1234567"`
+    - `"nomad/L1234567890"`
+    - `"42"`""",
     )
 
     type: str = Field(
-        ...,
         description="""The name of the type of an entry.
+
 - **Type**: string.
-- **Requirements/Conventions**:
 
-  - **Support**: REQUIRED, MUST NOT be :val:`null`.
-  - **Query**: MUST be a queryable property with support for all mandatory filter features.
-  - **Response**: REQUIRED in the response.
-  - MUST be an existing entry type.
-  - The entry of type `<type>` and ID `<id>` MUST be returned in response to a request for :endpoint:`/<type>/<id>` under the versioned base URL.
+- **Requirements/Conventions**:
+    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.
+    - **Query**: MUST be a queryable property with support for all mandatory filter features.
+    - **Response**: REQUIRED in the response.
+    - 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**: :val:`"structures"`""",
+- **Example**: `"structures"`""",
     )
 
     attributes: EntryResourceAttributes = Field(
         ...,
-        description="""a dictionary, containing key-value pairs representing the entry's properties, except for type and id.
-
-Database-provider-specific properties need to include the database-provider-specific prefix
-(see appendix `Database-Provider-Specific Namespace Prefixes`_).""",
+        description="""A dictionary, containing key-value pairs representing the entry's properties, except for `type` and `id`.
+Database-provider-specific properties need to include the database-provider-specific prefix (see section on Database-Provider-Specific Namespace Prefixes).""",
     )
 
     relationships: Optional[EntryRelationships] = Field(
         None,
-        description="""a dictionary containing references to other entries according to the description in section `Relationships`_
-encoded as `JSON API Relationships <https://jsonapi.org/format/1.0/#document-resource-object-relationships>`__.
-The OPTIONAL human-readable description of the relationship MAY be provided in the :field:`description` field inside the :field:`meta` dictionary.""",
+        description="""A dictionary containing references to other entries according to the description in section Relationships encoded as [JSON API Relationships](https://jsonapi.org/format/1.0/#document-resource-object-relationships).
+The OPTIONAL human-readable description of the relationship MAY be provided in the `description` field inside the `meta` dictionary of the JSON API resource identifier object.""",
     )
 
 
 class EntryInfoProperty(BaseModel):
 
-    description: str = Field(..., description="description of the entry property")
+    description: str = Field(
+        ..., description="A human-readable description of the entry property"
+    )
 
     unit: Optional[str] = Field(
-        None, description="the physical unit of the entry property"
+        None,
+        description="""The physical unit of the entry property.
+It is RECOMMENDED that non-standard (non-SI) units are described in the description for the property.""",
     )
 
     sortable: Optional[bool] = Field(
         None,
-        description='defines whether the entry property can be used for sorting with the "sort" parameter. '
-        "If the entry listing endpoint supports sorting, this key MUST be present for sortable properties with value `true`.",
+        description="""Defines whether the entry property can be used for sorting with the "sort" parameter.
+If the entry listing endpoint supports sorting, this key MUST be present for sortable properties with value `true`.""",
     )
 
     type: Optional[DataType] = Field(
         None,
-        description="Data 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.
+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`.""",
     )
 
 
 class EntryInfoResource(BaseModel):
 
-    formats: List[str] = Field(..., description="list of available output formats.")
+    formats: List[str] = Field(
+        ..., 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(
         ...,
-        description="a dictionary describing queryable properties for this "
-        "entry type, where each key is a property ID.",
+        description="A dictionary describing queryable properties for this entry type, where each key is a property name.",
     )
 
     output_fields_by_format: Dict[str, List[str]] = Field(
         ...,
-        description="a dictionary of available output fields for this entry "
-        "type, where the keys are the values of the `formats` list "
-        "and the values are the keys of the `properties` dictionary.",
+        description="Dictionary of available output fields for this entry type, where the keys are the values of the `formats` list and the values are the keys of the `properties` dictionary.",
     )

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,8 +43,8 @@ class IndexRelationship(BaseModel):
 
     data: Union[None, RelatedLinksResource] = Field(
         ...,
-        description="JSON API resource linkage. It 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).
+It MUST be either `null` or contain a single Links identifier object with the fields `id` and `type`""",
     )
 
 
@@ -56,8 +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. "
-        "A 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.
+A client SHOULD present this database as the first choice when an end-user chooses this provider.""",
     )

optimade/models/jsonapi.py

@@ -137,12 +137,22 @@ 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 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.
 
-    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"
+        None,
+        description="A [related resource link](https://jsonapi.org/format/1.0/#document-resource-object-related-resource-links).",
     )
 
     @root_validator(pre=True)
@@ -237,7 +247,7 @@ def check_illegal_attributes_fields(cls, values):
 
 
 class Resource(BaseResource):
-    """Resource objects appear in a JSON:API document to represent resources."""
+    """Resource objects appear in a JSON API document to represent resources."""
 
     links: Optional[ResourceLinks] = Field(
         None, description="a links object containing links related to the resource."
@@ -252,7 +262,8 @@ 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](https://jsonapi.org/format/1.0/#document-resource-object-relationships)
+describing relationships between the resource and other JSON API resources.""",
     )
 
 

optimade/models/links.py

@@ -41,13 +41,11 @@ class LinksResourceAttributes(Attributes):
 
     name: str = Field(
         ...,
-        description="Human-readable name for the OPTIMADE API implementation "
-        "a client may provide in a list to an end-user.",
+        description="Human-readable name for the OPTIMADE API implementation, e.g., for use in clients to show the name to the end-user.",
     )
     description: str = Field(
         ...,
-        description="Human-readable description for the OPTIMADE API implementation "
-        "a client may provide in a list to an end-user.",
+        description="Human-readable description for the OPTIMADE API implementation, e.g., for use in clients to show a description to the end-user.",
     )
     base_url: Union[AnyUrl, Link, None] = Field(
         ...,
@@ -61,27 +59,28 @@ class LinksResourceAttributes(Attributes):
 
     link_type: LinkType = Field(
         ...,
-        description="The link type of the represented resource in relation to this implementation. MUST be one of these values: 'child', 'root', 'external', 'providers'.",
+        description="""The type of the linked relation.
+MUST be one of these values: 'child', 'root', 'external', 'providers'.""",
     )
 
     aggregate: Optional[Aggregate] = Field(
         "ok",
         description="""A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not.
-This flag SHOULD NOT be indicated for links where :property:`link_type` is not :val:`child`.
+This flag SHOULD NOT be indicated for links where `link_type` is not `child`.
 
-If not specified, clients MAY assume that the value is :val:`ok`.
-If specified, and the value is anything different than :val:`ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).
+If not specified, clients MAY assume that the value is `ok`.
+If specified, and the value is anything different than `ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).
 
 Specific values indicate the reason why the server is providing the suggestion.
-A client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with :property:`aggregate`=:val:`test`).
+A client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with `aggregate`=`test`).
 
 If specified, it MUST be one of the values listed in section Link Aggregate Options.""",
     )
 
     no_aggregate_reason: Optional[str] = Field(
         None,
         description="""An OPTIONAL human-readable string indicating the reason for suggesting not to aggregate results following the link.
-It SHOULD NOT be present if :property:`aggregate`=:val:`ok`.""",
+It SHOULD NOT be present if `aggregate`=`ok`.""",
     )
 
 
@@ -96,8 +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)