ckanext-resource-docs 0.2.1

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 allows attaching a flexible data dictionary (resource documentation) to any resource — not just those backed by the Datastore.

Each resource’s documentation can include a validation schema defined individually using JSON Schema Draft 2020-12, enabling optional enforcement of structure and constraints while maintaining the flexibility of a free-form data dictionary.

The official specification for JSON Schema Draft 2020-12 is available 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