[ckan-dev] IDatasetForm: form_to_db_schema_api_create() etc

[Sean Hammond]

> I think that we should do the following.
> 
> have a `create` and an `update` schema that is used by both the api
> and the front end it

Yeah, I agree. I thought about just having a single form_to_db_schema()
instead of create and update ones, but that seems tricky because CKAN
behaves differently when creating vs updating a dataset. It may be
possible to unify these but as a first step keeping them separate seems
easier. Notes on the current behaviour:

Create:

- You _must_ put "name" in the dict

  Name is the only required field, you can create a package with just
  {"name": "foo"}

- You _cannot_ put "id" in the dict or it'll fail

The error reporting of package_create seems wrong, if "name" is missing
from the dict it will give you two "missing value" errors, "name" and
"title", but in fact you can create the package successfully by
supplying only "name". (Supplying only "title" does not work.)

Update:

- You _must_ put _either_ "id" or "name" in the dict, this is the only
  requirement, you can do a successful noop package_update with just
  {"name": "foo"} or just {"id": "foo"}

- The meanings of id and name are different: either one of them can be
  either the package's name or its id

You can change a package's id but not its name, which when combined with
the fact that either id or name can be either the package's id or name
in the posted dict, produces some weird ways to rename a package:

Posting:

   {'name': '9f3fad27-0aba-4a50-832e-6d83066802a5'}

will find the package with id 9f3... and change its name to its id!

Posting:

   {'id': 'foo', 'name': '9f3fad27-0aba-4a50-832e-6d83066802a5'}

will find the package with name 'foo' and, again, change its name to its
id.

package_show(), on the other hand, is yet again different. You _must_
supply "id", again this can be either the package's name or its id, but
trying to supply just "name" to package_show() will fail (and with an
incorrect error message, that says you must supply a field called
"name_or_id"). You can also supply "name" but it'll be ignored (without
error), e.g:

   {'id': 'warandpeace', 'name': 'annakarenina'}

will show warandpeace not annakarenina.

> Hopefully the allow partial updates stuff done will help here - before
> the data would get stripped out of datasets if not supplied.

Partial updates do work for packages, partially :)

I can do a package_update by supplying either "id" or "name" and then
just one other field, e.g. "notes":

    {"name": "foo", "notes": "updated notes"}

and generally speaking this will only update the value of the notes
field and not affect other fields.  Except that _some_ other fields will
be affected, for example all of the package's tags and groups will be deleted
if you do this.

There's a config option, "fix_partial_updates", which is on by default,
but whether it's on or off doesn't seem to matter a partial
package_update will delete fields. (Also it's not actually possible to
turn this option off in your config file because the code that reads it
is wrong, always reads True.)

I think we may need to add the Action API to the list of things that
require a new set of functional tests. It needs to be consistent in
terms of which fields are required and which optional, what the values
of fields mean, whether or not updating just one field deletes other
fields, and it needs to give correct error messages.