Feat (urls): Interface allowing to customize dataset, resource and organization uri

Author: sagargg

ckanext/dcat/interfaces.py

@@ -1,6 +1,74 @@
 from ckan.plugins.interfaces import Interface
 
 
+class IDCATURIGenerator(Interface):
+    '''
+    Interface for customizing URI generation in DCAT serializations
+    '''
+
+    def catalog_uri(self, default_uri):
+        '''
+        Called when generating the catalog URI for RDF serializations.
+        
+        Allows plugins to customize how the catalog URI is generated.
+
+        :param default_uri: The default catalog URI generated by the system
+        :type default_uri: string
+
+        :returns: The catalog URI to use. If None, the default will be used.
+        :rtype: string or None
+        '''
+        return default_uri
+
+    def dataset_uri(self, dataset_dict, default_uri):
+        '''
+        Called when generating the dataset URI for RDF serializations.
+        
+        Allows plugins to customize how dataset URIs are generated.
+
+        :param dataset_dict: The dataset dictionary
+        :type dataset_dict: dict
+        :param default_uri: The default dataset URI generated by the system
+        :type default_uri: string
+
+        :returns: The dataset URI to use. If None, the default will be used.
+        :rtype: string or None
+        '''
+        return default_uri
+
+    def resource_uri(self, resource_dict, default_uri):
+        '''
+        Called when generating the resource URI for RDF serializations.
+        
+        Allows plugins to customize how resource URIs are generated.
+
+        :param resource_dict: The resource dictionary
+        :type resource_dict: dict
+        :param default_uri: The default resource URI generated by the system
+        :type default_uri: string
+
+        :returns: The resource URI to use. If None, the default will be used.
+        :rtype: string or None
+        '''
+        return default_uri
+
+    def publisher_uri(self, dataset_dict, default_uri):
+        '''
+        Called when generating the publisher URI for RDF serializations.
+        
+        Allows plugins to customize how publisher URIs are generated.
+
+        :param dataset_dict: The dataset dictionary
+        :type dataset_dict: dict
+        :param default_uri: The default publisher URI generated by the system
+        :type default_uri: string
+
+        :returns: The publisher URI to use. If None, the default will be used.
+        :rtype: string or None
+        '''
+        return default_uri
+
+
 class IDCATRDFHarvester(Interface):
 
     def before_download(self, url, harvest_job):

ckanext/dcat/utils.py

@@ -13,8 +13,10 @@
 
 from ckan import model
 import ckan.plugins.toolkit as toolkit
+import ckan.plugins as plugins
 
 from ckanext.dcat.exceptions import RDFProfileException
+from ckanext.dcat.interfaces import IDCATURIGenerator
 
 from ckan.views.home import index as index_endpoint
 from ckan.views.dataset import read as read_endpoint
@@ -128,6 +130,13 @@ def catalog_uri():
                          'the `ckanext.dcat.base_uri` or `ckan.site_url` ' +
                          'option')
 
+    # Allow plugins to modify the catalog URI
+    for plugin in plugins.PluginImplementations(IDCATURIGenerator):
+        result = plugin.catalog_uri(uri)
+        if result is not None:
+            uri = result
+            break
+
     return uri
 
 
@@ -164,6 +173,13 @@ def dataset_uri(dataset_dict):
                                        str(uuid.uuid4()))
         log.warning('Using a random id for dataset URI')
 
+    # Allow plugins to modify the dataset URI
+    for plugin in plugins.PluginImplementations(IDCATURIGenerator):
+        result = plugin.dataset_uri(dataset_dict, uri)
+        if result is not None:
+            uri = result
+            break
+
     return uri
 
 
@@ -194,6 +210,13 @@ def resource_uri(resource_dict):
                                                     dataset_id,
                                                     resource_dict['id'])
 
+    # Allow plugins to modify the resource URI
+    for plugin in plugins.PluginImplementations(IDCATURIGenerator):
+        result = plugin.resource_uri(resource_dict, uri)
+        if result is not None:
+            uri = result
+            break
+
     return uri
 
 
@@ -208,11 +231,19 @@ def publisher_uri_organization_fallback(dataset_dict):
     Returns a string with the publisher URI, or None if no URI could be
     generated.
     '''
+    uri = None
     if dataset_dict.get('organization'):
-        return '{0}/organization/{1}'.format(catalog_uri().rstrip('/'),
+        uri = '{0}/organization/{1}'.format(catalog_uri().rstrip('/'),
                                             dataset_dict['organization']['id'])
 
-    return None
+    # Allow plugins to modify the publisher or organization URI
+    for plugin in plugins.PluginImplementations(IDCATURIGenerator):
+        result = plugin.publisher_uri(dataset_dict, uri)
+        if result is not None:
+            uri = result
+            break
+
+    return uri
 
 def dataset_id_from_resource(resource_dict):
     '''

docs/index.md

