Data package implementation


It is not clear how to implement the element of Data Packages.

  • A can be included in but it is not referenced in datapackage.json.
  • There is a data package description property that appears to be defined similarly to the

So are the and the data package description two ways of achieving the same thing?

If not, what different content is placed in each?

Presenting readme content on a platform

Platforms that support data packages may offer to download:

  • a datapackage.json file
  • a
  • or both

If only a datapackage.json file is offered, then the content can be lost.

One solution is to embedded the content in the datapackage.json. This is done in but strangely the property is called readme, and not description.

What should be done?

I think clear guidance is needed on the difference between and the data package description property.

I think implementations should ensure that data package consumers get all the information available. Hence, if a datapackage.json is the only download offered, then the must be converted to a data package property.

What is not clear is:

  • what property should the readme content be written to - description or the non-standard readme?
  • what if a description property already has content?


@Stephen in we’re embedding file when processing data packages and store it under readme property for various reasons, e.g., we don’t want to overwrite publisher provided description property.

There is some information about having here :

Additional files such as a README, scripts (for processing or analyzing the data) and other material may be provided. By convention scripts go in a scripts directory and thus, a more elaborate data package could look like this:

datapackage.json  # (required) metadata and schemas for this data package         # (optional) README in markdown format

# data files may go either in data subdirectory or in main directory

# the directory for code scripts - again these can go in the base directory

Here is the example:

Why have file rather than inlined description or readme property? I think it is more convenient, especially when you have long text so you want to keep your metadata minimal. In my understanding, description property is something for short description, whereas is the opposite.


@anuveyatsu has done a great job explaining a nice approach.

To summarize:

  • provides a convenient way to edit this info (outside of json). When transporting we often inline onto the datapackage.json as readme property
  • description: a description (usually a paragraph or so). Often, in my own practice I don’t fill in the description and just generate it from the first paragraph of the README. But if you don’t have a README you can use this instead.