[Schema Inaccuracy] "contents" endpoints response seem way under-specified

从 issue 中描述的 file-commit 和 content-file schema 开始，然后将它们与 PUT 和 DELETE contents endpoint 的响应进行比较。确定哪些属性始终存在，content 是否仅对 DELETE 可为 nullable，以及是否应限制 type。完成标准是 OpenAPI schema 能准确描述两种响应变体及其必需字段。

The "updating "contents" endpoints (PUT, or DELETE on /repos/{owner}/{repo}/contents/{path}, but not GET) all respond with a file-commit defined thus:

    file-commit:
      title: File Commit
      description: File Commit
      type: object
      required:
      - content
      - commit
      properties:
        content:
          type: object
          properties:
            name:
              type: string
            path:
              type: string
            sha:
              type: string
            size:
              type: integer
            url:
              type: string
            html_url:
              type: string
            git_url:
              type: string
            download_url:
              type: string
            type:
              type: string
            _links:
              type: object
              properties:
                self:
                  type: string
                git:
                  type: string
                html:
                  type: string
          nullable: true
        commit:
          type: object
          properties:
            sha:
              type: string
            node_id:
              type: string
            url:
              type: string
            html_url:
              type: string
            author:
              type: object
              properties:
                date:
                  type: string
                name:
                  type: string
                email:
                  type: string
            committer:
              type: object
              properties:
                date:
                  type: string
                name:
                  type: string
                email:
                  type: string
            message:
              type: string
            tree:
              type: object
              properties:
                url:
                  type: string
                sha:
                  type: string
            parents:
              type: array
              items:
                type: object
                properties:
                  url:
                    type: string
                  html_url:
                    type: string
                  sha:
                    type: string
            verification:
              type: object
              properties:
                verified:
                  type: boolean
                reason:
                  type: string
                signature:
                  type: string
                  nullable: true
                payload:
                  type: string
                  nullable: true

So file-commit has two required properties content and commit, with the first being nullable.

It's my understanding that content is null in the case of DELETE, in the case of PUT it's present and contains the information of the just-created file.

However I don't understand in what case all the properties of a non-null content or a commit would be missing, surely most or all properties should be required, with the possible (probable?) exception of commit.verification?

All in all, file-commit.content looks like a slightly cut down version of content-file (without encoding and content), so probably should otherwise have the same schema? And for both it seems like the type field should be an enum with file as the only option?

I think file-commit.content could be something like a file type with content-file being an allOf(file, {encoding: ..., content: ...}) but I guess that increases the complexity of the schema and currently there's a single use site for allOf so that's probably a tad too much.