Skip to content
This repository has been archived by the owner on Oct 28, 2024. It is now read-only.

Commit

Permalink
Clarify collection item types in Data Package (#53)
Browse files Browse the repository at this point in the history
* Clarify collection item types in Data Package

* Updated formatting
  • Loading branch information
roll authored Apr 11, 2024
1 parent b35c11b commit 62e2271
Showing 1 changed file with 25 additions and 21 deletions.
46 changes: 25 additions & 21 deletions content/docs/specifications/data-package.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,9 +150,13 @@ The license(s) under which the package is provided.
This property is not legally binding and does not guarantee the package is licensed under the terms defined in this property.
:::

`licenses` `MUST` be an array. Each item in the array is a License. Each `MUST` be an `object`. The object `MUST` contain a `name` property and/or a `path` property. It `MAY` contain a `title` property.
`licenses` `MUST` be an array. Each item in the array is a License. Each `MUST` be an `object`. The object `MUST` contain a `name` property and/or a `path` property, and it `MAY` contain a `title` property:

Here is an example:
- `name`: A string containing an [Open Definition license ID](http://licenses.opendefinition.org/)
- `path`: A [URL or Path](../glossary/#url-or-path), that is a fully qualified HTTP address, or a relative POSIX path.
- `title`: A string containing human-readable title.

An example of using the `licenses` property:

```json
"licenses": [{
Expand All @@ -162,10 +166,6 @@ Here is an example:
}]
```

- `name`: The `name` `MUST` be an [Open Definition license ID](http://licenses.opendefinition.org/)
- `path`: A [URL or Path](../glossary/#url-or-path) string, that is a fully qualified HTTP address, or a relative POSIX path.
- `title`: A human-readable title.

### `profile`

A string identifying the profile of this descriptor as per the [profiles](https://specs.frictionlessdata.io/profiles/) specification.
Expand Down Expand Up @@ -226,7 +226,17 @@ An Array of string keywords to assist users searching for the package in catalog

### `contributors`

The people or organizations who contributed to this Data Package. It `MUST` be an array. Each entry is a Contributor and `MUST` be an `object`. A Contributor `MUST` have at least one property. A Contributor is RECOMMENDED to have `title` property and MAY contain `givenName`, `familyName`, `path`, `email`, `roles`, and `organization` properties. An example of the object structure is as follows:
The people or organizations who contributed to this Data Package. It `MUST` be an array. Each entry is a Contributor and `MUST` be an `object`. A Contributor `MUST` have at least one property. A Contributor is `RECOMMENDED` to have `title` property and `MAY` contain `givenName`, `familyName`, `path`, `email`, `roles`, and `organization` properties:

- `title`: A string containing a name of the contributor.
- `givenName`: A string containing name a person has been given, if the contributor is a person.
- `familyName`: A string containing familial name that a person inherits, if the contributor is a person.
- `path`: A fully qualified URL pointing to a relevant location online for the contributor.
- `email`: A string containing an email address.
- `roles`: An array of strings describing the roles of the contributor. A role is `RECOMMENDED` to follow an established vocabulary, such as [DataCite Metadata Schema's contributorRole](https://support.datacite.org/docs/datacite-metadata-schema-v44-recommended-and-optional-properties#7a-contributortype) or [CreDIT](https://credit.niso.org/). Useful roles to indicate are: `creator`, `contact`, `rightsHolder`, and `dataCurator`.
- `organization`: A string describing the organization this contributor is affiliated to.

An example of the object structure is as follows:

```json
"contributors": [{
Expand All @@ -237,14 +247,6 @@ The people or organizations who contributed to this Data Package. It `MUST` be a
}]
```

- `title`: name of the contributor.
- `givenName`: name a person has been given, if the contributor is a person.
- `familyName`: familial name that a person inherits, if the contributor is a person.
- `path`: a fully qualified http URL pointing to a relevant location online for the contributor
- `email`: An email address
- `roles`: an array of strings describing the roles of the contributor. A role is `RECOMMENDED` to follow an established vocabulary, such as [DataCite Metadata Schema's contributorRole](https://support.datacite.org/docs/datacite-metadata-schema-v44-recommended-and-optional-properties#7a-contributortype) or [CreDIT](https://credit.niso.org/). Useful roles to indicate are: `creator`, `contact`, `rightsHolder`, and `dataCurator`.
- `organization`: a string describing the organization this contributor is affiliated to.

Use of the `creator` role does not imply that that person was the original creator of the data in the data package - merely that they created and/or maintain the data package. It is common for data packages to "package" up data from elsewhere. The original origin of the data can be indicated with the `sources` property - see above.

References:
Expand All @@ -257,16 +259,18 @@ If the `roles` property is not provided a data consumer MUST fall back to using

### `sources`

The raw sources for this data package. It `MUST` be an array of Source objects. A Source object `MUST` have at least one property. A Source object is `RECOMMENDED` to have `title` property and `MAY` have `path`, `email`, and `version` properties. Example:
The raw sources for this data package. It `MUST` be an array of Source objects. A Source object `MUST` have at least one property. A Source object is `RECOMMENDED` to have `title` property and `MAY` have `path`, `email`, and `version` properties:

- `title`: A string containing a title of the source (e.g. document or organization name).
- `path`: A [URL or Path](../glossary/#url-or-path), that is a fully qualified HTTP address, or a relative POSIX path.
- `email`: A string containing an email address.
- `version`: A string containing a version of the source.

An example of the object structure is as follows:

```json
"sources": [{
"title": "World Bank and OECD",
"path": "http://data.worldbank.org/indicator/NY.GDP.MKTP.CD"
}]
```

- `title`: title of the source (e.g. document or organization name)
- `path`: A [URL or Path](../glossary/#url-or-path) string, that is a fully qualified HTTP address, or a relative POSIX path.
- `email`: An email address
- `version`: A version of the source

0 comments on commit 62e2271

Please sign in to comment.