feat(cli): add `describe` command for detailing OCM entities and metadata by jakobmoellerdev · Pull Request #1554 · open-component-model/open-component-model

jakobmoellerdev · 2026-01-05T16:04:50Z

What this PR does / why we need it

Introduces the describe command, including the types subcommand, to describe OCM subsystems, types, and configuration schemas. Adds supporting markdown and text renderers for improved documentation output.

Which issue(s) this PR fixes

Synopsis

## ocm describe types

Describe OCM types and their configuration schema

### Synopsis

Describe OCM types registered in various subsystems.

WHAT ARE SUBSYSTEMS?
  OCM uses a plugin-based architecture where different types of functionality are organized
  into subsystems. Each subsystem is a collection of related type implementations. When you
  use OCM commands or configure OCM resources, you specify types from these subsystems.

  Common subsystems:
    - ocm-repository:          Where component versions are stored (OCI registries, CTF archives)
    - ocm-resource-repository: Where resources within components are stored
    - input:                   How content is sourced (from files, directories, etc.) in component constructors
    - credential-repository:   Where credentials are stored and retrieved
    - signing:                 How component versions are signed and verified

HOW TO USE SUBSYSTEMS:
  When creating OCM configurations (YAML files) or using CLI commands, you'll specify a 'type'
  field. This type comes from one of the subsystems. For example:

  In a repository configuration:
    type: OCIRepository/v1        # Type from ocm-repository subsystem
    spec:
      baseUrl: ghcr.io

  In an input specification:
    type: dir/v1                  # Type from input subsystem
    spec:
      path: ./my-content

  Use this command to:
    1. Discover what subsystems exist
    2. See what types are available in each subsystem
    3. Learn what fields each type requires

EXPLORATION WORKFLOW:
  1. List all subsystems (no arguments)
  2. Pick a subsystem and list its types (one argument: subsystem name)
  3. View field details for a specific type (two arguments: subsystem and type name)

ocm describe types

+---------------------------------------------------------------------------------------+
| Available Subsystems                                                                  |
+-------------------------+--------------------------+----------------------------------+
| SUBSYSTEM               | TYPES                    | ALIAS                            |
+-------------------------+--------------------------+----------------------------------+
| input                   | dir/v1                   | dir                              |
|                         | file/v1                  | file                             |
|                         | utf8/v1                  | utf8                             |
+-------------------------+--------------------------+----------------------------------+
| ocm-repository          | CommonTransportFormat/v1 | CTF                              |
|                         |                          | CTF/v1                           |
|                         |                          | CommonTransportFormat            |
|                         |                          | ctf                              |
|                         |                          | ctf/v1                           |
|                         | OCIRepository/v1         | OCI                              |
|                         |                          | OCI/v1                           |
|                         |                          | OCIRepository                    |
|                         |                          | oci                              |
|                         |                          | oci/v1                           |
+-------------------------+--------------------------+----------------------------------+
| ocm-repository-lister   | CommonTransportFormat/v1 | CTF                              |
|                         |                          | CTF/v1                           |
|                         |                          | CommonTransportFormat            |
|                         |                          | ctf                              |
|                         |                          | ctf/v1                           |
|                         | OCIRepository/v1         | OCI                              |
|                         |                          | OCI/v1                           |
|                         |                          | OCIRepository                    |
|                         |                          | oci                              |
|                         |                          | oci/v1                           |
+-------------------------+--------------------------+----------------------------------+
| ocm-resource-repository | OCIImage/v1              | OCIImage                         |
|                         |                          | ociArtifact                      |
|                         |                          | ociArtifact/v1                   |
|                         |                          | ociImage                         |
|                         |                          | ociImage/v1                      |
|                         |                          | ociRegistry                      |
|                         |                          | ociRegistry/v1                   |
|                         | OCIImageLayer/v1         | OCIImageLayer                    |
|                         |                          | ociBlob                          |
|                         |                          | ociBlob/v1                       |
+-------------------------+--------------------------+----------------------------------+
| signing                 | RSASigningConfiguration  | RSASigningConfiguration/v1alpha1 |
+-------------------------+--------------------------+----------------------------------+

ocm describe types input

+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Input methods define how content is sourced and ingested into an OCM component version.                                                                           |
+----------------------------------------------------------------------------------+--------------------------------------------------------------------------------+
| TYPE                                                                             | ALIAS                                                                          |
+----------------------------------------------------------------------------------+--------------------------------------------------------------------------------+
| dir/v1                                                                           | dir                                                                            |
| file/v1                                                                          | file                                                                           |
| utf8/v1                                                                          | utf8                                                                           |
+----------------------------------------------------------------------------------+--------------------------------------------------------------------------------+

ocm describe types input dir

+----------------------------------------------------------------------------------------------------------------------------------------------+
| Dir (dir)                                                                                                                                    |
| Dir describes an input sourced by a directory.                                                                                               |
| 9 fields (2 required, 7 optional)                                                                                                            |
+----------------+-----------+----------+------------------------------------------------------------------------------------------------------+
| FIELD NAME     | TYPE      | REQUIRED | DESCRIPTION                                                                                          |
+----------------+-----------+----------+------------------------------------------------------------------------------------------------------+
| compress       | [boolean] | ✗        | Compress indicates whether the resulting blob should be compressed with gzip.                        |
| excludeFiles   | [array]   | ✗        | ExcludeFiles is a list of file name patterns to exclude from addition to the resulting blob.         |
|                |           |          | Excluded files always override included files.                                                       |
| followSymlinks | [boolean] | ✗        | FollowSymlinks will include the content of the encountered symbolic links to the resulting blob.     |
|                |           |          | Support for this option is not implemented yet. The field is included for compatibility with previou |
|                |           |          | s OCM version.                                                                                       |
| includeFiles   | [array]   | ✗        | IncludeFiles is a list of file name patterns to exclusively add to the resulting blob.               |
| mediaType      | [string]  | ✗        | MediaType is the media type of the resulting blob.                                                   |
| path           | [string]  | ✓        | Path is the path to the directory.                                                                   |
| preserveDir    | [boolean] | ✗        | PreserveDir defines that the directory specified in the Path field should be included in the resulti |
|                |           |          | ng blob.                                                                                             |
| reproducible   | [boolean] | ✗        | Reproducible defines that the attributes of the included files have to be normalized.                |
|                |           |          | This is important if reproducible generation of blobs is required. In this case the blobs            |
|                |           |          | need to be comparable on byte level (e.g. for hashing). So, if Reproducible is set to true,          |
|                |           |          | to get fully byte-equivalent blobs despite different file modification time, permission bits, etc.,  |
|                |           |          | these attributes will be set to fixed values while creating the blob.                                |
| type           | [string]  | ✓        | Type represents a structured type with an optional version and a name. It is used to identify the ty |
|                |           |          | pe of an object in a versioned API.                                                                  |
|                |           |          | Possible values: [dir/v1 Dir/v1 dir Dir]                                                             |
+----------------+-----------+----------+------------------------------------------------------------------------------------------------------+

fix open-component-model/ocm-project#806

…data Introduces the `describe` command, including the `types` subcommand, to describe OCM subsystems, types, and configuration schemas. Adds supporting markdown and text renderers for improved documentation output. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

… structure Replaces the deprecated internal `jsonschema` package with functionality from the `runtime` module. Refactors CLI renderers for `types` command to streamline schema introspection and output formatting. Adds support for `jsonschema` output format. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

… schemas Removes all schema definitions, markers, and code related to the Diataxis documentation model, along with its integration into the JSON schema generation. Simplifies the codebase by eliminating unused documentation features. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

Adds support for new output formats (`markdown`, `html`) and customizable table styles (`StyleColoredBright`, `StyleColoredDark`, `StyleDefault`) for the `types` commands. Refactors subsystem sorting and removes unused `title` field from `Subsystem` struct for a streamlined design. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

Introduces a new `--examples` flag to display YAML-formatted examples for specific types and schemas in the `types` command. Updates schema definitions and CLI flags to support this feature. Enhances JSON schema generation with example markers. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

… `types` command Adds support for rendering output through a pager (e.g., `less`) for improved readability in terminal environments. Refactors output rendering to detect terminal or file-based output, ensuring appropriate handling for different output types. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

Signed-off-by: Jakob Möller <contact@jakob-moeller.com> # Conflicts: # bindings/go/generator/jsonschemagen/marker.go # bindings/go/oci/spec/transformation/v1alpha1/schemas/CTFAddComponentVersion.schema.json # bindings/go/oci/spec/transformation/v1alpha1/schemas/CTFAddComponentVersionSpec.schema.json # bindings/go/oci/spec/transformation/v1alpha1/schemas/CTFGetComponentVersion.schema.json # bindings/go/oci/spec/transformation/v1alpha1/schemas/CTFGetComponentVersionOutput.schema.json # bindings/go/oci/spec/transformation/v1alpha1/schemas/OCIAddComponentVersion.schema.json # bindings/go/oci/spec/transformation/v1alpha1/schemas/OCIAddComponentVersionSpec.schema.json # bindings/go/oci/spec/transformation/v1alpha1/schemas/OCIGetComponentVersion.schema.json # bindings/go/oci/spec/transformation/v1alpha1/schemas/OCIGetComponentVersionOutput.schema.json # cli/go.mod # cli/go.sum # cli/integration/go.mod

fabianburth

I love it!

Just some small remarks. Besides, if the terminal is not wide enough, the table format quickly becomes unreadable.

Signed-off-by: Jakob Möller <contact@jakob-moeller.com> # Conflicts: # cli/go.mod

…on and improved field-path navigation Adds expanded documentation for subsystems and their types, including usage examples, workflows, and output formats. Introduces support for field-path navigation using dot notation and enhances terminal output for usability. Refactors schema handling to improve modularity and reusability. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

… global registry Replaces the global subsystem registry with context-specific registries, improving encapsulation and concurrency support. Refactors registration and access patterns. Adjusts tests and CLI integration to align with the new design. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

…nfo` for improved flexibility Refactors schema metadata handling in the `describe types` command by introducing the `schemaInfo` struct to encapsulate schema details. Updates output rendering to leverage modular `schemaInfo` components, enhances formatting for tables and details, and adds support for rendering fields without properties. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

…ehensive tests Replaces inline table-building logic in the `describe types` command with reusable `buildSubsystemsTable` and `buildTypesTable` functions. Simplifies code by removing unused styles and refactoring output handling. Adds extensive tests to ensure command accuracy and reliability. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

# Conflicts: # .github/config/wordlist.txt

frewilhelm

I really like the command and the capabilities!

… for `types` command Streamlines output rendering logic by directly determining terminal capability at usage. Updates examples in documentation to reflect changes in field-path navigation, replacing `spec` with `baseUrl`. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

# Conflicts: # cli/go.mod # cli/go.sum # cli/integration/go.mod

Upgraded `golang.org/x/text` to v0.33.0 and multiple `ocm.software/open-component-model` modules to newer versions. Adjusted `cli/integration/go.mod` accordingly. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

…` command Eliminates references to generating example configurations using `-o examples` from both command help text and related documentation for the `describe types` command. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

matthiasbruns

awesome work ❤️

Signed-off-by: Jakob Möller <contact@jakob-moeller.com> # Conflicts: # cli/go.mod

github-actions Bot added kind/feature new feature, enhancement, improvement, extension size/l Large labels Jan 5, 2026

jakobmoellerdev added 5 commits January 6, 2026 16:50

jakobmoellerdev mentioned this pull request Jan 19, 2026

ocm describe types Command open-component-model/ocm-project#806

Closed

7 tasks

jakobmoellerdev force-pushed the ocm-describe-command branch from 4ca0c12 to 19a069c Compare January 20, 2026 16:35

jakobmoellerdev force-pushed the ocm-describe-command branch from 19a069c to a933696 Compare January 20, 2026 16:36

fabianburth reviewed Jan 23, 2026

View reviewed changes

Comment thread cli/cmd/describe/types/cmd.go Outdated

Comment thread cli/cmd/describe/types/cmd.go Outdated

Comment thread cli/cmd/describe/types/cmd.go

fabianburth reviewed Jan 23, 2026

View reviewed changes

Comment thread cli/cmd/describe/types/cmd.go

Merge remote-tracking branch 'upstream/main' into ocm-describe-command

0af214d

Signed-off-by: Jakob Möller <contact@jakob-moeller.com> # Conflicts: # cli/go.mod

jakobmoellerdev force-pushed the ocm-describe-command branch from 0438418 to 0af214d Compare January 30, 2026 15:52

jakobmoellerdev marked this pull request as ready for review January 30, 2026 17:27

jakobmoellerdev requested a review from a team as a code owner January 30, 2026 17:27

jakobmoellerdev added 2 commits February 2, 2026 12:22

Merge remote-tracking branch 'upstream/main' into ocm-describe-command

7c0a6c9

jakobmoellerdev force-pushed the ocm-describe-command branch from 5a106f8 to d1d48c1 Compare February 2, 2026 11:48

github-actions Bot added the component/github-actions Changes on GitHub Actions or within `.github/` directory label Feb 2, 2026

jakobmoellerdev added 3 commits February 2, 2026 13:02

Merge remote-tracking branch 'upstream/main' into ocm-describe-command

4cdc72b

# Conflicts: # .github/config/wordlist.txt

frewilhelm reviewed Feb 3, 2026

View reviewed changes

Comment thread cli/cmd/describe/types/cmd.go Outdated

frewilhelm reviewed Feb 3, 2026

View reviewed changes

Comment thread cli/cmd/describe/types/cmd.go Outdated

Comment thread cli/cmd/describe/types/cmd.go Outdated

Comment thread cli/cmd/describe/types/render.go Outdated

jakobmoellerdev added 2 commits February 3, 2026 15:17

Merge remote-tracking branch 'upstream/main' into ocm-describe-command

4f80aab

# Conflicts: # cli/go.mod # cli/go.sum # cli/integration/go.mod

chore(deps): update module dependencies in go.mod and go.sum

d023d09

Upgraded `golang.org/x/text` to v0.33.0 and multiple `ocm.software/open-component-model` modules to newer versions. Adjusted `cli/integration/go.mod` accordingly. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

jakobmoellerdev requested review from fabianburth and frewilhelm February 3, 2026 14:46

matthiasbruns previously approved these changes Feb 4, 2026

View reviewed changes

Merge remote-tracking branch 'upstream/main' into ocm-describe-command

65a3876

Signed-off-by: Jakob Möller <contact@jakob-moeller.com> # Conflicts: # cli/go.mod

jakobmoellerdev dismissed matthiasbruns’s stale review via 65a3876 February 4, 2026 15:08

Merge remote-tracking branch 'upstream/main' into ocm-describe-command

cbda1a9

Signed-off-by: Jakob Möller <contact@jakob-moeller.com> # Conflicts: # cli/go.mod

matthiasbruns approved these changes Feb 4, 2026

View reviewed changes

fabianburth approved these changes Feb 4, 2026

View reviewed changes

fabianburth merged commit 593d7ce into open-component-model:main Feb 4, 2026
30 of 32 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(cli): add `describe` command for detailing OCM entities and metadata#1554

feat(cli): add `describe` command for detailing OCM entities and metadata#1554
fabianburth merged 20 commits into
open-component-model:mainfrom
jakobmoellerdev:ocm-describe-command

jakobmoellerdev commented Jan 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fabianburth left a comment

Uh oh!

Uh oh!

Uh oh!

frewilhelm left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matthiasbruns left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

jakobmoellerdev commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does / why we need it

Which issue(s) this PR fixes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fabianburth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

frewilhelm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matthiasbruns left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jakobmoellerdev commented Jan 5, 2026 •

edited

Loading