From b2d2271e50f896ffc056ea753ae991614f4c4729 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20Guti=C3=A9rrez?= Date: Wed, 9 Jan 2019 16:08:08 +0100 Subject: [PATCH] added comment documentation on DDO related classes #79 --- src/ddo/AdditionalInformation.ts | 25 +++++- src/ddo/Curation.ts | 23 +++++- src/ddo/DDO.ts | 38 +++++++-- src/ddo/MetaData.ts | 9 +-- src/ddo/MetaDataBase.ts | 135 ++++++++++++++++++++++++++++--- 5 files changed, 206 insertions(+), 24 deletions(-) diff --git a/src/ddo/AdditionalInformation.ts b/src/ddo/AdditionalInformation.ts index 54d2111..c4878eb 100644 --- a/src/ddo/AdditionalInformation.ts +++ b/src/ddo/AdditionalInformation.ts @@ -1,7 +1,24 @@ import StructuredMarkup from "./StructuredMarkup" +/** + * Additional Information of Assets Metadata. + * @see https://github.com/oceanprotocol/OEPs/tree/master/8#additional-information + */ export default class AdditionalInformation { + /** + * An indication of update latency - i.e. How often are updates expected (seldom, + * annually, quarterly, etc.), or is the resource static that is never expected + * to get updated. + * @type {string} + * @example "yearly" + */ public updateFrecuency: string = "yearly" + + /** + * A link to machine-readable structured markup (such as ttl/json-ld/rdf) + * describing the dataset. + * @type {StructuredMarkup[]} + */ public structuredMarkup: StructuredMarkup[] = [ { uri: "http://skos.um.es/unescothes/C01194/jsonld", @@ -10,7 +27,13 @@ export default class AdditionalInformation { { uri: "http://skos.um.es/unescothes/C01194/turtle", mediaType: "text/turtle", - }as StructuredMarkup, + } as StructuredMarkup, ] + + /** + * Checksum of attributes to be able to compare if there are changes in + * the asset that you are purchasing. + * @type {string} + */ public checksum: string } diff --git a/src/ddo/Curation.ts b/src/ddo/Curation.ts index bc40e86..95e0cc0 100644 --- a/src/ddo/Curation.ts +++ b/src/ddo/Curation.ts @@ -1,5 +1,26 @@ +/** + * Curation attributes of Assets Metadata. + * @see https://github.com/oceanprotocol/OEPs/tree/master/8#curation-attributes + */ export default class Curation { + /** + * Decimal value between 0 and 1. 0 is the default value. + * @type {number} + * @example 0.93 + */ public rating: number = 0.93 + + /** + * Number of votes. 0 is the default value. + * @type {number} + * @example 123 + */ public numVotes: number = 123 - public schema: string = "Binary Votting" + + /** + * Schema applied to calculate the rating. + * @type {number} + * @example "Binary Votting" + */ + public schema?: string = "Binary Votting" } diff --git a/src/ddo/DDO.ts b/src/ddo/DDO.ts index 49b447f..94825b1 100644 --- a/src/ddo/DDO.ts +++ b/src/ddo/DDO.ts @@ -2,12 +2,26 @@ import Authentication from "./Authentication" import PublicKey from "./PublicKey" import Service from "./Service" +/** + * DID Descriptor Object. + * Contains all the data related to an asset. + */ export default class DDO { + /** + * Serializes the DDO object. + * @param {DDO} DDO to be serialized. + * @return {string} DDO serialized. + */ public static serialize(ddo: DDO): string { return JSON.stringify(ddo, null, 2) } + /** + * Deserializes the DDO object. + * @param {DDO} DDO to be deserialized. + * @return {string} DDO deserialized. + */ public static deserialize(ddoString: string): DDO { const ddo = JSON.parse(ddoString) @@ -15,6 +29,10 @@ export default class DDO { } public "@context": string = "https://w3id.org/future-method/v1" + /** + * DID, descentralized ID. + * @type {string} + */ public id: string public publicKey: PublicKey[] public authentication: Authentication[] @@ -26,14 +44,18 @@ export default class DDO { authentication?: Authentication[], service?: Service[], }) { - this.authentication = ddo ? ddo.authentication ? ddo.authentication : [] : [] - this.id = ddo ? ddo.id ? ddo.id : null : null - this.publicKey = ddo ? ddo.publicKey ? ddo.publicKey : [] : [] - this.service = ddo ? ddo.service ? ddo.service : [] : [] + this.authentication = (ddo && ddo.authentication) || [] + this.id = (ddo && ddo.id) || null + this.publicKey = (ddo && ddo.publicKey) || [] + this.service = (ddo && ddo.service) || [] } + /** + * Finds a service of a DDO by ID. + * @param {string} serviceDefinitionId Service ID. + * @return {Service} Service. + */ public findServiceById(serviceDefinitionId: string): Service { - if (!serviceDefinitionId) { throw new Error("serviceDefinitionId not set") } @@ -43,8 +65,12 @@ export default class DDO { return service } + /** + * Finds a service of a DDO by type. + * @param {string} serviceType Service type. + * @return {Service} Service. + */ public findServiceByType(serviceType: string): Service { - if (!serviceType) { throw new Error("serviceType not set") } diff --git a/src/ddo/MetaData.ts b/src/ddo/MetaData.ts index 1a5c01a..5d89388 100644 --- a/src/ddo/MetaData.ts +++ b/src/ddo/MetaData.ts @@ -58,11 +58,8 @@ export default class MetaData { public curation: Curation constructor(metaData?: MetaData) { - this.additionalInformation = metaData ? - metaData.additionalInformation ? metaData.additionalInformation : - additionalInformation : additionalInformation - this.base = metaData ? metaData.base ? metaData.base : base : base - this.curation = metaData ? metaData.curation ? metaData.curation : curation : curation + this.additionalInformation = (metaData && metaData.additionalInformation) || additionalInformation + this.base = (metaData && metaData.base) || base + this.curation = (metaData && metaData.curation) || curation } - } diff --git a/src/ddo/MetaDataBase.ts b/src/ddo/MetaDataBase.ts index 1c5d98f..a20aad6 100644 --- a/src/ddo/MetaDataBase.ts +++ b/src/ddo/MetaDataBase.ts @@ -1,21 +1,116 @@ +/** + * Base attributes of Assets Metadata. + * @see https://github.com/oceanprotocol/OEPs/tree/master/8#base-attributes + */ export default class MetaDataBase { + + /** + * Descriptive name of the Asset. + * @type {string} + * @example "UK Weather information 2011" + */ public name: string = "UK Weather information 2011" - public type: string = "dataset" - public description: string = "Weather information of UK including temperature and humidity" - public size: string = "3.1gb" + + /** + * Type of the Asset. Helps to filter by the type of asset, + * initially ("dataset", "algorithm", "container", "workflow", "other"). + * @type {string} + * @example "dataset" + */ + public type: "dataset" | "algorithm" | "container" | "workflow" | "other" = "dataset" + + /** + * Details of what the resource is. For a dataset, this attribute + * explains what the data represents and what it can be used for. + * @type {string} + * @example "Weather information of UK including temperature and humidity" + */ + public description?: string = "Weather information of UK including temperature and humidity" + + /** + * The date on which the asset was created or was added. + * @type {string} + * @example "2012-10-10T17:00:000Z" + */ public dateCreated: string = "2012-10-10T17:00:000Z" + + /** + * Size of the asset (e.g. 18MB). In the absence of a unit (MB, kB etc.), kB will be assumed. + * @type {string} + * @example "3.1gb" + */ + public size: string = "3.1gb" + + /** + * Name of the entity generating this data (e.g. Tfl, Disney Corp, etc.). + * @type {string} + * @example "Met Office" + */ public author: string = "Met Office" + + /** + * Short name referencing the license of the asset (e.g. Public Domain, CC-0, CC-BY, No License Specified, etc. ). + * If it's not specified, the following value will be added: "No License Specified". + * @type {string} + * @example "CC-BY" + */ public license: string = "CC-BY" - public copyrightHolder: string = "Met Office" - public encoding: string = "UTF-8" - public compression: string = "zip" + + /** + * The party holding the legal copyright. Empty by default. + * @type {string} + * @example "Met Office" + */ + public copyrightHolder?: string = "Met Office" + + /** + * File encoding. + * @type {string} + * @example "UTF-8" + */ + public encoding?: string = "UTF-8" + + /** + * File compression (e.g. no, gzip, bzip2, etc). + * @type {string} + * @example "zip" + */ + public compression?: string = "zip" + + /** + * File format, if applicable. + * @type {string} + * @example "text/csv" + */ public contentType: string = "text/csv" - public workExample: string = "423432fsd,51.509865,-0.118092,2011-01-01T10:55:11+00:00,7.2,68" + + /** + * Example of the concept of this asset. This example is part + * of the metadata, not an external link. + * @type {string} + * @example "423432fsd,51.509865,-0.118092,2011-01-01T10:55:11+00:00,7.2,68" + */ + public workExample?: string = "423432fsd,51.509865,-0.118092,2011-01-01T10:55:11+00:00,7.2,68" + + /** + * List of content URLs resolving the Asset files. + * @type {string | string[]} + * @example "https://testocnfiles.blob.core.windows.net/testfiles/testzkp.zip" + */ public contentUrls: string | string[] = [ "https://testocnfiles.blob.core.windows.net/testfiles/testzkp.zip", "https://testocnfiles.blob.core.windows.net/testfiles/testzkp.zip", ] - public links: any[] = [ + + /** + * Mapping of links for data samples, or links to find out more information. + * Links may be to either a URL or another Asset. We expect marketplaces to + * converge on agreements of typical formats for linked data: The Ocean Protocol + * itself does not mandate any specific formats as these requirements are likely + * to be domain-specific. + * @type {any[]} + */ + public links?: any[] = [ { sample1: "http://data.ceda.ac.uk/badc/ukcp09/data/gridded-land-obs/gridded-land-obs-daily/", }, @@ -26,7 +121,27 @@ export default class MetaDataBase { fieldsDescription: "http://data.ceda.ac.uk/badc/ukcp09/", }, ] - public inLanguage: string = "en" - public tags: string = "weather, uk, 2011, temperature, humidity" + + /** + * The language of the content. Please use one of the language + * codes from the {@link https://tools.ietf.org/html/bcp47 IETF BCP 47 standard}. + * @type {String} + * @example "en" + */ + public inLanguage?: string = "en" + + /** + * Keywords or tags used to describe this content. Multiple entries in a keyword + * list are typically delimited by commas. Empty by default. + * @type {String} + * @example "weather, uk, 2011, temperature, humidity" + */ + public tags?: string = "weather, uk, 2011, temperature, humidity" + + /** + * Price of the asset. + * @type {String} + * @example 10 + */ public price: number = 10 }