From c9bf468111302ec1da576406bc82c3740109fc35 Mon Sep 17 00:00:00 2001 From: Jesper Friis Date: Fri, 16 Feb 2024 00:47:01 +0100 Subject: [PATCH 1/4] Added additional descriptive fields to ResourceConfig --- oteapi/models/genericconfig.py | 1 + oteapi/models/resourceconfig.py | 77 +++++++++++++++++++++++++++++---- 2 files changed, 70 insertions(+), 8 deletions(-) diff --git a/oteapi/models/genericconfig.py b/oteapi/models/genericconfig.py index 7954d97e3..ca27d86f5 100644 --- a/oteapi/models/genericconfig.py +++ b/oteapi/models/genericconfig.py @@ -238,6 +238,7 @@ class GenericConfig(BaseModel): "be given as key/value-pairs or set as attributes.", ) + # Consider to rename to modelDescription description: str = Field( __doc__, description="A description of the configuration model.", diff --git a/oteapi/models/resourceconfig.py b/oteapi/models/resourceconfig.py index 805cf4cb1..310a05314 100644 --- a/oteapi/models/resourceconfig.py +++ b/oteapi/models/resourceconfig.py @@ -1,6 +1,6 @@ """Pydantic Resource Configuration Data Model.""" -from typing import Annotated, Optional +from typing import Annotated, List, Optional from pydantic import Field, model_validator from pydantic.networks import Url, UrlConstraints @@ -26,7 +26,8 @@ class ResourceConfig(GenericConfig, SecretConfig): "Definition: The URL of the downloadable file in a given format. E.g. CSV " "file or RDF file.\n\nUsage: `downloadURL` *SHOULD* be used for the URL at" " which this distribution is available directly, typically through a HTTPS" - " GET request or SFTP." + " GET request or SFTP.\n\n" + "Ref: cdat:downloadURL" ), ) mediaType: Optional[str] = Field( @@ -36,7 +37,8 @@ class ResourceConfig(GenericConfig, SecretConfig): "[[IANA-MEDIA-TYPES](https://www.w3.org/TR/vocab-dcat-2/#bib-iana-media-types)]" ".\n\nUsage: This property *SHOULD* be used when the media" " type of the distribution is defined in IANA " - "[[IANA-MEDIA-TYPES](https://www.w3.org/TR/vocab-dcat-2/#bib-iana-media-types)]." + "[[IANA-MEDIA-TYPES](https://www.w3.org/TR/vocab-dcat-2/#bib-iana-media-types)].\n\n" + "Ref: dcat:mediaType" ), ) accessUrl: Optional[HostlessAnyUrl] = Field( @@ -47,30 +49,89 @@ class ResourceConfig(GenericConfig, SecretConfig): "`accessURL` *SHOULD* be used for the URL of a service or location that " "can provide access to this distribution, typically through a Web form, " "query or API call.\n`downloadURL` is preferred for direct links to " - "downloadable resources." + "downloadable resources.\n\n" + "Ref: dcat:accessURL" ), ) accessService: Optional[str] = Field( None, description=( - "A data service that gives access to the distribution of the dataset." + "A data service that gives access to the distribution of the " + "dataset.\n\n" + "Usage: SHOULD be used to link to a description of a " + "dcat:DataService that can provide access to this distribution.\n\n" + "Ref: dcat:accessService" ), ) license: Optional[str] = Field( None, description=( - "A legal document under which the distribution is made available." + "A legal document under which the distribution is made " + "available.\n\n" + "Usage: Information about licenses and rights MAY be provided " + "for the Resource. See also guidance at [9. License and rights " + "statements](https://www.w3.org/TR/vocab-dcat-3/#license-rights)." + "\n\nRef: dcterms:license" ), ) accessRights: Optional[str] = Field( None, description=( - "A rights statement that concerns how the distribution is accessed." + "Information about who can access the resource or an indication " + "of its security status.\n\n" + "Usage: Information about licenses and rights MAY be provided " + "for the Resource. See also guidance at [9. License and rights " + "statements](https://www.w3.org/TR/vocab-dcat-3/#license-rights)." + "\n\nRef:dcterms:accessRights" ), ) publisher: Optional[str] = Field( None, - description="The entity responsible for making the resource/item available.", + description=( + "The entity responsible for making the resource/item " + "available.\n\n" + "Usage: Resources of type " + "[foaf:Agent](http://xmlns.com/foaf/0.1/Agent) are recommended as " + "values for this property.\n\n" + "Ref: dcterms:publisher" + ), + ) + title: Optional[str] = Field( + None, + description="A name given to the resource.\n\nRef: dcterms:title", + ) + # + # For now `description` is commented out to avoid name conflice + # `GenericConfig.description`. Consider to rename + # `GenericConfig.description` to `GenericConfig.modelDescription`. + # + # description: Optional[str] = Field( + # None, + # description=( + # "A free-text account of the resource.\n\nRef: dcterms:description" + # ), + # ) + keyword: Optional[List[str]] = Field( + None, + description=( + "A keyword or tag describing the resource.\n\n" + "Note: Keywords are useful for making the resource easier " + "searchable.\n\n" + "Ref: dcat:keyword" + ), + ) + conformsTo: Optional[str] = Field( + None, + description=( + "An established standard to which the distribution " + "conforms.\n\n" + "Usage: This property SHOULD be used to indicate the model, " + "schema, ontology, view or profile that this representation " + "of a dataset conforms to.\n" + "This is (generally) a complementary concern to the media-type " + "or format.\n\n" + "Ref: dcterms:conformsTo" + ), ) @model_validator(mode="after") From d6809e17d851e095e37f39e6ffcc169b690e2673 Mon Sep 17 00:00:00 2001 From: Jesper Friis Date: Fri, 16 Feb 2024 07:30:42 +0100 Subject: [PATCH 2/4] Added examples to the resource config fields. --- oteapi/models/resourceconfig.py | 98 +++++++++++++++++++++++---------- 1 file changed, 70 insertions(+), 28 deletions(-) diff --git a/oteapi/models/resourceconfig.py b/oteapi/models/resourceconfig.py index 310a05314..c634b2c2d 100644 --- a/oteapi/models/resourceconfig.py +++ b/oteapi/models/resourceconfig.py @@ -23,34 +23,43 @@ class ResourceConfig(GenericConfig, SecretConfig): downloadUrl: Optional[HostlessAnyUrl] = Field( None, description=( - "Definition: The URL of the downloadable file in a given format. E.g. CSV " - "file or RDF file.\n\nUsage: `downloadURL` *SHOULD* be used for the URL at" - " which this distribution is available directly, typically through a HTTPS" - " GET request or SFTP.\n\n" - "Ref: cdat:downloadURL" + "The URL of the downloadable file in a given format. E.g. CSV " + "file or RDF file.\n\n" + "Usage: `downloadURL` *SHOULD* be used for the URL at which this " + "distribution is available directly, typically through a HTTPS " + "GET request or SFTP.\n\n" + "Range: Resource\n\n" + "Example: http://dcat.example.org/files/001.csv\n\n" + "Reference: cdat:downloadURL" ), ) mediaType: Optional[str] = Field( None, description=( "The media type of the distribution as defined by IANA " - "[[IANA-MEDIA-TYPES](https://www.w3.org/TR/vocab-dcat-2/#bib-iana-media-types)]" - ".\n\nUsage: This property *SHOULD* be used when the media" + "[[IANA-MEDIA-TYPES](https://www.w3.org/TR/vocab-dcat-2/#bib-iana-media-types)]\n\n" + ".Usage: This property *SHOULD* be used when the media" " type of the distribution is defined in IANA " "[[IANA-MEDIA-TYPES](https://www.w3.org/TR/vocab-dcat-2/#bib-iana-media-types)].\n\n" - "Ref: dcat:mediaType" + "Example: text/csv\n\n" + "Note: In a data catalog should the full IRI be used, i.e. " + "`http://www.iana.org/assignments/media-types/` should be " + "pre-pended to the value in this field." + "Reference: dcat:mediaType" ), ) accessUrl: Optional[HostlessAnyUrl] = Field( None, description=( "A URL of the resource that gives access to a distribution of " - "the dataset. E.g. landing page, feed, SPARQL endpoint.\n\nUsage: " - "`accessURL` *SHOULD* be used for the URL of a service or location that " - "can provide access to this distribution, typically through a Web form, " - "query or API call.\n`downloadURL` is preferred for direct links to " - "downloadable resources.\n\n" - "Ref: dcat:accessURL" + "the dataset. E.g. landing page, feed, SPARQL endpoint.\n\n" + "Usage: `accessURL` *SHOULD* be used for the URL of a service " + "or location that can provide access to this distribution, " + "typically through a Web form, query or API call.\n" + "`downloadURL` is preferred for direct links to downloadable " + "resources.\n\n" + "Example: http://dcat.example.org/dataset-002.html\n\n" + "Reference: dcat:accessURL" ), ) accessService: Optional[str] = Field( @@ -60,7 +69,9 @@ class ResourceConfig(GenericConfig, SecretConfig): "dataset.\n\n" "Usage: SHOULD be used to link to a description of a " "dcat:DataService that can provide access to this distribution.\n\n" - "Ref: dcat:accessService" + "Range: Resource\n\n" + "Example: http://dcat.example.org/table-service-005\n\n" + "Reference: dcat:accessService" ), ) license: Optional[str] = Field( @@ -70,8 +81,10 @@ class ResourceConfig(GenericConfig, SecretConfig): "available.\n\n" "Usage: Information about licenses and rights MAY be provided " "for the Resource. See also guidance at [9. License and rights " - "statements](https://www.w3.org/TR/vocab-dcat-3/#license-rights)." - "\n\nRef: dcterms:license" + "statements](https://www.w3.org/TR/vocab-dcat-3/#license-rights).\n\n" + "Range: URL to license document (dcterms:LicenseDocument).\n\n" + "Example: https://creativecommons.org/licenses/by/4.0/\n\n" + "Reference: dcterms:license" ), ) accessRights: Optional[str] = Field( @@ -81,8 +94,11 @@ class ResourceConfig(GenericConfig, SecretConfig): "of its security status.\n\n" "Usage: Information about licenses and rights MAY be provided " "for the Resource. See also guidance at [9. License and rights " - "statements](https://www.w3.org/TR/vocab-dcat-3/#license-rights)." - "\n\nRef:dcterms:accessRights" + "statements](https://www.w3.org/TR/vocab-dcat-3/#license-rights).\n\n" + "Range: URL to document describing the license rights " + "(dcterm:RightsStatement).\n\n" + "Example: http://publications.europa.eu/resource/authority/access-right/PUBLIC\n\n" + "Reference: dcterms:accessRights" ), ) publisher: Optional[str] = Field( @@ -91,14 +107,27 @@ class ResourceConfig(GenericConfig, SecretConfig): "The entity responsible for making the resource/item " "available.\n\n" "Usage: Resources of type " - "[foaf:Agent](http://xmlns.com/foaf/0.1/Agent) are recommended as " - "values for this property.\n\n" - "Ref: dcterms:publisher" + "[foaf:Agent](http://xmlns.com/foaf/0.1/Agent) are recommended " + "as values for this property.\n\n" + "Example: http://emmc.eu/\n\n" + "Reference: dcterms:publisher" + ), + ) + creator: Optional[str] = Field( + None, + description=( + "The entity responsible for producing the resource.\n\n" + "Usage: Resources of type foaf:Agent are recommended as values " + "for this property.\n\n" + "Note: For a researcher, this could be the orcid. For an " + "instrument, it would be an URL identifying the instrument.\n\n" + "Example: https://orcid.org/0000-0002-1560-809X\n\n" + "Reference: dcterms:creator" ), ) title: Optional[str] = Field( None, - description="A name given to the resource.\n\nRef: dcterms:title", + description="A name given to the resource.\n\nReference: dcterms:title", ) # # For now `description` is commented out to avoid name conflice @@ -108,7 +137,8 @@ class ResourceConfig(GenericConfig, SecretConfig): # description: Optional[str] = Field( # None, # description=( - # "A free-text account of the resource.\n\nRef: dcterms:description" + # "A free-text account of the resource.\n\n" + # "Reference: dcterms:description" # ), # ) keyword: Optional[List[str]] = Field( @@ -117,20 +147,32 @@ class ResourceConfig(GenericConfig, SecretConfig): "A keyword or tag describing the resource.\n\n" "Note: Keywords are useful for making the resource easier " "searchable.\n\n" - "Ref: dcat:keyword" + "Reference: dcat:keyword" ), ) conformsTo: Optional[str] = Field( None, description=( - "An established standard to which the distribution " - "conforms.\n\n" + "An established standard to which the distribution conforms.\n\n" "Usage: This property SHOULD be used to indicate the model, " "schema, ontology, view or profile that this representation " "of a dataset conforms to.\n" "This is (generally) a complementary concern to the media-type " "or format.\n\n" - "Ref: dcterms:conformsTo" + "Range: URL to the standard (dcterms:Standard).\n\n" + "Example: https://www.w3.org/TR/owl2-overview/\n\n" + "Reference: dcterms:conformsTo" + ), + ) + wasGeneratedBy: Optional[str] = Field( + None, + description=( + "Generation is the completion of production of a new entity by " + "an activity. This entity did not exist before generation and " + "becomes available for usage after this generation.\n\n" + "Range: URL referring generating activity (prov:Activity)\n\n" + "Example: http://www.ntnu.edu/temgemini/transmission-electron-microscopy\n\n" + "Reference: prov:wasGeneratedBy" ), ) From 5343cf2e030581825dfd09a6ebd349cebcaededa Mon Sep 17 00:00:00 2001 From: Jesper Friis Date: Wed, 28 Feb 2024 23:23:41 +0100 Subject: [PATCH 3/4] Update oteapi/models/resourceconfig.py --- oteapi/models/resourceconfig.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/oteapi/models/resourceconfig.py b/oteapi/models/resourceconfig.py index 7079c479d..55b54c17e 100644 --- a/oteapi/models/resourceconfig.py +++ b/oteapi/models/resourceconfig.py @@ -34,7 +34,7 @@ class ResourceConfig(GenericConfig, SecretConfig): "GET request or SFTP.\n\n" "Range: Resource\n\n" "Example: http://dcat.example.org/files/001.csv\n\n" - "Reference: cdat:downloadURL" + "Reference: dcat:downloadURL" ), ) mediaType: Optional[str] = Field( From 08e066836d83c8d9c231a59bd7b93b253eccb5d6 Mon Sep 17 00:00:00 2001 From: Jesper Friis Date: Thu, 29 Feb 2024 15:19:38 +0100 Subject: [PATCH 4/4] Added example and IRI fields --- oteapi/models/resourceconfig.py | 34 +++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/oteapi/models/resourceconfig.py b/oteapi/models/resourceconfig.py index c634b2c2d..0ef4746ee 100644 --- a/oteapi/models/resourceconfig.py +++ b/oteapi/models/resourceconfig.py @@ -29,9 +29,10 @@ class ResourceConfig(GenericConfig, SecretConfig): "distribution is available directly, typically through a HTTPS " "GET request or SFTP.\n\n" "Range: Resource\n\n" - "Example: http://dcat.example.org/files/001.csv\n\n" - "Reference: cdat:downloadURL" + "Reference: dcat:downloadURL" ), + example="http://dcat.example.org/files/001.csv", # type: ignore + IRI="http://www.w3.org/ns/dcat#downloadURL", # type: ignore ) mediaType: Optional[str] = Field( None, @@ -41,12 +42,13 @@ class ResourceConfig(GenericConfig, SecretConfig): ".Usage: This property *SHOULD* be used when the media" " type of the distribution is defined in IANA " "[[IANA-MEDIA-TYPES](https://www.w3.org/TR/vocab-dcat-2/#bib-iana-media-types)].\n\n" - "Example: text/csv\n\n" "Note: In a data catalog should the full IRI be used, i.e. " "`http://www.iana.org/assignments/media-types/` should be " "pre-pended to the value in this field." "Reference: dcat:mediaType" ), + example="text/csv", # type: ignore + IRI="http://www.w3.org/ns/dcat#mediaType", # type: ignore ) accessUrl: Optional[HostlessAnyUrl] = Field( None, @@ -58,9 +60,10 @@ class ResourceConfig(GenericConfig, SecretConfig): "typically through a Web form, query or API call.\n" "`downloadURL` is preferred for direct links to downloadable " "resources.\n\n" - "Example: http://dcat.example.org/dataset-002.html\n\n" "Reference: dcat:accessURL" ), + example="http://dcat.example.org/dataset-002.html", # type: ignore + IRI="http://www.w3.org/ns/dcat#accessURL", # type: ignore ) accessService: Optional[str] = Field( None, @@ -70,9 +73,10 @@ class ResourceConfig(GenericConfig, SecretConfig): "Usage: SHOULD be used to link to a description of a " "dcat:DataService that can provide access to this distribution.\n\n" "Range: Resource\n\n" - "Example: http://dcat.example.org/table-service-005\n\n" "Reference: dcat:accessService" ), + example="http://dcat.example.org/table-service-005", # type: ignore + IRI="http://www.w3.org/ns/dcat#accessService", # type: ignore ) license: Optional[str] = Field( None, @@ -83,9 +87,10 @@ class ResourceConfig(GenericConfig, SecretConfig): "for the Resource. See also guidance at [9. License and rights " "statements](https://www.w3.org/TR/vocab-dcat-3/#license-rights).\n\n" "Range: URL to license document (dcterms:LicenseDocument).\n\n" - "Example: https://creativecommons.org/licenses/by/4.0/\n\n" "Reference: dcterms:license" ), + example="https://creativecommons.org/licenses/by/4.0/", # type: ignore + IRI="http://purl.org/dc/terms/license", # type: ignore ) accessRights: Optional[str] = Field( None, @@ -97,9 +102,10 @@ class ResourceConfig(GenericConfig, SecretConfig): "statements](https://www.w3.org/TR/vocab-dcat-3/#license-rights).\n\n" "Range: URL to document describing the license rights " "(dcterm:RightsStatement).\n\n" - "Example: http://publications.europa.eu/resource/authority/access-right/PUBLIC\n\n" "Reference: dcterms:accessRights" ), + example="http://publications.europa.eu/resource/authority/access-right/PUBLIC", # type: ignore + IRI="http://www.w3.org/ns/dcat#accessService", # type: ignore ) publisher: Optional[str] = Field( None, @@ -109,9 +115,10 @@ class ResourceConfig(GenericConfig, SecretConfig): "Usage: Resources of type " "[foaf:Agent](http://xmlns.com/foaf/0.1/Agent) are recommended " "as values for this property.\n\n" - "Example: http://emmc.eu/\n\n" "Reference: dcterms:publisher" ), + example="http://emmc.eu/", # type: ignore + IRI="http://purl.org/dc/terms/publisher", # type: ignore ) creator: Optional[str] = Field( None, @@ -124,10 +131,13 @@ class ResourceConfig(GenericConfig, SecretConfig): "Example: https://orcid.org/0000-0002-1560-809X\n\n" "Reference: dcterms:creator" ), + example="https://orcid.org/0000-0002-1560-809X", # type: ignore + IRI="http://purl.org/dc/terms/creator", # type: ignore ) title: Optional[str] = Field( None, description="A name given to the resource.\n\nReference: dcterms:title", + IRI="http://purl.org/dc/terms/title", # type: ignore ) # # For now `description` is commented out to avoid name conflice @@ -140,6 +150,7 @@ class ResourceConfig(GenericConfig, SecretConfig): # "A free-text account of the resource.\n\n" # "Reference: dcterms:description" # ), + # IRI="http://purl.org/dc/terms/description", # type: ignore # ) keyword: Optional[List[str]] = Field( None, @@ -149,6 +160,7 @@ class ResourceConfig(GenericConfig, SecretConfig): "searchable.\n\n" "Reference: dcat:keyword" ), + IRI="http://www.w3.org/ns/dcat#keyword", # type: ignore ) conformsTo: Optional[str] = Field( None, @@ -160,9 +172,10 @@ class ResourceConfig(GenericConfig, SecretConfig): "This is (generally) a complementary concern to the media-type " "or format.\n\n" "Range: URL to the standard (dcterms:Standard).\n\n" - "Example: https://www.w3.org/TR/owl2-overview/\n\n" "Reference: dcterms:conformsTo" ), + example="https://www.w3.org/TR/owl2-overview/", # type: ignore + IRI="http://purl.org/dc/terms/conformsTo", # type: ignore ) wasGeneratedBy: Optional[str] = Field( None, @@ -171,9 +184,10 @@ class ResourceConfig(GenericConfig, SecretConfig): "an activity. This entity did not exist before generation and " "becomes available for usage after this generation.\n\n" "Range: URL referring generating activity (prov:Activity)\n\n" - "Example: http://www.ntnu.edu/temgemini/transmission-electron-microscopy\n\n" "Reference: prov:wasGeneratedBy" ), + example="http://www.ntnu.edu/temgemini/transmission-electron-microscopy", # type: ignore + IRI="http://www.w3.org/ns/prov#wasGeneratedBy", # type: ignore ) @model_validator(mode="after")