ckanext-resource-docs 0.2.0

A CKAN extension that lets you attach a flexible, schema-free data dictionary (“resource documentation”) to any resource, not just Datastore-backed ones.

A CKAN extension that lets you attach a flexible, schema-free data dictionary (resource documentation) to any resource — not just those backed by the Datastore. It supports custom fields via extensions, reuses CKAN’s existing data dictionary UI, and displays documentation directly on resource pages.

New in the latest version: you can now define a validation schema for each resource’s documentation individually, using JSON Schema Draft 2020-12. This allows you to optionally enforce structure and constraints while still keeping the flexibility of a free-form data dictionary.

You can read the official specification for JSON Schema Draft 2020-12 here.

Here is an example of a resource documentation in a format of Datastore fields. But it's not limited to that format, you can save any custom data you need.

It's also possible to define a validation schema for the resource documentation, which will be used to validate the documentation data.

• Requirements
• Installation
• Config settings
  • ckanext.resource_docs.append_docs_to_resource_api
  • ckanext.resource_docs.api_field_name
  • Example API response
• Developer installation
• Tests
• License

Requirements

Compatibility with core CKAN versions:

CKAN version	Compatible?
2.9 and earlier	no
2.10+	yes

Installation

To install ckanext-resource-docs:

1. Activate your CKAN virtual environment, for example:

   . /usr/lib/ckan/default/bin/activate
   

2. Install the extension from PyPI:

   pip install ckanext-resource-docs
   

3. Add resource_docs to the ckan.plugins setting in your CKAN config file (usually located at /etc/ckan/default/ckan.ini).

4. Restart CKAN. For example, if you've deployed CKAN with Apache on Ubuntu:

   sudo service apache2 reload
   

Config settings

The following options control how ckanext-resource-docs behaves.

ckanext.resource_docs.append_docs_to_resource_api

Type: bool

Default: false

When true, resource documentation is automatically included in the standard CKAN resource API response. This allows clients to retrieve documentation without making a separate API call.

Example:

ckanext.resource_docs.append_docs_to_resource_api = true

---

ckanext.resource_docs.api_field_name

Type: string

Default: resource_docs

Specifies the field name in the API response that will contain the resource documentation. Only applies if append_docs_to_resource_api is enabled.

Example:

ckanext.resource_docs.api_field_name = documentation

With this setting, the documentation appears under "documentation" field instead of "resource_docs".

---

Example API response

With append_docs_to_resource_api = true and the default api_field_name:

{
  "id": "resource-id-123",
  "name": "my-resource.csv",
  "url": "https://example.com/data.csv",
  "format": "CSV",
  "resource_docs": {
    "documentation": "This dataset contains...",
    "fields": [
      {
        "name": "column1",
        "description": "Description of column1",
        "type": "string"
      }
    ]
  }
}

Developer installation

To install ckanext-resource-docs for development, activate your CKAN virtualenv and do:

git clone https://github.com/DataShades/ckanext-resource-docs.git
cd ckanext-resource-docs
pip install -e .

Tests

To run the tests, do:

pytest --ckan-ini=test.ini

License

AGPL