It might be pertinent to write a type example or the potential types list.

tbh, I don't know the answers to these questions

what are the possible values for this provider_type (I've not checked the code for this) ? If its a limited list of possible values, give them, otherwise tell how valid values can be guessed.

It isn't a limited list for now, we have at the moment only one provider_type deposit_client, but the metadata provider entity should be used in the following future cases:

• when listing: lister type
• when loading: loader type
• when fetching metadata from registries: registry type

Because it is not implemented, I'm not sure if we should list the types above in the docs

add a complete and valid example of arguments (or give a clue on where such a usage example can be found in the code)

Here is the actual metadata_provider in the storage today

with the use cases I mentioned we could add:

Also, there should somewhere a description of what this metadata object stands for. I guess it is the metadata describing the metadata provider (which might be source of confusion; which metadata are we talking about in there?)

You are right ! we do not use at the moment the metadata property for a metadata_provider, this property was added for registries where we want to keep more information about the registry itself.

@vlorentz you can add the existing hal deposit_client example as is
The rest isn't documented, we had a couple of emails on swh-devel, but we might need specs on this subject.

For a larger discussion:
@douardda where would you put specs on future features?
For the deposit, we used the \docs\specs for it, maybe wiki pages are more appropriate.