Inconsistency between the response and the schema definition

Jira Development Jira Cloud
,
1

Hello there,

I am currently using Jira REST API endpoints to query various information from the Jira Cloud, such as retrieving a list of issues through issue search, obtaining issue details by ID, and extracting comments. Currently, I am utilizing version 2 of the API; however, it has been recommended that I upgrade to the latest version 3 due to breaking changes in the issue search functionality, which now utilizes a new endpoint with JQL.

While attempting to adjust my implementation based on the schema definitions provided in the Jira documentation, I have encountered inconsistencies between the response received from version 3 and the defined schema. Although I have not conducted an exhaustive examination to identify all discrepancies, I seek confirmation from the Jira team regarding whether the schema outlined in their documentation aligns with the responses returned by version 3. This confirmation is crucial as it presents a potential blocker for upgrading to the latest version.

For instance, the new search endpoint describes one of the properties, ‘comments,’ as a collection of comments. I was referencing the get issue endpoint, which also includes a collection of comments. However, when using these endpoints with version 3, I receive a differing schema or model where ‘comment’ is not a collection.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-jql-post
and
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get

What I get is this (masked)
“comment”: {
“comments”: ,
“self”: “masked”,
“maxResults”: 0,
“total”: 0,
“startAt”: 0
},

2

Hello @PeterJoseph

I cannot replicate that issue.

The v3 versions of the Search for issues using JQL enhanced search and the Get Issue endpoints return identical results as their v2 counterparts (except for the body of rich text fields being rendered in ADF, of course).

Both of those v3 endpoints will return a fields object that contains a comment object that contains a comments object that contains an array (a collection) of all the comments… IF the appropriate request parameters have been set correctly.

Here’s a hint why your comments object is coming back empty for that particular Issue:
“total”: 0

3

@sunnyape, thanks for looking into it.

I can reproduce this problem from my end on my project which is hosted in the cloud and it comes as a comment with as a single object and moreover if you look at my actual response (json) provided, and what you have mentioned, total: 0
I dont think the v3 has total in the spec

Is there any settings or project needs to be migrated to latest version in order to get these changes on the API ?

Try on an older project (project which was created couple of years back) with v3 route and can you see the results?

4

Nothing that I know of. AFAIK, comments are comments are comments and have been so since the day Jira Cloud was released.

I get the same results no matter how old the Project is or the age of the Issues within it. If an Issue has no Comments, then the value of the total object is 0 and the comments object is an empty array, exactly as you’ve shown in your example and exactly as expected.

POST: https://{{Instance}}/rest/api/3/search/jql
Request body:

{
   "jql": "key = BPT-226", <-- An issue initially created 5 years ago, with no Comments
   "fields": ["comment"]
}

Response body:

{
    "issues": [
        {
            "expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
            "id": "10294",
            "self": "https://solidinterface.atlassian.net/rest/api/3/issue/10294",
            "key": "BPT-226",
            "fields": {
                "comment": {
                    "comments": [], <-- Empty array because the Issue has zero comments
                    "self": "https://solidinterface.atlassian.net/rest/api/3/issue/10294/comment",
                    "maxResults": 0,
                    "total": 0, <-- Confirmation there are zero comments in this Issue
                    "startAt": 0
                }
            }
        }
    ]
}

If I add two Comments to that Issue and execute the same request, the response changes and the value of the total object is 2 and the comments object contains the array of two comments, exactly as expected:

{
    "issues": [
        {
            "expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
            "id": "10294",
            "self": "https://solidinterface.atlassian.net/rest/api/3/issue/10294",
            "key": "BPT-226",
            "fields": {
                "comment": {
                    "comments": [
                        {
                            "self": "https://solidinterface.atlassian.net/rest/api/3/issue/10294/comment/10237",
                            "id": "10237",
                            "author": {
                                "self": "https://solidinterface.atlassian.net/rest/api/3/user?accountId=557058%3A943a10c8-0495-4019-93b0-45cf469445fb",
                                "accountId": "557058:943a10c8-0495-4019-93b0-45cf469445fb",
                                "emailAddress": "sunnyape@gmail.com",
                                "displayName": "David Bakkers",
                                "active": true,
                                "timeZone": "Australia/Sydney",
                                "accountType": "atlassian"
                            },
                            "body": {
                                "type": "doc",
                                "version": 1,
                                "content": [
                                    {
                                        "type": "paragraph",
                                        "content": [
                                            {
                                                "type": "text",
                                                "text": "Comment #1"
                                            }
                                        ]
                                    }
                                ]
                            },
                            "updateAuthor": {
                                "self": "https://solidinterface.atlassian.net/rest/api/3/user?accountId=557058%3A943a10c8-0495-4019-93b0-45cf469445fb",
                                "accountId": "557058:943a10c8-0495-4019-93b0-45cf469445fb",
                                "emailAddress": "sunnyape@gmail.com",
                                },
                                "displayName": "David Bakkers",
                                "active": true,
                                "timeZone": "Australia/Sydney",
                                "accountType": "atlassian"
                            },
                            "created": "2025-03-03T16:19:00.240+1100",
                            "updated": "2025-03-03T16:19:00.240+1100",
                            "jsdPublic": true
                        },
                        {
                            "self": "https://solidinterface.atlassian.net/rest/api/3/issue/10294/comment/10238",
                            "id": "10238",
                            "author": {
                                "self": "https://solidinterface.atlassian.net/rest/api/3/user?accountId=557058%3A943a10c8-0495-4019-93b0-45cf469445fb",
                                "accountId": "557058:943a10c8-0495-4019-93b0-45cf469445fb",
                                "emailAddress": "sunnyape@gmail.com",
                                "displayName": "David Bakkers",
                                "active": true,
                                "timeZone": "Australia/Sydney",
                                "accountType": "atlassian"
                            },
                            "body": {
                                "type": "doc",
                                "version": 1,
                                "content": [
                                    {
                                        "type": "paragraph",
                                        "content": [
                                            {
                                                "type": "text",
                                                "text": "Comment #2"
                                            }
                                        ]
                                    }
                                ]
                            },
                            "updateAuthor": {
                                "self": "https://solidinterface.atlassian.net/rest/api/3/user?accountId=557058%3A943a10c8-0495-4019-93b0-45cf469445fb",
                                "accountId": "557058:943a10c8-0495-4019-93b0-45cf469445fb",
                                "emailAddress": "sunnyape@gmail.com",
                                "displayName": "David Bakkers",
                                "active": true,
                                "timeZone": "Australia/Sydney",
                                "accountType": "atlassian"
                            },
                            "created": "2025-03-03T16:19:07.214+1100",
                            "updated": "2025-03-03T16:19:07.214+1100",
                            "jsdPublic": true
                        }
                    ],
                    "self": "https://solidinterface.atlassian.net/rest/api/3/issue/10294/comment",
                    "maxResults": 2,
                    "total": 2,
                    "startAt": 0
                }
            }
        }
    ]
}

