--- sidebar_label: Tags in catalogs toc_max_heading_level: 3 doc_id: 7a9f2e3c-5b1d-4a8f-92e1-c6d8b7f3e4a2 description: >- Mark catalog fields as tags to expose them for filtering, search, and external integrations. Learn how to define, use, and query tags via API. keywords: - catalog tags - tagging - metadata filtering - external integrations - API queries - nullplatform --- # 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: ```json { "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. :::tip 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. ```bash curl -L -X GET 'https://api.nullplatform.com/applications/my-app-id?include=tags' \ -H 'Authorization: Bearer ' ``` The response includes only the tagged fields from every catalog specification attached to that entity: ```json { "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. ```json { "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. ```json { "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 - [Define catalog specifications](/docs/catalog/define-catalog-specs): learn how to create specs with tags - [Create and edit catalog instances](/docs/catalog/instances): attach metadata values to entities - [Where catalogs appear in the UI](/docs/catalog/where-catalog-appears): see how tagged fields power dashboards and filters