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

[xmo-odoo]

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.

[xmo-odoo]

Having taken one more look at this type, it also seems very much like the commit object is a straight git-commit, the properties are exactly the same, with "author" and "committer" being git data (triplet of name, email, and date) rather than github objects (simple-user).

The only difference is that all properties of file-commit.commit are currently non-required, but for both create/update and delete all the properties seem to be filled, so I think this is just the schema being under-specified and it should just be:

        commit:
          "$ref": "#/components/schemas/git-commit"

[ahoglund]

@xmo-odoo - Thank you for opening the issue. We've chosen to keep the file-commit.commit object and the git-commit object distinct for now in the schema although as you've pointed out they are in fact the same under-the-hood.