Skip to main content

Tags in catalogs

When you have many applications, builds, or namespaces, finding and organizing them becomes challenging without a way to group or search by meaningful properties. Tags solve this by marking specific catalog fields as searchable, filterable metadata that can be:

  • Surfaced in dashboards: filter applications by compliance level, business unit, or cost center
  • Exposed to external tools: sync with FinOps platforms, inventory systems, or cloud governance tools
  • Queried via API: retrieve all entities matching specific tag criteria

Instead of burying important metadata in read-only catalog displays, tags make it discoverable and actionable.

How tags work​

A regular catalog field stores metadata on an entity, but only tags are promoted to the platform's filtering and integration layer. When you mark a field with the "tag" key in a catalog specification:

  1. In the UI, the field becomes available for filtering, grouping, and sorting in dashboards and list views.
  2. In the API, when you query an entity with ?include=tags, the platform collects all tagged fields and returns them together in a single tags object.
  3. In integrations, external systems can consume the tags to sync metadata. For example, mapping cost centers to your cloud provider's billing tags.

Fields not marked as tags still appear in catalog instances but are excluded from filters and the tags API response.

Defining tags in a catalog specification​

To tag a field, add the "tag" key to any property in your schema. Here's a specification with a mix of tagged and untagged fields:

{
  "name": "Application metadata",
  "entity": "application",
  "metadata": "operational",
  "nrn": "organization=123",
  "schema": {
    "type": "object",
    "properties": {
      "business_unit": {
        "type": "string",
        "enum": ["Engineering", "Finance", "Operations"],
        "title": "Business Unit",
        "tag": true
      },
      "cost_center": {
        "type": "string",
        "title": "Cost Center ID",
        "tag": "cost_center"
      },
      "compliance_level": {
        "type": "string",
        "enum": ["PCI", "HIPAA", "SOC2", "None"],
        "title": "Compliance Requirements",
        "tag": "compliance"
      },
      "owner": {
        "type": "string",
        "title": "Application Owner"
      }
    },
    "required": ["business_unit"]
  }
}

In this example, business_unit, cost_center, and compliance_level are tags. They'll appear in dashboard filters and the ?include=tags API response. The owner field is regular metadata: visible in the catalog but not promoted to the filtering or integration layer.

Tag naming​

  • "tag": true uses the property name as the tag key. The field business_unit produces a tag called business_unit.
  • "tag": "custom_name" assigns a custom key. For example, "tag": "compliance" exposes the field as compliance regardless of the property name.
Use custom names to standardize

Custom names let you keep tag keys consistent across different specifications. If two specs track compliance (one for applications, one for namespaces), giving both "tag": "compliance" means external integrations can rely on a single, predictable key.

Supported field types​

You can tag strings (including enums), numbers, booleans, and arrays. Avoid tagging deeply nested objects. Tag individual fields within them instead.

Querying tags via API​

When fetching an entity, add ?include=tags to collect all tagged fields into a single tags object.

curl -L -X GET 'https://api.nullplatform.com/applications/my-app-id?include=tags' \
  -H 'Authorization: Bearer <token>'

The response includes only the tagged fields from every catalog specification attached to that entity:

{
  "id": "my-app-id",
  "name": "my-application",
  "tags": {
    "business_unit": "Engineering",
    "cost_center": "CC0042",
    "compliance": "SOC2"
  }
}

Notice that owner (not tagged in the specification above) does not appear here. This makes ?include=tags useful for integrations that only need the filterable metadata without pulling full catalog instances.

Common use cases​

Cost allocation and FinOps​

Tag applications with cost_center, project_code, or owner, then sync those tags to your cloud provider's billing system or FinOps platform. This enables accurate chargeback by department, budget enforcement per business unit, and cost trend reporting.

{
  "cost_center": {
    "type": "string",
    "title": "Cost Center",
    "description": "Finance cost center for billing and allocation",
    "tag": "cost_center"
  },
  "project_code": {
    "type": "string",
    "title": "Project Code",
    "tag": "project_code"
  }
}

Compliance and governance​

Mark applications with the compliance frameworks they're subject to, then filter and report on them across your organization.

{
  "compliance_framework": {
    "type": "string",
    "enum": ["PCI", "HIPAA", "GDPR", "SOC2", "None"],
    "title": "Applicable Compliance Framework",
    "tag": "compliance"
  }
}

With this tag in place, you can audit which applications fall under a specific framework, run compliance scans only on in-scope applications, and generate reports for auditors. Filter on the compliance tag in dashboards or query it via the API.

Integrating tags with external systems​

Tags become most powerful when you sync them to external platforms. A typical workflow looks like this:

  1. Define tags in your catalog specification, for example cost_center, environment, compliance.
  2. Query the API with ?include=tags to retrieve the tags for each entity.
  3. Map tags to the external system's format: AWS resource tags, Azure resource labels, or a FinOps tool's cost allocation dimensions.
  4. Apply tags to the external resources using that platform's SDK or API.

This pattern works for cloud provider billing tags (AWS, Azure, GCP), FinOps platforms (CloudHealth, Kubecost, Vantage), inventory and CMDB systems, and custom integrations like Slack notifications enriched with application metadata or automated ticket creation with compliance context.

Best practices​

  • Use descriptive names. cost_center instead of cc, compliance_framework instead of comp.
  • Align across specs. Use the same custom tag key (e.g., "tag": "compliance") everywhere the same concept appears.
  • Add descriptions. Help users understand why they're filling out a tagged field.
  • Use enums. Consistent values make queries and integrations reliable.

Next steps​