Skip to content

Instantly share code, notes, and snippets.

Created Aug 21, 2012
What would you like to do?
Basic Orientation to CKAN (for developers)

Basic Orientation to CKAN (for developers)

Some of the most important layers in the CKAN code architecture, going from lowest-level up to highest-level:


CKAN uses SQLAlchemy ( to handle communication between CKAN source code and the PostgreSQL database (


The ckan/model/ package corresponds to the model in the Model-View-Controller concept ( and contains classes for each of the entities stored in CKAN's database, e.g. ckan/model/ contains a Package class that represents CKAN data packages, and contains the SQLAlchemy code for mapping between Package objects in the CKAN source code and their corresponding table in the database.

A note about packages, these are now called 'datasets' in the CKAN interface, but in the source code you'll still find many places where they're referred to as packages, package and dataset they mean the same thing.


ckan/lib/dictization/ contains functions that transform CKAN model objects such as Packages, Resources, etc. into dictionaries and vice-versa. The templates that render the CKAN web interface and the JSON format used by the CKAN API both work with these dictionary representations.


ckan/logic/ contains all the functions that the WUI, API and CLI use for accessing and manipulating the data stored in CKAN. Whenever you want to get, create, update or delete some object from CKAN's model you use some function from the ckan/logic/action/ package, for example there are functions package_show(), package_create(), package_update() and package_delete() for working with packages.

All communication with the model should be done in the logic layer, and not in higher-level layers such as the controllers, which should use the logic layer instead of accessing the model themselves.


The logic action functions use schema defined in ckan/logic/ to validate data that is posted to CKAN by users via the WUI, API or CLI. The schema in turn draw on validation and conversion functions defined in ckan/logic/ and ckan/logic/


The logic action functions use the authorization functions in ckan/logic/auth/ to decide whether a user is authorized to call an action function.


The CKAN API v3 ('the action API') is the newest, most complete and best-documented of the CKAN API versions and the version we intend to support going forwards. Docs for the v3 API are here:

The API is implemented so that as soon as function such as package_update() is added to the ckan/logic/action/ package, this function can be called from the API by posting a JSON dict (and optionally an Authorization header containing a CKAN API key) to a URL that is automatically generated from the functions name, such as /api/action/package_update. The docstrings from these ckan/logic/action/ functions are also automatically exported into the Action API documentation page as well. The idea is that we want to expose as much of CKAN's functionality as possible through the API and not just from the command-line and web user interfaces (see for some interesting discussion about APIs).


CKAN's Web User Interface is implemented by the controller classes in ckan/controllers/. These classes call functions from ckan/logic/action/ to manipulate data, and return rendered template files from ckan/templates/. ckan/config/ contains the routing definitions that control which requests get sent to which controller classes according to which URL was requested (it uses

Currently CKAN templates use the Genshi template engine ( but the upcoming CKAN 2.0 release will move to the much nicer and friendlier Jinja2 by default ( Genshi will still be supported so that existing CKAN themes don't break.


CKAN has a Command Line Interface that you can use to do lots of actions such as managing datasets and users, etc. (Do paster --plugin=ckan from the ckan dir to see what's available.) It's implemented using Paste Script:


CKAN contains a number of plugin interfaces that CKAN plugins can use to hook into CKAN and add or alter behaviour. For example, the IAuthFunctions plugin interface allows plugins to override CKAN's authorization functions. The different extension interfaces are documented here: This stuff is implemented in ckan/plugins/, for example you'll find all the plugin interfaces defined in ckan/plugins/, and ckan/plugins/ defines the 'plugin toolkit', a collection of useful helper functions etc. for plugins to use.

We have several CKAN plugins for adding various functionality, e.g. commenting on datasets using disqus (, sharing pages on social networking sites (, and Google Analytics integration (

Some core CKAN features are actually implemented as plugins, you can find these in ckanext in the CKAN git repo:

Further Reading

CKAN Coding Standards: covers how we use git, our Python, JavaScript, HTML and CSS coding standards, etc.

Release cycle:

How we do i18n:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment