[Enhancement] Add support for deeply nested arrays in gh api magic fields

Describe the bug

#6614 added support for a syntax that supports adding arrays and/or nested objects, e.g.

gh api -f labels[]=bug -f labels[]=p1
#=> { "labels": ["bug", "p1"] }

gh api -f branch[name]=patch-1 -F branch[protected]=true
#=> { "branch": { "name": "patch-1", "protected": true }

You're able to set an array of objects like so,

gh api -f labels[][name]=a -f "labels[][description]=label a"

would turn into,

{
  "labels": {
    "name": "a",
    "description": "label a"
  }
}

The order of the arguments matters for adding multiple items to the same object. But if you try to set add more than one item in an array in one of these objects the gh cli messes up the parsing and no longer thinks that the next item in the array is part of the same object.

For example,

gh api -f labels[][name]=a -f "labels[][description]=label a" -f "labels[][allowedColors][]=red"

Works and adds allowedColors to the object as an array with one item, red, e.g.

{
  "labels": {
    "name": "a",
    "description": "label a",
    "allowedColors": ["red"]
  },
  {
    "allowedColors": ["blue"]
  }
}

But the following command does not add another item to the array,

gh api -f labels[][name]=a -f "labels[][description]=label a" -f "labels[][allowedColors][]=red" -f "labels[][allowedColors][]=blue"

It errors when it should result in the following JSON,

{
  "labels": {
    "name": "a",
    "description": "label a",
    "allowedColors": ["red", "blue"]
  }
}

Logs

I discovered this bug while attempting to add docs to our GitHub CLI example tab on GitHub docs. There are requests that require passing more than one item to an array, but are not able to due to this bug.

An example from docs for creating / updating custom properties for an org. In the link the GitHub CLI example is bugged, but it should be able to show the following,

# GitHub CLI api
# https://cli.github.com/manual/gh_api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /orgs/ORG/properties/schema \
   -f "properties[][property_name]=environment" -f "properties[][value_type]=single_select" -F "properties[][required]=true" -f "properties[][default_value]=production" -f "properties[][description]=Prod or dev environment" -f "properties[][allowed_values][]=production" -f "properties[][allowed_values][]=development" -f "properties[][values_editable_by]=org_actors" -f "properties[][property_name]=service" -f "properties[][value_type]=string" -f "properties[][property_name]=team" -f "properties[][value_type]=string" -f "properties[][description]=Team owning the repository"

@Ebonsignori

@Ebonsignori : thank you for opening up this issue along with the associated PR! ❤

Less a bug and more an enhancement as I don't believe the original nested fields feature added in v2.21.0 via #6614 was intended for highly complex data structures as you are describing. That said, let's see how we might be able to enhance gh api for a new use case.

Good point! My hope is that the syntax isn't too complex and that this is a useful enhancement 😁

If we do want to go forward with the new syntax, the docs are ready to be updated to accommodate it https://github.com/github/docs-internal/pull/49385

Meaning every REST endpoint in our docs will have a GitHub CLI example tab that is functionally identical to the cURL & JavaScript tabs

For what it's worth, workarounds for the custom properties issue were discussed in #8621

Also, as I'm reading your description of this issue I am confused. You say:

gh api -f labels[][name]=a -f "labels[][description]=label a"

would turn into

{
  "labels": {
    "name": "a",
    "description": "label a"
  }
}

but what I see is:

{
  "labels": [
    {
      "description": "label a",
      "name": "a"
    }
  ]
}

This might just be a typo on your side forgetting []?

And just for clarities sake, when you say regarding gh api -f 'labels[][name]=a' -f 'labels[][description]=label a' -f 'labels[][allowedColors][]=red' -f 'labels[][allowedColors][]=blue'

It errors when it should result in the following JSON

What we get is:

{
  "labels": [
    {
      "allowedColors": [
        "red"
      ],
      "description": "label a",
      "name": "a"
    },
    {
      "allowedColors": [
        "blue"
      ]
    }
  ]
}

This might just be a typo on your side forgetting []?

Yes this is exactly the case 😅

And just for clarities sake, when you say regarding gh api -f 'labels[][name]=a' -f 'labels[][description]=label a' -f 'labels[][allowedColors][]=red' -f 'labels[][allowedColors][]=blue'

It errors when it should result in the following JSON

Again correct, editing my original body to reflect the current behavior

Navigation Menu

Repository navigation

[Enhancement] Add support for deeply nested arrays in `gh api` magic fields #8761

Describe the bug

Logs

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[Enhancement] Add support for deeply nested arrays in gh api magic fields #8761

Description

Describe the bug

Logs

Activity

andyfeller commented on Feb 27, 2024

Ebonsignori commented on Feb 27, 2024

williammartin commented on Mar 1, 2024

williammartin commented on Mar 1, 2024

Ebonsignori commented on Mar 16, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[Enhancement] Add support for deeply nested arrays in `gh api` magic fields #8761