Skip to main content

Entity catalog

The entity catalog is a structured, queryable source of truth that allows you extend and enrich nullplatform entities—such as builds, applications, and namespaces—with structured, schema-validated metadata. This enables smarter automation, richer UI components, and consistent enforcement of organizational standards.

What is the entity catalog?​

At its core, the catalog provides a way to attach custom attributes to any entity. These attributes are defined and validated using JSON Schema, which ensures data consistency across your platform.

Think of it as a programmable metadata system—one that is:

  • Flexible: You decide what data is needed per entity.
  • Validated: Every field is schema-checked at runtime.
  • Hierarchical: You can define or override attributes at any level of your NRN structure (e.g., namespace > application > build).

Benefits of using the catalog​

  • Structure – Avoid loose, inconsistent metadata.
  • Visualization – Power UI components directly from schema-defined fields.
  • Automation – Drive approval workflows and deployment pipelines using dynamic attributes.
  • Discoverability – Tag entities for search, filtering, and reporting.

Key concepts​

Each catalog entry consists of two parts:

  • Catalog specification: A schema that defines what metadata is allowed and how it should be structured.
  • Metadata entry: A JSON object that attaches actual data to a specific entity like an application, validated against the catalog specification.

This data can be used to:

  • Display custom info in the UI (e.g., test coverage, platform type).
  • Drive approval workflows and deployment policies.
  • Power autogenerated forms and tags for better UX and discoverability.

How it works​

To use the catalog, you’ll follow three steps:

  1. Define a catalog specification

    Create a schema that describes the attributes your entity should support. You can define field types, validation rules, and tagging behaviors.

  2. Create one or more metadata entries

    Submit actual metadata values that conform to the specification. These values are attached to individual entity instances.

  3. Use the metadata in your workflows

    The platform can automatically render these values in dashboards, forms, and detail views. You can also use metadata in automation and policy enforcement.

Example use cases​

Here’s how teams typically use the catalog in practice:

Build coverage tracking

Track test coverage per build and visualize it on the build detail page.

{
  "coverage": {
    "percent": 95,
    "report": "https://reports.example.com/build-123/coverage.html"
  }
}

Application platform tagging

Indicate whether an application targets web, mobile, or IoT, and use this to filter or group applications.

{
  "platform_type": "mobile"
}

Namespace-level configuration

Attach region, platform, or maintainer info to a namespace, and reuse it across multiple services or automations.

{
  "maintainers": ["alice@example.com", "bob@example.com"],
  "region": "eu-west-1",
  "platform": ["web", "microservice"]
}

Next steps​

Now that you have the basic concepts on catalog, here are some quick links that can be useful to jump to: