[ckan-dev] IDatasetForm: form_to_db_schema_api_create() etc

[Sean Hammond]

> The IDatasetForm plugin interface has a method:
> 
>     def form_to_db_schema(self):
>         '''Return the schema for mapping dataset dicts from form to db.
> 
>         CKAN will use the returned schema to validate and convert data coming
>         from users (via the dataset form) before entering that data into the
>         database.
> 
>         ...
> 
> But what really happens is:
> 
> - If creating or updating a dataset using the web interface,
>   form_to_db_schema() is called
> - If creating a dataset using the API form_to_db_schema_api_create()
>   is called instead
> - If updating a dataset using the API form_to_db_schema_api_update()
>   is called instead
> 
> This only happens if your IDatasetForm plugin inherits from
> DefaultDatasetForm, if it doesn't then form_to_db_schema() is called in
> all three cases.
> 
> This logic (selecting when to call form_to_db_schema(),
> form_to_db_schema_api_update() or form_to_db_schema_api_create()) seems
> like it probably belongs in CKAN's logic functions not in a
> form_to_db_schema_options() method in DefaultDatasetForm.
> 
> We need to either document form_to_db_schema_options(), _api_create()
> and _api_update() in IDatasetForm, or we need to get rid of the whole
> lot and just call form_to_db_schema() always.
> 
> (There's also db_to_form_schema_options() which is also missing from
> IDatasetForm.)
> 
> Do we really want to support using different schemas for different
> purposes - web UI vs API, create vs update? It seems that in most cases
> people will want and expect the same schema always. I'm not sure what
> the use-case for this is.
> 
> If I'm not mistaken this seems to be the commit that added this feature
> (but that doesn't shed much light on things):
> 
> https://github.com/okfn/ckan/commit/6f743b636001f6f78f40b0dc9a53cffdd972c851

It seems the point of form_to_db_schema_options() is to enable different
schemas to be used for different purposes, by calling different methods
form_to_db_schema(), _api_create(), api_update(), etc. But the thing is,
form_to_db_schema() is already a function! So if an IDatasetForm plugin
(including DefaultDatasetForm) want to have some logic about using
different schemas it can just put the logic in form_to_db_schema(). Then
the IDatasetForm interface is simple: always calls form_to_db_schema(),
we can get rid of form_to_db_schema_options().

The only problem is that form_to_db_schema_options()'s params would have
to be passed to form_to_db_schema() instead, which would break any
existing IDatasetForm plugins whose form_to_db_schema() methods do not
accept params.

If we're gonna break backward-compatibility here 2.0 seems like the time
to do it, anyone with an IDatasetForm plugin is already gonna have to
rewrite all their template customizations anyway.

By the way, why the hack are form_to_db_schema_options' params passed to
it wrapped in a dict!?