From d24c3d98cc66f11e08287f070bb38bf73bf348c5 Mon Sep 17 00:00:00 2001 From: Paul Millar Date: Wed, 24 Apr 2024 11:10:25 +0200 Subject: [PATCH] Update PublishedData OpenAPI descriptions Motivation: Many of the fields exposed by the PublishedData endpoint currently have rather limited descriptions, with poorly defined semantics. Modification: Semantics of some fields were understood by examining how they are currently used both when minting a DOI and when building OAI-PMH records. The OpenAPI descriptions are updated following this understanding, by including the corresponding terms and including MarkDown links that point to the definition. (Note: the links point to DataCite metadata v4.5 descriptions because it is with this version that the schema documentation was available as HTML.) An example DOI is added to the description of the `doi` field, to remove any ambiguity on how the DOI is represented. The description of the `pidArray` field is updated to remove ambiguity resulting from "pid" (meaning "persistent identifier") being an overloaded term. Result: The PublishedData endpoint semantics are now better described. Closes: #1175 --- .../schemas/published-data.schema.ts | 50 +++++++++++++++---- 1 file changed, 41 insertions(+), 9 deletions(-) diff --git a/src/published-data/schemas/published-data.schema.ts b/src/published-data/schemas/published-data.schema.ts index bb68c3c88..d9e73a30c 100644 --- a/src/published-data/schemas/published-data.schema.ts +++ b/src/published-data/schemas/published-data.schema.ts @@ -27,7 +27,12 @@ export class PublishedData { }) _id: string; - @ApiProperty({ type: String, description: "Digital Object Identifier" }) + @ApiProperty({ + type: String, + description: + "Digital Object Identifier; e.g.," + + ' "10.xxx/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d".', + }) @Prop({ type: String, unique: true, @@ -47,7 +52,9 @@ export class PublishedData { @ApiProperty({ type: String, required: false, - description: "Creator Affiliation", + description: + "Creator Affiliation. This field has the semantics of" + + " [DataCite Creator/affiliation](https://datacite-metadata-schema.readthedocs.io/en/4.5/properties/creator/#affiliation).", }) @Prop({ type: String, required: false }) affiliation: string; @@ -55,7 +62,10 @@ export class PublishedData { @ApiProperty({ type: [String], required: true, - description: "Creator of dataset/dataset collection", + description: + "Creator of dataset/dataset collection. This field has the semantics" + + " of Dublin Core [dcmi:creator](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/creator/)" + + " and [DataCite Creator/creatorName](https://datacite-metadata-schema.readthedocs.io/en/4.5/properties/creator/#creatorname).", }) @Prop({ type: [String], required: true }) creator: string[]; @@ -63,7 +73,10 @@ export class PublishedData { @ApiProperty({ type: String, required: true, - description: "Dataset publisher", + description: + "Dataset publisher. This field has the semantics of Dublin Core" + + " [dcmi:publisher](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/publisher/)" + + " and [DataCite publisher](https://datacite-metadata-schema.readthedocs.io/en/4.5/properties/publisher).", }) @Prop({ type: String, required: true }) publisher: string; @@ -71,12 +84,22 @@ export class PublishedData { @ApiProperty({ type: Number, required: true, - description: "Year of publication ", + description: + "Year of publication. This field has the semantics of Dublin Core" + + " [dcmi:date](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/date/)" + + " and [DataCite publicationYear](https://datacite-metadata-schema.readthedocs.io/en/4.5/properties/publicationyear/).", }) @Prop({ type: Number, required: true }) publicationYear: number; - @ApiProperty({ type: String, required: true, description: "Title" }) + @ApiProperty({ + type: String, + required: true, + description: + "The title of the data. This field has the semantics of Dublin Core" + + " [dcmi:title](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/title/)" + + " and [DataCite title](https://datacite-metadata-schema.readthedocs.io/en/4.5/properties/title/).", + }) @Prop({ type: String, required: true }) title: string; @@ -91,7 +114,10 @@ export class PublishedData { @ApiProperty({ type: String, required: true, - description: "Abstract text for published datasets", + description: + "Abstract text for published datasets. This field has the semantics" + + " of [DataCite description](https://datacite-metadata-schema.readthedocs.io/en/4.5/properties/description/)" + + " with [Abstract descriptionType](https://datacite-metadata-schema.readthedocs.io/en/4.5/appendices/appendix-1/descriptionType/#abstract).", }) @Prop({ type: String, required: true }) abstract: string; @@ -99,7 +125,11 @@ export class PublishedData { @ApiProperty({ type: String, required: true, - description: "Link to description of how to re-use data", + description: + "Link to description of how to re-use data. This field has the" + + " semantics of Dublic Core [dcmi:description](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/description/)" + + " and [DataCite description](https://datacite-metadata-schema.readthedocs.io/en/4.5/properties/description/)" + + " with [Abstract descriptionType](https://datacite-metadata-schema.readthedocs.io/en/4.5/appendices/appendix-1/descriptionType/#abstract).", }) @Prop({ type: String, required: true }) dataDescription: string; @@ -131,7 +161,9 @@ export class PublishedData { @ApiProperty({ type: [String], required: true, - description: "Array of one or more PIDS which make up the published data", + description: + "Array of one or more Dataset persistent identifier (pid) values that" + + " make up the published data.", }) @Prop({ type: [String], required: true }) pidArray: string[];