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 support@datacite.org 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.

[rebeccaringuette]

I wonder if the link itself would give that information. From what I've seen, links that have a file extension on the end (e.g., .csv, .pdf, .cdf) are links to the files, while links without an extension on the end tend to not be direct links to files (e.g., links to a folder of files). For NASA Heliophysics, we have the second kind of link much more often than the first.

[amyehodge]

One thing that's come up for us in considering whether/how we might include metadata in this new property for our own DOIs, is the impact of their being MANY files. We have objects with almost 50,000 files. That's likely to cause an issue with payload size for us or you at some point, it seems like. Or just in the time it takes to generate the metadata or possibly even worse -- checking and updating it whenever a work is modified to see if, for example, a file size has changed, or a single file has been added. I don't have any suggestions or request, just suggesting that this point be considered. Thanks!

[rebeccaringuette]

I would like to see some thought given to how to support file directories on the cloud (e.g., s3), particularly when some additional information is needed to access the file (e.g., access keys / similar). Any ideas on that?

[alex-ball]

There has always been this strange inference in the DataCite metadata schema that the dataset being identified consists of a single file, or else several files that can be treated as a single file because they all have the same format/access conditions/usage rights. That does not reflect the datasets in our repository.

We warmly welcome this proposal, which would avoid the need for the ugly workarounds we are currently using:

"relatedIdentifiers": [
    {
        "relatedIdentifier": "https://url/for/filename.ext",
        "relatedIdentifierType": "URL",
        "relationType": "HasPart"
    }
],
"formats": [
  "filename.ext = mime/type"
],
"sizes": [
    "filename.ext = 196kB"
],

However, excluding rights is a missed opportunity, because we assign licences per-file not per-dataset, so even with this suggestion we would still be left with an ugly workaround:

"rightsList": [
    {
        "rights": "filename.ext is licensed under the XXX License",
        ...
    }
],

[KellyStathis]

Thanks everyone for your feedback and contributions to this Request for Comment. I’m writing with an update on the status of Distribution and a request for additional feedback.

We have an updated draft of the Distribution property available here: https://datacite-metadata-schema.readthedocs.io/en/4.8_draft/properties/distribution/ as part of the working draft of Schema 4.8.

While preparing examples to accompany the Distribution property, several important issues have surfaced in discussions with the Metadata Working Group.