@@ -119,3 +119,5 @@ These are implemented internally using:
 * An [RDF Parser](writing-profiles.md#rdf-dcat-parser) that allows to read RDF serializations in different formats and extract CKAN dataset dicts, using customizable [profiles](profiles.md#profiles).
 
 * An [RDF Serializer](writing-profiles.md#rdf-dcat-serializer) that allows to transform CKAN datasets metadata to different semantic formats, also allowing customizable [profiles](profiles.md#profiles).
+
+* [URI Customization Interface](uri-customization.md) that allows plugins to customize how URIs are generated for catalogs, datasets, resources, and publishers in RDF serializations.

docs/uri-customization.md

@@ -0,0 +1,163 @@
+# URI Customization Interface
+
+The DCAT extension provides an interface (`IDCATURIGenerator`) that allows other plugins to customize how URIs are generated for RDF serializations. This is useful when you need to:
+
+- Use custom URI patterns for dataset, resources, and organizations. This is useful when you have decoupled frontend running in different domains or need to follow specific URI schemes.
+- Integrate with external authority systems
+- Use persistent identifiers like DOIs or handles etc. 
+
+## Interface Methods
+
+The `IDCATURIGenerator` interface provides four methods that can be implemented:
+
+### `catalog_uri(default_uri)`
+
+Customize the catalog URI used to identify the entire CKAN instance.
+
+**Parameters:**
+- `default_uri` (string): The default catalog URI generated by the system
+
+**Returns:**
+- `string` or `None`: The catalog URI to use, or None to use the default
+
+**Example:**
+```python
+def catalog_uri(self, default_uri):
+    custom_domain = toolkit.config.get('ckanext.my_extension.catalog_domain')
+    if custom_domain:
+        return f"https://{custom_domain}/{default_uri}"
+    return None 
+```
+
+### `dataset_uri(dataset_dict, default_uri)`
+
+Customize the dataset URI used to identify individual datasets.
+
+**Parameters:**
+- `dataset_dict` (dict): The dataset dictionary containing metadata
+- `default_uri` (string): The default dataset URI generated by the system
+
+**Returns:**
+- `string` or `None`: The dataset URI to use, or None to use the default
+
+**Example:**
+```python
+def dataset_uri(self, dataset_dict, default_uri):
+    # Use DOI if available
+    doi = dataset_dict.get('doi')
+    if doi:
+        return f"https://doi.org/{doi}"
+    return None  # Use default
+```
+
+### `resource_uri(resource_dict, default_uri)`
+
+Customize the resource URI used to identify individual resources.
+
+**Parameters:**
+- `resource_dict` (dict): The resource dictionary containing metadata
+- `default_uri` (string): The default resource URI generated by the system
+
+**Returns:**
+- `string` or `None`: The resource URI to use, or None to use the default
+
+**Example:**
+```python
+def resource_uri(self, resource_dict, default_uri):
+    # Use the actual URL for API resources
+    resource_format = resource_dict.get('format', '').lower()
+    if resource_format == 'api':
+        return resource_dict.get('url')
+    return None  # Use default
+```
+
+### `publisher_uri(dataset_dict, default_uri)`
+
+Customize the publisher URI used to identify the organization that published the dataset.
+
+**Parameters:**
+- `dataset_dict` (dict): The dataset dictionary containing metadata
+- `default_uri` (string): The default publisher URI generated by the system
+
+**Returns:**
+- `string` or `None`: The publisher URI to use, or None to use the default
+
+**Example:**
+```python
+def publisher_uri(self, dataset_dict, default_uri):
+    organization = dataset_dict.get('organization', {})
+    # Use ROR ID if available
+    ror_id = organization.get('ror_id')
+    if ror_id:
+        return f"https://ror.org/{ror_id}"
+    return None  # Use default
+```
+
+## Implementation Example
+
+Here's a complete example of a plugin that implements the `IDCATURIGenerator` interface:
+
+```python
+import ckan.plugins as plugins
+import ckan.plugins.toolkit as toolkit
+from ckanext.dcat.interfaces import IDCATURIGenerator
+
+class MyURIPlugin(plugins.SingletonPlugin):
+    plugins.implements(plugins.IConfigurer)
+    plugins.implements(IDCATURIGenerator)
+
+    # IConfigurer
+    def update_config(self, config_):
+        pass
+
+    # IDCATURIGenerator
+    def catalog_uri(self, default_uri):
+        # Add version to catalog URI
+        version = toolkit.config.get('my_extension.catalog_version', 'v1')
+        if default_uri:
+            return f"{default_uri.rstrip('/')}/{version}"
+        return None
+
+    def dataset_uri(self, dataset_dict, default_uri):
+        # Use custom identifier if available
+        custom_id = dataset_dict.get('custom_identifier')
+        if custom_id:
+            base_uri = toolkit.config.get('ckanext.dcat.base_uri')
+            return f"{base_uri}/data/{custom_id}"
+        return None
+
+    def resource_uri(self, resource_dict, default_uri):
+        # Use content hash for stable URIs
+        content_hash = resource_dict.get('content_hash')
+        if content_hash:
+            base_uri = toolkit.config.get('ckanext.dcat.base_uri')
+            return f"{base_uri}/resource/{content_hash}"
+        return None
+
+    def publisher_uri(self, dataset_dict, default_uri):
+        organization = dataset_dict.get('organization', {})
+        # Use external authority URI
+        authority_id = organization.get('authority_id')
+        if authority_id:
+            return f"https://authority.example.org/org/{authority_id}"
+        return None
+```
+
+## Configuration
+
+You can add configuration options to your plugin to make URI generation configurable:
+
+```ini
+# In your CKAN configuration file
+my_extension.catalog_version = v2
+my_extension.use_dois = true
+my_extension.authority_base_uri = https://authority.example.org
+```
+
+## Multiple Plugins
+
+If multiple plugins implement the `IDCATURIGenerator` interface, only the first plugin that returns a non-None value will be used for each URI type. Plugins are called in the order they are loaded.
+
+## Backward Compatibility
+
+This interface is completely backward compatible. Existing installations will continue to work unchanged, and the interface only affects URI generation when plugins explicitly implement it.

mkdocs.yml

@@ -78,6 +78,7 @@ nav:
     - 'harvester.md'
     - Google Dataset Search: 'google-dataset-search.md'
     - Croissant ML: 'croissant.md'
+    - URI Customization: 'uri-customization.md'
     - CLI: 'cli.md'
   - Configuration reference: 'configuration.md'
   - Contributing: 'contributing.md'