Tagging Policy

A TaggingPolicy property references a document defining the cost allocation tag taxonomy for an API or platform — including required tag keys such as CostCenter, Environment, Product, and Owner, along with allowed values and compliance requirements. Cost allocation tagging is a foundational FinOps practice, and the FinOps Foundation publishes guidance on tagging policy compliance. Publishing a tagging policy makes cost attribution requirements discoverable by consumers integrating the API into their FinOps workflows.

Also known as: Tag Policy, Cost Allocation Tags, Resource Tagging Policy

Example

- type: TaggingPolicy
  url: https://developers.example.com/billing/tagging

Standards

OpenAPI Initiative OpenAPI Specification 3.1 — Tag Object
Redocly Redocly x-tagGroups vendor extension
AWS AWS Tagging Best Practices
Google Cloud Google Cloud — Resource labels
Microsoft Azure Azure — Tag resources
FinOps Foundation FinOps Foundation — Tagging

Media Types

application/json — Machine-readable tagging policy documents.
application/yaml — Common authoring format for tag taxonomies.

OpenAPI Expression

tags (OpenAPI 3.x) — Global array of tag objects with names and descriptions used to organize operations.
tags (operation) (OpenAPI 3.x) — Operation-level tags grouping endpoints by domain, lifecycle, or audience.
x-tagGroups (Redocly vendor extension) — Groups tags into named sections for navigation in rendered documentation.

Governance Rules

operation-tag-defined (Spectral built-in (spectral:oas)) — Every operation tag must be declared in the global tags array.
oas-tag-description (Spectral built-in (spectral:oas)) — Tags must include a description so their scope is unambiguous.
tags-alphabetical (Spectral built-in (spectral:oas, recommended off by default)) — Tags should be ordered alphabetically for consistency.

Risk & Compliance

Compliance:

SOC 2 CC2.x — accurate cost attribution underpins financial reporting controls
ISO/IEC 27001 A.8 — asset inventory and ownership rely on consistent tagging

Tools

AWS Tag Editor — Tag management
AWS Config — required-tags rule — Tag compliance
Azure Policy — tag policies — Tag compliance
Spectral — OpenAPI tag linting (Apache-2.0)

Suggested Metrics

tag_coverage_percent — Share of resources or operations carrying all required tag keys.
untagged_cost_share — Percentage of monthly spend not attributable due to missing tags.
tag_policy_violations — Count of resources or operations failing the active tagging policy.
tag_key_cardinality — Distinct values per tag key; high cardinality often signals taxonomy drift.

Example Implementations

AWS — Resource tags drive cost allocation reports and Service Control Policy enforcement.
Google Cloud — Labels on resources feed Cloud Billing export and BigQuery analysis.
Microsoft Azure — Azure Policy enforces required tags across subscriptions and management groups.