Skip to content

feat: define a files metadata API - #66355

Open
leftybournes wants to merge 3 commits into
masterfrom
leftybournes/feat/files-metadata-api
Open

leftybournes wants to merge 3 commits into
masterfrom
leftybournes/feat/files-metadata-api

Conversation

@leftybournes

@leftybournes leftybournes commented Nov 5, 2026 •

Copy link
Copy Markdown
Member

Summary

This defines a metadata API that apps will be able to use to register custom metadata fields to files.

Currently, metadata fields that can be registered with the following types:

  • string
  • int/float
  • bool
  • date
  • enum (for dropdowns)

These are checked and validated. For example, int/float metadata can be in the form of a string. It will be validated and normalized into an actual int/float or throw an error if the input is invalid.

Checklist

AI (if applicable)

  • The content of this PR was partly or fully generated using AI

Signed-off-by: Kent Delante <kent@delante.me>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Kent Delante <kent@delante.me>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Kent Delante <kent@delante.me>
Assisted-by: ClaudeCode:claude-opus-5-5
@leftybournes leftybournes added this to the Nextcloud 36 milestone Nov 5, 2026
@leftybournes
leftybournes requested review from a team as code owners November 5, 2026 08:28
@leftybournes
leftybournes requested review from pabzm and removed request for a team November 5, 2026 08:28
@leftybournes leftybournes added the 3. to review Waiting for reviews label Nov 5, 2026
@leftybournes
leftybournes requested review from Altahrim, icewind1991, salmart-dev and susnux and removed request for a team November 5, 2026 08:28
*
* @since 36.0.0
*/
#[Throwable(since: '36.0.0')]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can this be thrown by apps?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I initially considered it but, after thinking about it, I think it shouldn't be as only core currently throws it. I'll remove the attribute.

Comment on lines +61 to +73
public function canRead(string $key, Node $node, ?IUser $user): bool;

/**
* Whether the user may change the value of the field on the node, as decided by the app owning the field.
* Returns false for unknown fields.
* When injected into an app, the app is detected and passed on to the owning app.
*
* @param string $key the key of the metadata field
* @param Node $node the node to which the metadata key applies
* @param IUser|null $user null for unauthenticated access, e.g. public shares
* @since 36.0.0
*/
public function canEdit(string $key, Node $node, ?IUser $user): bool;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both should ideally directly use the Actor API

@artonge artonge left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you clarify what the changes are adding compared to the current files metadata API?

I think those changes might contain some logic duplication.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a duplicate of:

public const TYPE_STRING = 'string';
/** @since 28.0.0 */
public const TYPE_INT = 'int';
/** @since 28.0.0 */
public const TYPE_FLOAT = 'float';
/** @since 28.0.0 */
public const TYPE_BOOL = 'bool';
/** @since 28.0.0 */
public const TYPE_ARRAY = 'array';
/** @since 28.0.0 */
public const TYPE_STRING_LIST = 'string[]';
/** @since 28.0.0 */
public const TYPE_INT_LIST = 'int[]';
/** @since 28.0.0 */
public const EDIT_FORBIDDEN = 0;
/** @since 28.0.0 */
public const EDIT_REQ_OWNERSHIP = 1;
/** @since 28.0.0 */
public const EDIT_REQ_WRITE_PERMISSION = 2;
/** @since 28.0.0 */
public const EDIT_REQ_READ_PERMISSION = 3;