I recommend that you have a peer double-check your work and, if you can both replicate the same issue, I suggest you open a support request.

Have fun

5

This is exactly what I am referring, and below is the extract from the Jira API docs for GET ISSUE endpoint. Can you please have a look in that 200 response content and check the “comment” property.
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get

Problem1 - comment is directly an array item, but what you have shared is an object of type “comment” and within that, there is array of comments, that is an internal property to the parent comment. (“comment”: )
Problem2 - you have these fields
“maxResults”: 0,
“total”: 0, ← Confirmation there are zero comments in this Issue
startAt": 0
But, these fields are not part of the new schema, (check below, which is an extract from the Jira API docs).

So question is, should I expect the below schema jira api document or should I expect what you have shared (which is what is the actual now and referring to as a bug)

Extract from the API doc - response of GET Issue endpoint (200 code)
“comment”: [
{
“author”: {
“accountId”: “5b10a2844c20165700ede21g”,
“active”: false,
“displayName”: “Mia Krystof”,
“self”: “”
},
“body”: {
“type”: “doc”,
“version”: 1,
“content”: [
{
“type”: “paragraph”,
“content”: [
{
“type”: “text”,
“text”: “Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.”
}
]
}
]
},
“created”: “2021-01-17T12:34:00.000+0000”,
“id”: “10000”,
“self”: “”,
“updateAuthor”: {
“accountId”: “5b10a2844c20165700ede21g”,
“active”: false,
“displayName”: “Mia Krystof”,
“self”: “”
},
“updated”: “2021-01-18T23:45:00.000+0000”,
“visibility”: {
“identifier”: “Administrators”,
“type”: “role”,
“value”: “Administrators”
}
}
],

6

Ok, now I understand what you are saying. Whenever you use the word “schema” you are referring to the “example response” and that the example response shown in the documentation for both the v2 and v3 versions of those two endpoints doesn’t match the actual response you are getting from those endpoints.

In that case, yes, you have found a mistake in the example responses provided in the documentation for those endpoints, and the actual response you are getting is what you should ‘expect’ as being correct, in this case.

The problem probably originated back in August last year, when RFC-61 advised of the new Issue search endpoints and that a maximum of 20 Comments would be returned per Issue for those and other endpoints, and to get more Comments for any Issue, you’d need to use the new Get Comments endpoint per Issue. Looks like nobody ever updated the response examples in the documentation to match those changes.

Look through these Bugs in JAC for Jira Cloud that match ‘rest api comment’ and see if somebody else has logged that documentation Bug already. If not, you are welcome to log it yourself.

7

Thanks for confirming @sunnyape

1 Like
8

After checking the code of one of our apps that accesses the comments, I can say that the format of the comments in an issue hasn’t changed in several years. I guess the example responses in the documentation have been incorrect for quiet some time.

1 Like
9

Thanks @t-bundt,

Is there a way I can get the latest swagger or openapi spec for these endpoints or is it the examples I need to refer?
I am looking for the schema or the contract of these endpoints.

Much appreciated for the responses @t-bundt & @sunnyape

10

You can download the most recent Swagger file from the REST API documentation Intro page. In the top right of the page, click the ‘OpenAPI’ logo to get it. Given that the documentation is generated from that Swagger file, it’s almost guaranteed to contain the exact same mistake… but you’re welcome to spend your time validating that.

Also, if you look at the response schema in the documentation, it doesn’t go to that depth of detail anyhow. For the fields object, all it says is that there are ‘Additional Properties’ that can be returned:

Responses
issues array<IssueBean>

  • fields object
    – Additional Properties any

It doesn’t provide the entire schema for every single possible field, such as the comment field.

11

If they are the same then there is no value in it.
Btw, you are right the documentation has changed which is not at all helpful. The old one was better and clear with more details.
I dont think I will have time to validate everything but recommend to have some contract tests added so that these will be automatically picked up :slight_smile: