How should file-information be returned in element and collection endpoints?

[Syndesi]

Currently individual elements as well as collections of elements return data in the following schema:

{
  "type": "Comment",
  "id": "74a8fcd9-6cb0-4b0d-8d42-0b6c3c54d1ac",
  "data": {
    "created": "2025-09-27T10:39:51+00:00",
    "name": "Blue",
    "updated": "2025-09-27T10:39:51+00:00",
    "content": "Blue is ..."
  }
}

We now have two different options to represent file data:

Option A: As data properties

{
  "type": "Comment",
  "id": "74a8fcd9-6cb0-4b0d-8d42-0b6c3c54d1ac",
  "data": {
    "created": "2025-09-27T10:39:51+00:00",
    "name": "Blue",
    "updated": "2025-09-27T10:39:51+00:00",
    "content": "Blue is ...",
    "file": {
      "contentLength": 1234,
      ...
    }
  }
}

Option B: As a new root level property

{
  "type": "Comment",
  "id": "74a8fcd9-6cb0-4b0d-8d42-0b6c3c54d1ac",
  "data": {
    "created": "2025-09-27T10:39:51+00:00",
    "name": "Blue",
    "updated": "2025-09-27T10:39:51+00:00",
    "content": "Blue is ..."
  },
  "file": {
    "contentLength": 1234,
    ...
  }
}

Acceptance criteria

• Create pro- / contra-list of both variants
• Think about side effects, e.g. Elasticsearch serialization, search, event listeners to block users from directly modifying file properties, ...
• Define the chosen variant
• Implement chosen variant

[Syndesi]

With file data being separate, I think I tend towards option B, i.e. having file as another root level property - similar to the id and type properties as well. This will also make the distinction easier, that file-properties can not be directly modified.

Regarding the content of the file-block, the following properties will likely make sense:

• extension: A string, provided by the original upload, or bin if not available. Static.
• name: A string, contains the identical content as the Content-Disposition HTTP response header - talked about in detail in Support Content-Disposition HTTP response header #447 , dynamic.
• mimetype: A string containing the detected mime type of the file, can be null if no mime type can be identified. Can not be set by the user - open for discussion / a separate issue later on.
• size: Integer, communicates the length of the file in bytes.

So a final example can be:

{
  "type": "Comment",
  "id": "74a8fcd9-6cb0-4b0d-8d42-0b6c3c54d1ac",
  "data": {
    "created": "2025-09-27T10:39:51+00:00",
    "name": "Blue",
    "updated": "2025-09-27T10:39:51+00:00",
    "content": "Blue is ..."
  },
  "file": {
    "name": "Blue.txt",
    "extension": "txt",
    "mimetype": "text/plain",
    "size": 1234
  }
}