Comment on lines +83 to +101
private function checkAccess(string $key, Node $node, ?IUser $user, bool $edit): bool {
$field = $this->registry->getFields()[$key] ?? null;
$provider = $this->registry->getProvider($key);
if ($field === null || $provider === null) {
return false;
}

try {
return $edit
? $provider->canEdit($field, $node, $user, $this->appId)
: $provider->canRead($field, $node, $user, $this->appId);
} catch (Throwable $e) {
$this->logger->error('Failed to check access to metadata field "' . $key . '"', [
'app' => $field->getApp(),
'exception' => $e,
]);
return false;
}
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

private function getMetadataFileAccessRight(Node $node, string $userId): int {
if ($node->getOwner()?->getUID() === $userId) {
return IMetadataValueWrapper::EDIT_REQ_OWNERSHIP;
} else {
$filePermissions = $node->getSharePermissions($userId);
if ($filePermissions & Constants::PERMISSION_UPDATE) {
return IMetadataValueWrapper::EDIT_REQ_WRITE_PERMISSION;
}
}
return IMetadataValueWrapper::EDIT_REQ_READ_PERMISSION;
}

#[\Override]
public function canEdit(string $key, Node $node, ?IUser $user): bool {
return $this->checkAccess($key, $node, $user, true);
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if ($knownMetadata->getEditPermission($metadataKey) < $accessRight) {
throw new FilesMetadataException('you do not have enough rights to update \'' . $metadataKey . '\' on this node');
}

@rubenvdlinde

rubenvdlinde commented Nov 10, 2026 •

Copy link
Copy Markdown

Thanks for this, it is close to something we need.

Context: with Dutch municipalities and VNG (Common Ground) we are working on records-management support in Nextcloud, so files can be kept in line with archival law on storage that enforces retention. One piece is metadata that comes from the storage backend or a records register: classification, retention status, disposal date, legal hold and provenance. Users must be able to see and search it in Files, but not change it. Displayed, not owned.

The schema and provider pattern here looks like the right place for that. Three things would make it fit, ideally as room in the API rather than extra work in this PR:

  1. Source per value. Today a field belongs to the app that registered it. For records we need to show where each value came from (the backend, a register, a user) and when. That seems close to @susnux's Actor suggestion: the actor that wrote the value.
  2. Provider-supplied values. Let a provider return values itself instead of having them copied into oc_files_metadata. A copied retention date can drift from what the storage enforces, and server code can overwrite it.
  3. Multi-value fields. A record can have more than one custodian. The existing metadata API has string[], MetadataFieldType does not.

On @artonge's question: if canEdit() feeds into the existing edit-permission check in FilesPlugin instead of running next to it, that removes the duplication and also enforces it on PROPPATCH, which we need.

Two related proposals cover the storage side: #66498 (a backend that can refuse a deletion, with a reason the user sees) and #66499 (a durable object id, so metadata and links keep pointing at the same record after a rescan or migration).

We would like to help rather than only ask. We are happy to build follow-up PRs on top of this one (WebDAV wiring and enforcement, source per value, showing the fields in the Files sidebar), with tests, and to maintain them. Would you prefer follow-ups once this lands, or PRs against your branch?

@susnux

susnux commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Can you clarify what the changes are adding compared to the current files metadata API?

The existing is quite bare metal, what we need is a way to have proper defined metadata:

  1. defined schema of it so other apps can understand it without need to know the app that created it
  2. permissions on metadata, the app creating it must be in control over who can change it
  3. later: extend it by parsing and imprinting API

Source per value

Yes that can be done with the actor, but I do not think this belongs into the metadata itself but into the audit logging.

Provider-supplied values.

Not sure what you mean, files metadata should always be stored with the API.
The files stored version of all metadata is always the source of truth.
For the example of retention date I do not see why this cannot be stored within the API.

In general there are 3 things:

  • metadata storage and definition (here)
  • metadata extraction
  • metadata imprinting

An app stores their metadata with this API for a file, that metadata then is imprinted into documents where needed using the imprinting API.
Documents added to Nextcloud can have metadata, this is extracted from the document and stored in the server metadata storage.

Multi-value fields

If there is a real use case we can add this. For this API we agreed to add a base set of types and only add new ones if there is a use case because adding types is easy, removing types means breaking API.

@rubenvdlinde

Copy link
Copy Markdown

Thanks @susnux, that clarifies the scope, and it fits what we need better than I first read.

  • Provider-supplied values: agreed, we'll drop that. Our proof of concept (archiefmeta) does what you describe: it reads the retention date and legal hold from the storage (S3 Object Lock) and stores them through the metadata API, which stays the source of truth.
  • Source per value: audit logging works for the history. What we also need is that a user sees, next to a value, where it came from (for example "storage layer, Object Lock" versus "set by an administrator"). We now store that ourselves inside the value. If the schema had an optional place for it, other apps could show it the same way, but we can live with keeping it in our own values.
  • Multi-value, the use case: a record can have several organisations responsible for it (for example the municipality and a regional archive after a merger), several classifications from different schemes, and several identifiers from different systems. The Dutch archival metadata standard (MDTO) allows repeating values for exactly these. With only single-value types we store them as one array value, which works but cannot be indexed or searched. A string[] type, matching the existing IMetadataValueWrapper::TYPE_STRING_LIST, would cover it.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants