Formatted output

The ORAS command allows users to format the metadata output and perform computations on data based on the formatted output. The ORAS command also allows the --output option to write to a file or directory.

• Use --format <DATA_FORMAT> to format metadata output of ORAS commands into different formats including prettified JSON, tree, table view, and Go template, i.e. --format json|tree|table|go-template. It supports computing figures within the template using Sprig functions. This is the primary and recommended usage.
• Use --template GO_TEMPLATE to compute and manipulate the output data using Go template based on the chosen data format. To avoid ambiguity, this flag can only be used along with --format go-template.

note

Both --format and --template are marked as "Experimental" in its first iteration v1.2.0.

How to format output in ORAS commands

Use the --format flag to format metadata output into structured data (e.g. JSON) and optionally use the --template option with a Go template to manipulate the output data. See sample usages in several commands below.

oras manifest fetch

For example, when using oras manifest fetch with the flag --format, the following fields should be formatted into JSON output:

• reference: full artifact reference by digest, e.g, $REGISTRY/$REPO@$DIGEST
• mediaType: media type of the image manifest
• digest: digest of the image manifest
• size: manifest file size in bytes
• artifactType: the type of an artifact when the manifest is used for an artifact
• content: content object includes prettified manifest output
  • config: a content descriptor describes the disposition of the targeted content
  • layers: array of objects, each object in the array MUST be a descriptor

See sample use cases of formatted output for oras manifest fetch:

• Example: use --output <file> and --format at the same time, a manifest file should be produced in the filesystem and the mediaType value should be outputted on the console:

$ oras manifest fetch $REGISTRY/$REPO:$TAG --output sample-manifest --format go-template='{{.content.config.mediaType}}'
application/vnd.oci.empty.v1+json

View the content of the generated manifest within specified sample-manifest file. The output should be compact JSON data:

$ cat sample-manifest
{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","artifactType":"application/vnd.unknown.artifact.v1","config":{"mediaType":"application/vnd.oci.empty.v1+json","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2,"data":"e30="},"layers":[{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:6cb759c4296e67e35b0367f3c0f51dfdb776a0c99a45f39d0476e43d82696d65","size":14477,"annotations":{"org.opencontainers.image.title":"sbom.spdx"}},{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:54c0e84503c8790e03afe34bfc05a5ce45c933430cfd9c5f8a99d2c89f1f1b69","size":6639,"annotations":{"org.opencontainers.image.title":"scan-test-verify-image.json"}}],"annotations":{"org.opencontainers.image.created":"2023-12-15T09:41:54Z"}}

note

The --output - option for standard output cannot be used with the --format option due to conflicts.

• Example: use --format json to print the metadata output in prettified JSON:

oras manifest fetch $REGISTRY/$REPO:$TAG --format json

{
  "reference": " $REGISTRY/$REPO@sha256:8be4c36a29979c72fdd225654498791fb381a7dd8332ade1981274a16220fe1c",
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:8be4c36a29979c72fdd225654498791fb381a7dd8332ade1981274a16220fe1c",
  "artifactType": "application/vnd.unknown.artifact.v1",
  "content": {
    "config": {
      "mediaType": "application/vnd.oci.empty.v1+json",
      "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
      "size": 2
    },
    "layers": [
      {
        "mediaType": "application/vnd.oci.image.layer.v1.tar",
        "digest": "sha256:6cb759c4296e67e35b0367f3c0f51dfdb776a0c99a45f39d0476e43d82696d65",
        "size": 14477,
        "annotations": {
          "org.opencontainers.image.title": "sbom.spdx"
        }
      },
      {
        "mediaType": "application/vnd.oci.image.layer.v1.tar",
        "digest": "sha256:54c0e84503c8790e03afe34bfc05a5ce45c933430cfd9c5f8a99d2c89f1f1b69",
        "size": 6639,
        "annotations": {
          "org.opencontainers.image.title": "scan-test-verify-image.json"
        }
      }
    ],
    "annotations": {
      "org.opencontainers.image.created": "2023-12-15T09:41:54Z"
    }
  }
}

• Example: use --format go-template along with --template GO_TEMPLATE to fetch the metadata output and render it with Go template, filter out the config data of the manifest:

oras manifest fetch $REGISTRY/$REPO:$TAG --format go-template --template '{{ toPrettyJson .content.config }}'

{
  "digest": "sha256:b6f50765242581c887ff1acc2511fa2d885c52d8fb3ac8c4bba131fd86567f2e",
  "mediaType": "application/vnd.docker.container.image.v1+json",
  "size": 3362
}

oras pull

When using oras pull with the flag --format, the following fields should be formatted into JSON output:

• reference: full artifact reference by digest, e.g, $REGISTRY/$REPO@$DIGEST
• files: a list of downloaded files
  • path: the absolute file path of the pulled file (layer)
  • reference: full reference by digest of the pulled file (layer)
  • mediaType: media type of the pulled file (layer)
  • digest: digest of the pulled file (layer)
  • size: file size in bytes
  • annotations: contains arbitrary metadata for the image manifest

For example, pull an artifact that contains multiple layers (files) and show their descriptor metadata as pretty JSON in standard output:

oras pull $REGISTRY/$REPO:$TAG --artifact-type example/sbom sbom.spdx  --artifact-type example/vul-scan vul-scan.json --format json

{
  "reference": "localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186111",
  "files": [
    {
      "path": "/home/user/oras-install/sbom.spdx",
      "reference": "localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186222",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186222",
      "size": 820,
      "annotations": {
        "org.opencontainers.image.title": "sbom.spdx"
      }
    },
    {
      "path": "/home/user/oras-install/vul-scan.json",
      "reference": "localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd18669b",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd18669b",
      "size": 820,
      "annotations": {
        "org.opencontainers.image.title": "vul-scan.json"
      }
    }
  ]
}

note

When pulling a folder to filesystem, the value of path should be an absolute path of the folder and should be ended with slash / or backslash \, for example, /home/Bob/sample-folder/ on Unix or C:\Users\Bob\sample-folder\ on Windows. Other fields are the same as the example of pulling files as above.

For example, pull an artifact that contains multiple layers (files) and show their descriptor metadata as compact JSON in the standard output.

oras pull $REGISTRY/$REPO:$TAG --format go-template='{{toRawJson .}}'

{"reference":"localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186111","files":[{"path":"/home/user/oras-install/sbom.spdx","reference":"localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186222","mediaType":"application/vnd.oci.image.manifest.v1+json","digest":"sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186222","size":820},{"path":"/home/user/oras-install/vul-scan.json","reference":"localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd18669b","mediaType":"application/vnd.oci.image.manifest.v1+json","digest":"sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd18669b","size":820}]}

oras push

When using oras push with the flag --format, the following fields should be formatted into JSON output:

• reference: full artifact reference by digest, e.g, $REGISTRY/$REPO@$DIGEST
• referenceByTags: array, pushed tags by reference, e.g. $REGISTRY/$REPO@TAG1
• mediaType: media type of the pushed file (layer)
• digest: digest of the pushed file (layer)
• size: file size in bytes
• artifactType: artifact type of the pushed file
• annotations: contains arbitrary metadata for the image manifest

For example, push a file and two tags to a repository and show the descriptor of the image manifest in pretty JSON format.

oras push $REGISTRY/$REPO:$TAG1,$TAG2 sbom.spdx vul-scan.json --format json 

{
  "reference": "$REGISTRY/$REPO@sha256:4a5b8c83d153f52afdfcb422db56c2349aae3bd5ecf8338a58353b5eb6681c45",
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:4a5b8c83d153f52afdfcb422db56c2349aae3bd5ecf8338a58353b5eb6681c45",
  "size": 820,
  "annotations": {
    "org.opencontainers.image.created": "2023-12-15T09:41:54Z"
  },
  "artifactType": "json/example",
  "referenceByTags": [
    "$REGISTRY/$REPO:$TAG1",
    "$REGISTRY/$REPO:$TAG2"
  ]
}

note

When pushing a folder to filesystem, the output fields are the same as the example of pushing files as above.

Push a folder to a repository and filter out the value of reference and mediaType of the pushed artifact in the standard output.

oras push $REGISTRY/$REPO:$TAG sample-folder --format go-template='{{.reference}}, {{.mediaType}}'

$REGISTRY/$REPO@sha256:85438e6598bf35057962fff34399a362d469ca30a317939427fca6b7a289e70d, application/vnd.oci.image.manifest.v1+json

oras attach

When using oras attach with the flag --format, the following fields should be formatted into JSON output:

• reference: full reference by digest of the referrer file
• mediaType: media type of the referrer
• size: referrer file size in bytes
• digest: digest of the attached referrer file
• artifactType: artifact type of the referrer
• annotations: contains arbitrary metadata in a referrer

For example, attach two files to an image and show the descriptor metadata of the referrer in JSON format.

oras attach $REGISTRY/$REPO:$TAG --artifact-type example/report-and-sbom vul-report.json:example/vul-scan sbom.spdx:example/sbom --format json

{
  "reference": "$REGISTRY/$REPO@sha256:0afd0f0c35f98dcb607de0051be7ebefd942eef1e3a6d26eefd1b2d80f2affbe",
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:0afd0f0c35f98dcb607de0051be7ebefd942eef1e3a6d26eefd1b2d80f2affbe",
  "size": 923,
  "annotations": {
    "org.opencontainers.image.created": "2023-12-15T08:59:21Z"
  },
  "artifactType": "example/report-and-sbom"
}

oras discover

View an artifact's referrers. The default output should be listed in a tree view.

oras discover $REGISTRY/$REPO:$TAG --format tree

$REGISTRY/$REPO@sha256:a3785f78ab8547ae2710c89e627783cfa7ee7824d3468cae6835c9f4eae23ff7
├── application/vnd.cncf.notary.signature
│   └── sha256:8dee8cb9a1334595545e3baf15c3eeed13c4b35ae08e3ab32e1df31fb152dc1d
└── sbom/example
    └── sha256:50fd0dc107d84b5e7b402688000a7ed3aaf8a2692d5cb74da5277fa3c4cecf15

View an artifact's referrers manifest in pretty JSON output. The following fields should be outputted:

• manifests: the list of referrers
  • reference: full reference by digest of the referrer
  • mediaType: media type of the referrer
  • size: referrer file size in bytes
  • digest: digest of the referrer
  • artifactType: artifact type of a referrer
  • annotations: contains arbitrary metadata in a referrer

See an example:

oras discover $REGISTRY/$REPO:v1 --format json

{
  "manifests": [
    {
      "reference": "$REGISTRY/$REPO@sha256:8dee8cb9a1334595545e3baf15c3eeed13c4b35ae08e3ab32e1df31fb152dc1d",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:8dee8cb9a1334595545e3baf15c3eeed13c4b35ae08e3ab32e1df31fb152dc1d",
      "size": 739,
      "annotations": {
        "io.cncf.notary.x509chain.thumbprint#S256": "[\"79e91aa1e109a16df87d200e493fd3d33c67253f76d41334d7f7c29c00ba55b3\"]",
        "org.opencontainers.image.created": "2024-01-01T10:32:55Z"
      },
      "artifactType": "application/vnd.cncf.notary.signature"
    },
    {
      "reference": "$REGISTRY/$REPO@sha256:50fd0dc107d84b5e7b402688000a7ed3aaf8a2692d5cb74da5277fa3c4cecf15",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:50fd0dc107d84b5e7b402688000a7ed3aaf8a2692d5cb74da5277fa3c4cecf15",
      "size": 739,
      "annotations": {
        "org.opencontainers.image.created": "2024-01-01T07:57:10Z"
      },
      "artifactType": "sbom/example"
    }
  ]
}