First, the current design for Distribution centers around a stable direct download link, with contentURL as the main required sub-property. However, we’ve found that many repositories don’t have stable direct download links. A common pattern, for example, is to use a dynamically generated, expiring download link. This approach is implemented by Dataverse software (here’s an example: https://doi.org/10.5683/SP3/KPAQRO) among others. Expiring URLs like these wouldn’t be actionable contentURLs.

We’re also concerned that stable contentURLs might become rarer as repositories deliberately seek to prevent machine access. Many are concerned about network traffic, and with increasing strain on collections due to AI harvesting¹, the landscape has changed considerably since we first started working on Distribution four years ago.

We have a few questions to help move this forward—thanks in advance for your input! We want to make sure that Distribution is a useful addition to the DataCite Metadata Schema.

• Would your repository implement Distribution as currently designed? Why or why not?
• Distribution was designed to facilitate direct machine access to resources. From your perspective, are we still solving the right problem?
• In cases where a stable content URL isn’t available, is a human-navigable description of a resource’s components/parts useful?

Footnotes

1. See Lippincott, S., Collister, L. & Skinner, K. (2026). Sustaining the Commons in the AI Economy: A Landscape Scan of Challenges and Strategies for Bridging AI Companies and Open Curated Collections. Invest in Open Infrastructure. https://doi.org/10.5281/zenodo.19458128. ↩

[hsrzepa]

It is a concern that some repositories do not support stable contentURLs, as I understand because they use Web services and each download costs them money. This does make it difficult to support direct machine access. I can give one strong case for such access here https://www.ch.ic.ac.uk/rzepa/findingaid/ and https://www.ch.ic.ac.uk/rzepa/findingaid1/, ie machine construction of a Finding Aid based on data from a repository. Seeded with a top level collection, which references all the entries within (which can number 100s) a crawler based on stable contentURLs can autonomously harvest just that collection (and without having to access to any parochial API that can do that using unique eg access keys/tokens obtained in advance) analyse the data and produce a Finding Aid which can be used to search the entire data collection at a much finer level of granularity than that based purely on registered metadata. This can only be done by allowing machine access for all the datasets. Now that Crossref supports DOIs with type Data, our model is to cite the top level data collection DOI both in the citation list (and Crossref metadata record) and in the article "Data availability statement" (now mandatory for journals in eg the field of chemistry) and just that DOI enables e.g. a full Finding Aid to be constructed for that specific journal article. One can envisage other innovative tools akin to Finding Aids to emerge if stable contentURLs are adopted, but which would be difficult/parochial for repositories with non stable contentURLs.

So yes, our current repository and the one that will replace it shortly (based on Invenio), therefore allow stable contentURL access for exactly the purpose of enabling external tools such as a Finding Aid creator. So yes, absolutely, you are still solving the right problem! We are indeed relying on it - the Finding Aids constructed above were based on stable contentURL metadata declarations using the ORE schema, and we very much want to migrate these metadata records to the DataCite metadata record using the proposals in this RFC.

[rebeccaringuette]

Apologies if I'm behind on the conversation, but what is the use case to need this in DataCite in addition to the schema.org metadata embedded on the landing page? I am assuming that there is an external metadata structure where such information is mapped into DataCite and Schema.org, which would provide that metadata elsewhere. If there are systems where the only metadata for an item is in DataCite, then adding the links with which to access the items would absolutely be important. Otherwise, just piping that information into the schema.org metadata and showing the links on the landing page seems enough.

[KellyStathis]

@rebeccaringuette This would enable retrieval of content URLs via the DataCite REST API, without having to make an additional request to the landing page.

[uschindler]

In my opinion, the distribution property is unneeded if reporistories would better implement FAIR signposting. Basically at PANGAEA you can resolve the DOI with a HEAD request (following redirects) of course and all alternatie ditributions are announced as HTTP Link headers as decribed in Content Negotiation RFCs and FAIR Signposting.

So I am against this change. Adding another layer of distribution URLs in DataCite metadata makes it even more complicated for a consumer to find the correct link to download data or alternative metadata representations. FAIR signposting was made exactly for that use case, so a user should only need to resolve the DOI and query the repository for alternative links with standard HTTP requests. If you download the landing page, the links are also reported as HTML <link rel=.... href=...>.

So I would not like to move that to metadata. Especially as links to data or other alternative representations are often dynamic and not stable so should not be added to metadata.

[alex-ball]

I will reiterate that the thing I welcome most about this development is the ability to associate file-specific metadata (filename, byte size, media type, access level, and potentially others) with specific files. It just makes so much more sense than specifying file-specific metadata at the whole-dataset level.

The problem with the proposed implementation is that all this file-specific goodness is provided as a happy by-product of providing stable direct download URLs: the ContentURL is made primary and everything else has to hang off it. If a repository cannot or does not want to publish direct download links, they are then unable to provide any other file-specific metadata even though it would still make sense for them to do so.

To be clear, I don't think it's a valid argument that, because some repositories can't or don't want to provide stable direct download URLs, no repository should be able to, nor that because each repository could potentially implement their own technologies for providing machine-readable direct download URLs, that there's no benefit to having a simple standard way of providing them that works for everyone and doesn't involve having to visit each repository individually (and craft a specific approach).

So to answer your questions:

1. Yes, we'd use this current structure, because we happen to have file download URLs that don't normally change, so it is sustainable for us to update the DataCite record on the rare occasion that the URL does change; but the driver for us would be the ability to group information like file sizes and media types around the files being described.
2. Direct machine access is still a legitimate concern to address, but enthusiasm for it is probably waning and the current design leaves little flexibility for supporting alternative/dynamic ways of providing direct access in future.
3. A thousand times, yes; being able to describe a resource's components/parts would be a massive improvement.

In short, the structure "resource – component – download info" makes more logical and pragmatic sense than "resource – download info – other component info", so flipping the emphasis around would be a good move.

[borsna]

An additional optional property would be a typed checksum for the file content e.g:

{
  "contentUrl": "https://example.org/readme.txt",
  "byteSize": 838861,
  "mediaType": "text/plain",
  "accessType": "open",
  "contentName": "readme.txt",
  "checksum": "801a9be154c78caa032a37b4a4f0747f1e1addb397b64fa8581d749d704c12ea",
  "checksumType": "SHA256",
  "checksumTypeUri": "http://id.loc.gov/vocabulary/preservation/cryptographicHashFunctions/sha256"
}

[borsna]

Another (simple) alternative would be defining a CV for hash functions based on the most common one for data integrity.

[KellyStathis]

Hi everyone, thanks for sharing your feedback on this proposal.

We’ve heard from many in the community that the proposed implementation would make it easier both to share content URLs and describe individual files.

At the same time, this round of feedback revealed challenges with how the design anchors file-specific metadata to a required content URL. This is especially true for the XML structure, in which byteSize, mediaType, etc. were attributes of the contentURL element. This doesn’t provide flexibility to expand or adjust the structure later—for example, we wouldn’t be able to make contentURLs optional, or add sub-elements with their own attributes. Because we keep all minor version changes backward-compatible, it’s important that when we implement a new property, we start with a design that can grow to meet community use cases as they evolve.

We’re going to take this back to the DataCite Metadata WG to revise, and will share another proposal in this space for discussion. Thanks for working with us on this—more to come.