Request for comment: New Distribution property

[KellyStathis]

Currently, machines have no standardized way to retrieve resources identified with DataCite DOIs. When a DOI resolves to a landing page, machines need to rely on machine-readable file download information being embedded in that landing page, or other means that are inconsistent across repositories.

To address this challenge, DataCite is proposing a new Distribution property for the DataCite Metadata Schema.

Proposed new Distribution property

21. Distribution

• Obligation: Optional
• Occurrences: 0-n
• Definition: Represents a form of a resource that can be accessed or retrieved, such as downloadable files. This property can be repeated if different variations are available.
• Allowed values, examples, other constraints: The use of this property indicates directly downloadable distributions.

21.1 contentURL

• Occurrences: 1-n
• Definition: The URL leading to content provided by a repository using a valid protocol.
• Allowed values, examples, other constraints: If Distribution is used, at least one contentURL is mandatory. URLs should use schemes that are registered with IANA (e.g., https, ftp): https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml.
  • A contentURL can either represent the entirety of the distribution, or a part of it. Collections of files can be described either using a single contentURL (e.g., an archive format or a BagIt folder structure) or as multiple contentURLs.
  • Examples:
    • https://example.org/data.csv
    • ftp://example.org/data.txt
    • https://example.org/files.gzip

21.1.a byteSize

• Occurrences: 0-1
• Definition: The size of the object retrievable via the contentURL in bytes.
• Allowed values, examples, other constraints: The size in bytes can be approximated (as an integer) when the precise size is not known.
  • Example:
    • 1048576 (for 1 Megabyte)

21.1.b mediaType

• Occurrences: 0-1
• Definition: Media type of the object retrievable via the contentURL, expressed using a MIME format.
• Allowed values, examples, other constraints: MIME formats are strongly recommended: see IANA site and MDN reference.
  • Examples:
    • application/zip
    • audio/mpeg

21.1.c accessType

• Occurrences: 0-1
• Definition: A statement that describes how the object is accessed.
• Allowed values, examples, other constraints: To provide copyright or licensing information, use the Rights property. To provide an embargo date, use the Date property with dateType “Available”.
  • Controlled List Values:
    • Open
    • Embargoed
    • Restricted

21.1.d contentName

• Occurrences: 0-1
  Definition: A name given to the content at the contentURL.
• Allowed values, examples, other constraints:
  • Example:
    • readme.txt

Examples

XML

<distributions>
    <distribution>
        <contentURL byteSize="838861" mediaType="text/plain" accessType="open" contentName="readme.txt">https://example.org/readme.txt</contentURL>
        <contentURL byteSize="5242880" mediaType="application/json" accessType="open" contentName="data.json">https://example.org/data.json"</contentURL>
    </distribution>
    <distribution>
        <contentURL byteSize="6081741" mediaType="application/zip" accessType="open" contentName="package.zip">https://example.org/package.zip</contentURL>
    </distribution>
<distributions>

JSON

"distributions": [
    {
        {
	     "contentUrl":  "https://example.org/readme.txt",
	     "byteSize": 838861,
	     "mediaType": "text/plain"
	     "accessType": "open",
	     "contentName": "readme.txt"
        },
        {
	     "contentUrl": "https://example.org/data.json",
	     "byteSize": 5242880,
	     "mediaType": "application/json",
	     "accessType":  "restricted",
	     "contentName": "data.json"
        }
    },
    {
        {
	     "contentUrl":  "https://example.org/package.zip",
	     "byteSize": 6081741,
	     "mediaType": "application/zip"
	     "accessType": "open",
	     "contentName": "package.json"
        }
    }
]

Providing feedback

We are interested in your thoughts on this proposal and possibilities for improvement. Contribute your feedback by leaving a comment on this post. You are welcome to reply by answering any or all of the questions below:

• Would the change work for your use case? Why or why not?
• Is there something you would like to see implemented differently?
• Which aspects of the change would benefit from clarification, if any?

If you would like to share feedback without creating a GitHub account, you can email us at [email protected] and indicate whether you’d like us to post a comment on your behalf.

This discussion will close on 16 January 2026 (extended from 19 December 2025) , but you can still submit feedback on DataCite Suggestions.

[nichtich]

This nicely maps to DCAT class Distribution with properties

• dcat:downloadURL
• dcat:byteSize
• dcat:mediaType
• dcterms:accessRights with a controlled vocabulary (different from DCAT-AP because different use case, this may be discussed)

I'm not sure about contentName, this looks like dcterms:title in DCAT because "name" could be anything, but I assume it should be a file name, so definition of this field might need to be more precise.

[mlangseth]

I agree with @nichtich. DCAT also has a property for accessURL. Would it be important for DataCite to distinguish between contentURLs for direct downloads versus services?

This would be relatively straightforward for USGS to implement since we are moving toward storing our metadata as DCAT.

[philippconzett]

@KellyStathis Thanks for starting this discussion! Could you please elaborate on how Distribution would relate to the resourceType for dataset files I suggested some time ago (see Dataverse GitHub issue #5086 and PID Forum thread)?

[KellyStathis]

It's a really good question! The purpose of Distribution is to expose direct file links (content URLs).

When registering a DOI for an individual dataset file (or any other file), that DOI should still resolve to a landing page for the individual file. In addition, it could have a Distribution with a contentURL leading directly to the file.

We don't have a resourceTypeGeneral for "File" or similar, but if you are registering DOIs for individual files, they can be connected to datasets through relatedIdentifiers, using the relationType "IsPartOf" (and vice versa - the dataset can be linked to its file-level DOIs with "HasPart").

[philippconzett]

Thanks for clarifying, @KellyStathis! I think Dataverse already provides the relationType information. However, in DataCite/DataCite Commons dataset and file-level DOIs would all be listed at the same level, which is somewhat confusing, because it might make people think our repository has more than 100.000 dataset, but actually most of these DOIs are at file-level. Will the Distribution property enable distinguishing between datasets and files?

[KellyStathis]

Thanks @philippconzett! Do you have any ideas for how the Distribution property could be extended/adapted to enable distinguishing between datasets and files?

I was thinking we may need a different solution than Distribution for this purpose. One approach could be filtering using the relationTypes "HasPart" and "IsPartOf". However, these relationTypes are used to connect more than files, so there's a risk this would exclude too much. Another approach would be introducing a new resourceTypeGeneral (for "File" or "Component" or similar).

[philippconzett]

Thanks, @KellyStathis! I think introducing a new resourceTypeGeneral for "File" or "Component" or similar could do the job. That's basically, what I suggested back in 2018. What would be the right way to proceed with this suggestion?

[KellyStathis]

@philippconzett I'd recommend posting a new suggestion here: https://github.com/datacite/datacite-suggestions/discussions/categories/metadata-schema-suggestions so we can get more community feedback on this—thanks!

[philippconzett]

Thanks, @KellyStathis! I've submitted a suggestion.