Document Date
=============

The Document Date feature adds a dedicated date field to Files, allowing editors to assign a meaningful date to uploaded documents. This is useful for documents like reports, meeting minutes, or official publications where the document's own date differs from the upload date. The document date can be disabled as well.

Overview
--------

Files in the CMS receive a ``document_date`` field that:

- Defaults to the current date/time when a new file is uploaded
- Can be manually set or changed by editors
- Is optional and can be cleared
- Is indexed in the catalog ``Date`` index, enabling date-based sorting and querying of files

The ``document_date`` value replaces the default ``Date`` catalog index for Files. This means that sorting files by date will use the document date rather than the publication or creation date.


REST API
--------

Reading the Document Date
^^^^^^^^^^^^^^^^^^^^^^^^^

The ``document_date`` field is included in the standard REST API response for File content.

.. code-block:: javascript

    const response = await fetch('/Plone/my-folder/annual-report.pdf', {
        headers: {
            'Accept': 'application/json'
        }
    });
    const file = await response.json();
    console.log(file.document_date);  // "2025-06-15T10:00:00"


Querying Files by Date
^^^^^^^^^^^^^^^^^^^^^^

Since ``document_date`` is indexed in the catalog ``Date`` index, files can be queried and sorted by their document date through the ``@search`` endpoint.

.. code-block:: javascript

    // Search for files sorted by document date (newest first)
    const response = await fetch(
        '/Plone/@search?portal_type=File&sort_on=Date&sort_order=descending',
        {
            headers: { 'Accept': 'application/json' }
        }
    );
    const data = await response.json();
    data.items.forEach(file => {
        console.log(file.title, file.document_date);
    });

.. code-block:: python

    import requests

    response = requests.get(
        'http://localhost:8080/Plone/@search',
        params={
            'portal_type': 'File',
            'sort_on': 'Date',
            'sort_order': 'descending',
        },
        headers={'Accept': 'application/json'}
    )
    for item in response.json()['items']:
        print(item['title'], item.get('document_date'))