How OSS projects Perses and Gemara make configuration user-friendly

Adoption and contribution keep open-source tools alive. When you’ve started a promising project, chances are engineers want to try it out. The easier it is to get started, the more people play with it, and recommend what you are building.

For most tools, however, getting started involves some level of configuration … and that’s exactly where users drop off.

All tools need to be configured, but the information on “how to” is usually spread across code, documentation, YAML files, or specific examples. Users have to deal with a manual, trial-and-error process where they only find out if their configuration is valid after deploying it. When it isn’t, troubleshooting begins.

It could be much simpler. Projects invest heavily in designing APIs with clear contracts, versioning, and tooling support. Configuration, which is often just as critical, rarely gets the same treatment. But it should.

In this article, we will explain how OpenSSF project Gemara and CNCF project Perses make configuration user-friendly, by providing a clean interface, the ability to validate configuration, and a standardized configuration process.

Using schema for validation

Previously, we outlined that configuration translates intent into a specification that delivers a desired outcome. It is a process that can get very complicated when it involves multiple actors or systems. Most configuration-related errors result from mistakes in this configuration process.

The best way to ensure a configuration is valid is to introduce a schema into the process. It gives users a blueprint on how to translate their intent and validate their configuration (before deploying it). While this is more practical for your users, it also makes their systems safer.

Using a schema also replaces a lot of hidden work maintainers do today. Today, most projects already maintain parts of a schema, e.g., in documentation, YAML examples, validation scripts, or tests. These are often duplicated and drift over time. A schema consolidates this into a single source of truth. It also drastically reduces the number of “Why doesn’t my config work?” issues on GitHub.

To define the schema, Gemara and Perses use CUE. Designed for configuration, CUE schemas can validate configurations in a variety of formats, including YAML, JSON, XML or TOML. CUE comes with extensive ways to express logic, implement policy directly in the schema, and integrate with IDEs for autocomplete.

While a schema allows a user to reliably create a more robust configuration, it takes more to make configuration user-friendly: a standardized configuration process.

Meet the Central Registry

While there are countless ways to provide a schema (a file in your GitHub repo, a description, or code blocks in your documentation), they carry a risk: they bit rot over time. Users copy them, fork them, adapt them, and over time, different versions emerge. Tools implement their own interpretation. The result? Multiple sources of truth, which is exactly what the use of schemas tries to prevent in the first place.

To be effective, only one source of truth should exist. That’s why we built the Central Registry. The Central Registry is a platform that makes it easy to provide configuration schemas to your users via CUE modules. It versions the schema, keeps track of updates and dependencies, and allows you to manage access control. Your users can import it directly into their development process. As CUE modules are built on the OCI standard, you can easily make them available on-prem for your enterprise users.

By providing schemas via Central Registry to your users, you give them a clear interface to validate their configuration through a standardized process. Configuration becomes user-friendly, and easy to manage. Not just for your users, but also for you as a project owner.

Perses and Gemara provide CUE schemas to their users for very different use cases, but both via Central Registry to benefit from the features and infrastructure it provides. Let’s look at it in detail.

Gemara

Open Source Security Foundation (OpenSSF) project Gemara develops a layered Governance, Risk, and Compliance (GRC) model, which enables developers to introduce GRC consistency to their development process. They separate the model into seven layers, from high-level governance to technical evidence. If all layers, e.g., across security tools and compliance systems, are consistent, the GRC goal is met.

Six of the layers in the Gemara model are made available as CUE schemas, giving tool developers and end users a consistent expectation for inputs and outputs. Users can simply validate the schemas against their systems. Gemara published the schemas to the Central Registry thereby making it easy for their users to import schemas, get IDE support, and cover dependency management.

Perses

CNCF project Perses is an open dashboard that can display a variety of observability data (Prometheus, Tempo, Loki, and others). In Perses, both data sources and visualization types are implemented as plugins, whose models are written in CUE. Beyond the built‑in plugins, users can implement their own to extend the native capabilities of the dashboard.

The plugin ecosystem runs on the Central Registry. As the plugins are schemas, users can discover and use any plugin directly from the Central Registry. Plugin developers can publish directly to the Central Registry. Having a home for their entire plugin ecosystem, Perses avoids fragmentation, and via Central Registry, offers versioning, dependency management, access control, and search to its developers and users.

Conclusions

While both projects publish CUE schema to the Central Registry for their users, their use cases differ vastly. Perses runs a plugin ecosystem; Gemara expresses a logical model.

However, there is a lot of common ground. Both provide schema to their users to make configuration user-friendly. Both tell users exactly what a correct configuration looks like and how to validate it. Both use the Central Registry to standardize the configuration process and provide a single source of truth.

Configuration is a simple concept that can get complicated quickly. By providing your users with schemas for your tool, configuration becomes a lot simpler, which directly drives adoption.

• 🚀 Publish a schema to the Central Registry in two minutes.
• 📖 Learn more about the Central Registry.
• 💬 Have questions? Get in touch with us.