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

Bắt đầu với các schema file-commit và content-file được mô tả trong issue, sau đó so sánh chúng với các response của endpoint PUT và DELETE contents. Xác định những property nào luôn xuất hiện, liệu content chỉ nullable đối với DELETE hay không, và liệu có nên giới hạn type hay không. Hoàn thành khi các schema OpenAPI mô tả chính xác cả hai biến thể response và các field bắt buộc của chúng.

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.