Requirements:
- CKAN 2.10+
- jsonschema>=4.25.0,<5.0.0
Installation:
pip install ckanext-resource-docs
Add to ckan.plugins:
resource_docs
Configuration:
Include documentation in resource API response (default: false)
WARNING: Can impact performance and response size
ckanext.resource_docs.append_docs_to_resource_api = true
API field name for documentation (default: resource_docs)
WARNING: Ensure schema doesn’t use same field name
ckanext.resource_docs.api_field_name = documentation
Display documentation in resource view page (default: false)
ckanext.resource_docs.show_view = true
IResourceDocs Interface:
Implement to prepopulate documentation from resource metadata:
import json
import ckan.plugins as p
import ckan.logic as tk
from ckanext.resource_docs.interfaces import IResourceDocs
class YourPlugin(p.SingletonPlugin):
p.implements(IResourceDocs, inherit=True)
def prepopulate_resource_docs(self, resource: dict[str, Any]) -> str:
"""Provide initial documentation using DataStore Data Dictionary."""
try:
result = tk.get_action("datastore_info")(
{"user": tk.current_user.name if tk.current_user else ""},
{"id": resource["id"]}
)
except (tk.ValidationError, tk.ObjectNotFound):
return ""
return json.dumps(result["fields"])
Features:
- Flexible data dictionary for any resource (not just Datastore)
- JSON Schema Draft 2020-12 validation support
- Optional automatic API inclusion
- Customizable field names
- View page display option
- Prepopulation interface for automation
Example API response (with append_docs_to_resource_api = true):
{
“id”: “resource-id-123”,
“name”: “my-resource.csv”,
“format”: “CSV”,
“resource_docs”: {
“documentation”: “This dataset contains…”,
“fields”: [
{
“name”: “column1”,
“description”: “Description of column1”,
“type”: “string”
}
]
}
}
JSON Schema Validation:
- Define validation schema per resource
- Uses JSON Schema Draft 2020-12 specification
- Optional enforcement of structure/constraints
- Flexible while maintaining data quality
Development:
git clone https://github.com/DataShades/ckanext-resource-docs.git
cd ckanext-resource-docs
pip install -e .
Testing: pytest –ckan-ini=test.ini