From 7f7c01a036f49e74ddd981521b781f9ca8810315 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Wed, 24 Jun 2020 14:51:14 +0100 Subject: [PATCH] Changes from code review Co-authored-by: Casper Welzel Andersen --- openapi/index_openapi.json | 20 ++++++++++---------- openapi/openapi.json | 22 +++++++++++----------- optimade/models/baseinfo.py | 2 +- optimade/models/entries.py | 8 +++----- optimade/models/index_metadb.py | 8 +++----- optimade/models/jsonapi.py | 17 ++++++++++------- optimade/models/links.py | 4 ++-- optimade/models/optimade_json.py | 5 ++--- 8 files changed, 42 insertions(+), 44 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index ba994602ad..7b3b16dbff 100644 --- a/openapi/index_openapi.json +++ b/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", diff --git a/openapi/openapi.json b/openapi/openapi.json index 7e075876f8..4f0c5a4274 100644 --- a/openapi/openapi.json +++ b/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", diff --git a/optimade/models/baseinfo.py b/optimade/models/baseinfo.py index a7c17ab57d..2b45737ccd 100644 --- a/optimade/models/baseinfo.py +++ b/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) diff --git a/optimade/models/entries.py b/optimade/models/entries.py index dd7e59b4aa..43c946cae6 100644 --- a/optimade/models/entries.py +++ b/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( ..., diff --git a/optimade/models/index_metadb.py b/optimade/models/index_metadb.py index 26b366f859..4d6d1b9c66 100644 --- a/optimade/models/index_metadb.py +++ b/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.""", ) diff --git a/optimade/models/jsonapi.py b/optimade/models/jsonapi.py index 080a26b2dc..6b787b615a 100644 --- a/optimade/models/jsonapi.py +++ b/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.""", ) diff --git a/optimade/models/links.py b/optimade/models/links.py index 0f7a0a224a..437a2151d3 100644 --- a/optimade/models/links.py +++ b/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) diff --git a/optimade/models/optimade_json.py b/optimade/models/optimade_json.py index 4fd092a6cd..5c7b8a183f 100644 --- a/optimade/models/optimade_json.py +++ b/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(