[Schema Inaccuracy] Incorrect ref parameter specification for creating or updating references

[qubitz]

Schema Inaccuracy

Update a reference and Create a reference schemas incorrectly specify the requirements of the ref parameter.

Currently it says:

The name of the fully qualified reference to update. For example, refs/heads/master. If the value doesn't start with refs and have at least two slashes, it will be rejected.

Following these perimeter requirements leads to responses of "Reference does not exist".

Expected

The description of the ref parameter should be rewritten to almost match the parameter description of Get a reference. Something along the lines of:

Must be a branch name (heads/BRANCH_NAME) or tag name (tags/TAG_NAME). For more information, see "Git References" in the Git documentation.

Reproduction Steps

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/git/refs/refs/tags/latest \
  -d '{"sha":"aa218f56b14c9653891f9e74264a383fa43fefbd","force":false}'

Notice the .../refs/refs/... above . While a human can easily avoid this duplication, it is hidden when interacting through abstractions such as:

octokit.rest.git.updateRef({
  owner: OWNER,
  repo: REPO,
  "refs/tags/latest",
  aa218f56b14c9653891f9e74264a383fa43fefbd,
  force: false
});

Happy to provide more details if necessary.