Skip to content

Add JSON schema envelope and normalize all output fields #289

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AndreyVMarkelov merged 1 commit into from
Jun 25, 2026
Merged

Add JSON schema envelope and normalize all output fields #289

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 47 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,10 +192,13 @@ JSON error responses use stable `error.code` values:
| `unknown_flag` | Cobra could not resolve a flag. |
| `command_failed` | Fallback for failures without a more specific stable code. |

Successful JSON responses for migrated commands return an `input` object, a `results` array, and a `warnings` array. Result payloads are command-specific. For commands such as `mkdir`, each result reports what happened to the requested path:
Successful JSON responses for migrated commands return `ok: true`, `schema_version: "1"`, `command`, an `input` object, a `results` array, and a `warnings` array. Result payloads are command-specific. Public top-level schemas live under [docs/json-schema/v1](docs/json-schema/v1/). If a multi-target or recursive command fails after some side effects have already happened, dbxcli returns a JSON error envelope and does not include partial success results. For commands such as `mkdir`, each result reports what happened to the requested path:

```json
{
"ok": true,
"schema_version": "1",
"command": "mkdir",
"input": {
"path": "/new-folder",
"parents": false
Expand Down Expand Up @@ -224,9 +227,14 @@ For `cp` and `mv`, each result input object uses `from_path` and `to_path`:

```json
{
"ok": true,
"schema_version": "1",
"command": "cp",
"input": {},
"results": [
{
"status": "copied",
"kind": "file",
"input": {
"from_path": "/Reports/old.pdf",
"to_path": "/Reports/copy.pdf"
Expand All @@ -249,9 +257,14 @@ For commands such as `rm`, `input` uses command-specific path and flag fields:

```json
{
"ok": true,
"schema_version": "1",
"command": "rm",
"input": {},
"results": [
{
"status": "deleted",
"kind": "file",
"input": {
"path": "/old-file.txt",
"permanent": false,
Expand All @@ -276,6 +289,9 @@ For commands such as `rm`, `input` uses command-specific path and flag fields:

```json
{
"ok": true,
"schema_version": "1",
"command": "put",
"input": {
"source": "README.md",
"target": "/README.md",
Expand Down Expand Up @@ -311,6 +327,9 @@ Entry-list commands such as `ls`, `search`, and `revs` use the operation-style w

```json
{
"ok": true,
"schema_version": "1",
"command": "ls",
"input": {
"path": "/Reports",
"recursive": false,
Expand All @@ -324,6 +343,7 @@ Entry-list commands such as `ls`, `search`, and `revs` use the operation-style w
{
"status": "listed",
"kind": "file",
"input": {},
"result": {
"type": "file",
"path_display": "/Reports/q1.pdf",
Expand All @@ -342,9 +362,13 @@ Version, account, and usage commands use the operation-style wrapper with a sing

```json
{
"ok": true,
"schema_version": "1",
"command": "version",
"input": {},
"results": [
{
"status": "reported",
"kind": "version",
"input": {},
"result": {
Expand All @@ -360,9 +384,13 @@ Version, account, and usage commands use the operation-style wrapper with a sing

```json
{
"ok": true,
"schema_version": "1",
"command": "account",
"input": {},
"results": [
{
"status": "found",
"kind": "account",
"input": {},
"result": {
Expand All @@ -380,9 +408,13 @@ Version, account, and usage commands use the operation-style wrapper with a sing

```json
{
"ok": true,
"schema_version": "1",
"command": "du",
"input": {},
"results": [
{
"status": "reported",
"kind": "space_usage",
"input": {},
"result": {
Expand All @@ -402,13 +434,17 @@ Shared-link commands use the same operation-style wrapper. `share-link create`,

```json
{
"ok": true,
"schema_version": "1",
"command": "share-link create",
"input": {
"path": "/Reports/old.pdf"
},
"results": [
{
"status": "created",
"kind": "file",
"input": {},
"result": {
"type": "file",
"url": "https://www.dropbox.com/s/...",
Expand All @@ -429,11 +465,15 @@ The legacy `share list folder` command also supports operation-style JSON. It us

```json
{
"ok": true,
"schema_version": "1",
"command": "share list folder",
"input": {},
"results": [
{
"status": "listed",
"kind": "shared_folder",
"input": {},
"result": {
"type": "shared_folder",
"name": "Reports",
Expand All @@ -454,11 +494,15 @@ Team commands use the same operation-style wrapper. `team info` returns a single

```json
{
"ok": true,
"schema_version": "1",
"command": "team list-members",
"input": {},
"results": [
{
"status": "listed",
"kind": "team_member",
"input": {},
"result": {
"type": "team_member",
"team_member_id": "dbmid:...",
Expand All @@ -480,6 +524,8 @@ In JSON mode, command errors are written to stdout as JSON, including errors fro
```json
{
"ok": false,
"schema_version": "1",
"command": "rm",
"error": {
"message": "path exists and is not a folder: /old-file.txt",
"code": "path_conflict"
Expand Down
11 changes: 7 additions & 4 deletions cmd/account.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,10 @@ type jsonAccountTeam struct {
MemberID string `json:"member_id,omitempty"`
}

const accountKindAccount = "account"
const (
accountJSONStatusFound = "found"
accountKindAccount = "account"
)

// renderFullAccount prints the account details returned by GetCurrentAccount.
func renderFullAccount(out io.Writer, fa *users.FullAccount) error {
Expand Down Expand Up @@ -116,7 +119,7 @@ func account(cmd *cobra.Command, args []string) error {
input := accountInput{}
return out.Render(func(w io.Writer) error {
return renderFullAccount(w, res)
}, newAccountOperationOutput(input, jsonFullAccount(res)))
}, withJSONCommand(cmd, newAccountOperationOutput(input, jsonFullAccount(res))))
}

// Otherwise look up an account with the provided ID
Expand All @@ -130,12 +133,12 @@ func account(cmd *cobra.Command, args []string) error {
}
return out.Render(func(w io.Writer) error {
return renderBasicAccount(w, res)
}, newAccountOperationOutput(input, jsonBasicAccount(res)))
}, withJSONCommand(cmd, newAccountOperationOutput(input, jsonBasicAccount(res))))
}

func newAccountOperationOutput(input accountInput, account jsonAccount) jsonOperationOutput {
return newJSONOperationOutput(input, []jsonOperationResult{
newJSONOperationResult("", accountKindAccount, input, account),
newJSONOperationResult(accountJSONStatusFound, accountKindAccount, input, account),
}, nil)
}

Expand Down
2 changes: 1 addition & 1 deletion cmd/add-member.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ func addMember(cmd *cobra.Command, args []string) (err error) {
}
return commandOutput(cmd).Render(func(w io.Writer) error {
return renderTeamMemberAdd(w, res)
}, teamMemberAddOperationOutput(input, res))
}, withJSONCommand(cmd, teamMemberAddOperationOutput(input, res)))
}

func renderTeamMemberAdd(out io.Writer, res *team.MembersAddLaunch) error {
Expand Down
2 changes: 1 addition & 1 deletion cmd/cp.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ func cp(cmd *cobra.Command, args []string) error {
return fmt.Errorf("cp: %d error(s)", len(cpErrors))
}

return renderJSONOperationOutput(cmd, nil, relocationOperationResults(results))
return renderJSONOperationOutput(cmd, nil, relocationOperationResults(relocationJSONStatusCopied, results))
}

// cpCmd represents the cp command
Expand Down
9 changes: 6 additions & 3 deletions cmd/du.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,10 @@ type duAllocation struct {
UserWithinTeamSpaceLimitType string `json:"user_within_team_space_limit_type,omitempty"`
}

const duKindSpaceUsage = "space_usage"
const (
duJSONStatusReported = "reported"
duKindSpaceUsage = "space_usage"
)

func du(cmd *cobra.Command, args []string) (err error) {
dbx := usersNewFunc(config)
Expand All @@ -50,7 +53,7 @@ func du(cmd *cobra.Command, args []string) (err error) {

return commandOutput(cmd).Render(func(w io.Writer) error {
return renderUsage(w, usage)
}, newDuOperationOutput(usage))
}, withJSONCommand(cmd, newDuOperationOutput(usage)))
}

func renderUsage(out io.Writer, usage *users.SpaceUsage) error {
Expand Down Expand Up @@ -81,7 +84,7 @@ func newDuOutput(usage *users.SpaceUsage) duOutput {
func newDuOperationOutput(usage *users.SpaceUsage) jsonOperationOutput {
input := duInput{}
return newJSONOperationOutput(input, []jsonOperationResult{
newJSONOperationResult("", duKindSpaceUsage, input, newDuOutput(usage)),
newJSONOperationResult(duJSONStatusReported, duKindSpaceUsage, input, newDuOutput(usage)),
}, nil)
}

Expand Down
2 changes: 1 addition & 1 deletion cmd/info.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ func info(cmd *cobra.Command, args []string) (err error) {

return commandOutput(cmd).Render(func(w io.Writer) error {
return renderTeamInfo(w, res)
}, teamInfoOperationOutput(res))
}, withJSONCommand(cmd, teamInfoOperationOutput(res)))
}

func renderTeamInfo(out io.Writer, res *team.TeamGetInfoResult) error {
Expand Down
Loading
Loading