--- title: JSON output schema reference description: All -O json output from Ping CLI uses a consistent envelope structure. Every response (success or failure) always contains six top-level fields (schemaVersion, status, message, data, errors, meta), making it straightforward to parse reliably without checking the shape of the output first. A warnings field is included only when the command completes with non-fatal warnings. component: pingcli version: 1.0 page_id: pingcli:output_schema_reference:output-schema-reference canonical_url: https://developer.pingidentity.com/pingcli/1.0/output_schema_reference/output-schema-reference.html revdate: June 8, 2026 section_ids: envelope-fields: Envelope fields status-values: status values errors-object: errors[] object error-category-values: errors[].category values meta-object: meta object warnings-object: warnings[] object ndjson-envelope-behaviour: NDJSON envelope behaviour jsonschema: JSONSchema learn-more: Learn more --- # JSON output schema reference All `-O json` output from Ping CLI uses a consistent envelope structure. Every response (success or failure) always contains six top-level fields (`schemaVersion`, `status`, `message`, `data`, `errors`, `meta`), making it straightforward to parse reliably without checking the shape of the output first. A `warnings` field is included only when the command completes with non-fatal warnings. NDJSON output has two modes: * `-O ndjson` (default) — each line is a raw record with no envelope. * `-O ndjson-wrapped` — each line is the full envelope wrapping a single record. Errors are always envelope-wrapped regardless of output format. ## Envelope fields | | | | | | --------------- | ----------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ***Field*** | ***Type*** | ***Present*** | ***Description*** | | `schemaVersion` | string | Always | Schema version for the envelope. Currently `"1.0"`. | | `status` | string | Always | Result status. One of `success`, `warning`, or `error`. Refer to [status values](#status-values). | | `message` | string | Always | Human-readable status message. Empty string when not applicable. | | `data` | any \| null | Always | The command result payload. An array for list commands; a single object for get, create, and update commands; `null` on error. | | `errors` | array | Always | Array of error objects on failure; empty array `[]` on success. Refer to [errors\[\] object](#errors-object). | | `meta` | object | Always | Metadata about the command invocation. Refer to [meta object](#meta-object). | | `warnings` | array | When applicable | Array of warning objects. Present only when the command completes with warnings. Absent when there are no warnings. Refer to [warnings\[\] object](#warnings-object). | ## status values | | | | ----------- | ----------------------------------------------------------------------------------------------------------- | | ***Value*** | ***When set*** | | `success` | Command completed successfully; result is in `data`. | | `warning` | Command completed but with non-fatal warnings; result is in `data` and `warnings` is present and non-empty. | | `error` | Command failed; `data` is `null` and `errors` is non-empty. | | | | | - | -------------------------------------------------------------------- | | | The earlier `"info"` and `"fatal"` status values are no longer used. | ## errors\[] object | | | | | | ------------ | ---------- | --------------- | ---------------------------------------------------------------------------------------------------------- | | ***Field*** | ***Type*** | ***Present*** | ***Description*** | | `code` | string | Always | Machine-readable error code, for example `SERVICE_ERROR` or `INVALID_ARGUMENT`. | | `category` | string | Always | Error category. Refer to [errors\[\].category values](#error-category-values). | | `retryable` | boolean | Always | Whether the request can be retried automatically. `true` only for `rate_limited` and `network` categories. | | `message` | string | Always | Human-readable description of the error. | | `suggestion` | string | When applicable | A suggestion to help resolve the error. | | `details` | object | API errors only | Raw API response body for HTTP errors from `pingone api` or `pingfederate api` commands. | ### errors\[].category values | | | | -------------- | --------------------------------------------------------- | | ***Value*** | ***Condition*** | | `validation` | HTTP 400, or a CLI flag or argument error | | `unauthorized` | HTTP 401 | | `forbidden` | HTTP 403 | | `not_found` | HTTP 404 | | `conflict` | HTTP 409 | | `rate_limited` | HTTP 429 | | `internal` | HTTP 5xx | | `network` | Network-level failure (connection refused, timeout, etc.) | ## meta object | | | | | | ---------------- | ---------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | ***Field*** | ***Type*** | ***Present*** | ***Description*** | | `command` | string | Always | The full command that was invoked, reconstructed from `os.Args`. Present even for pre-parse errors. | | `count` | integer | Array results only | The number of records in `data`. Set automatically when `data` is an array; absent for single-object results. | | `api.httpStatus` | integer | `pingone api` and `pingfederate api` only | The HTTP status code returned by the upstream API. Absent on connector commands. | ## warnings\[] object | | | | | ----------- | ---------- | ------------------------------------------ | | ***Field*** | ***Type*** | ***Description*** | | `code` | string | Machine-readable warning code. | | `message` | string | Human-readable description of the warning. | ## NDJSON envelope behaviour | | | | ------------------- | ----------------------------------------------------------------------------------------------------------------------- | | ***Format*** | ***Envelope behaviour*** | | `-O ndjson` | Each line is a raw record (the contents of `data`) with no envelope wrapper. Errors are always envelope-wrapped. | | `-O ndjson-wrapped` | Each line is the full envelope wrapping a single record. `data` holds one record for each line; `meta.count` is absent. | ## JSONSchema The following [JSON Schema (draft-07)](https://json-schema.org/draft-07/schema) can be used to validate `-O json` output or to generate client code. ```json { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Ping CLI JSON output envelope", "type": "object", "required": ["schemaVersion", "status", "message", "data", "errors", "meta"], "properties": { "schemaVersion": { "type": "string", "enum": ["1.0"] }, "status": { "type": "string", "enum": ["success", "warning", "error"] }, "message": { "type": "string" }, "data": {}, "errors": { "type": "array", "items": { "type": "object", "required": ["code", "category", "retryable", "message"], "properties": { "code": { "type": "string" }, "category": { "type": "string", "enum": [ "validation", "unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "internal", "network" ] }, "retryable": { "type": "boolean" }, "message": { "type": "string" }, "suggestion": { "type": "string" }, "details": { "type": "object" } } } }, "meta": { "type": "object", "required": ["command"], "properties": { "command": { "type": "string" }, "count": { "type": "integer", "description": "Present only when data is an array" }, "api": { "type": "object", "properties": { "httpStatus": { "type": "integer" } } } } }, "warnings": { "type": "array", "items": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } ``` ## Learn more * [Output formats](../using_pingcli/output-formats.html) * [Filtering and transforming output](../using_pingcli/filtering-output.html) * [Return codes](../using_pingcli/return-codes.html)