ref is indeed meant to encode the reference/revision that was requested, while commit-hash is meant to be the resolved ref. I’ll see to clarify the wording in that respect (see proposal below).
The use of ref was inspired mainly
- by PEP 440 direct references (and pip URL references) which do not distinguish between tags and branches in their URL format
- Ruby Bundler which uses
ref - Pipfile
So it is sufficient to encode all types of direct references known today.
About submodules, this can indeed be covered later by future specs which can extend direct_url.json.
I would not rename ref to requested-revision because, like url, it is implied by the spec that it is the requested one.
The spec does not mandate any specific use of the new metadata so I suppose this part can be left out of this PEP?
commit-id is indeed more generic and covers SVN.
Tools would then need to combine the knowledge of VCS type plus the presence of commit-id to decide if the reference refers to an immutable version of the code, not just the presence of commit-hash. That is fine with me.
So I could to update the spec to replace commit-hash by resolved-commit-id and say that VCS that support hash based commit references MUST use it in that field.
Assuming the updated text above (resolved-commit-id), do you have specific use cases in mind for an additional resolved-ref field?