Metadata structure and supported versions

Service Catalog uses service definition schemas to store and display relevant metadata about your services. The schemas have built-in validation rules to ensure that only valid values are accepted. You can view warnings in the Definition tab on the Service Catalog side panel for any selected services.

Supported versions

Datadog supports four versions of the service definition schema:

• v3.0 (Beta): Latest version with expanded data model, multi-ownership support, manual dependency declaration, and enhanced features for complex infrastructure.
• v2.2: Supports user annotations for custom metadata and CI pipeline associations to link services with their build processes.
• v2.1: Supports service groupings for improved organization and introduces additional fields for more comprehensive service descriptions.
• v2: Earliest supported version, providing essential fields for basic service metadata and documentation.

Each version builds upon the previous one, adding new functionality while maintaining backwards compatibility. Choose the version that best suits your needs and infrastructure complexity.

Version comparison

The following features are supported in each version:

For detailed information about each version, including full schemas and example YAML files, see the individual version pages in Supported versions.

Add metadata to Service Catalog

Add metadata from the Datadog UI

1. On the Service Catalog page, click Setup & Config.
2. Click Create New Entry.
3. Specify the service you are adding metadata to.
4. Enter details for Team, On-call, Contacts, Documentation, Code repo, and Other links.
5. Switch to YAML or JSON to see the generated code and cURL command.
6. If you have the Service Catalog Write permission, you can submit the metadata by clicking Save Entry or by running the provided cURL command.

Add metadata with automation

Store and edit service definitions in GitHub

Configure the GitHub integration to directly link from where you view the service’s definition in the Service Catalog to where it’s stored and editable in GitHub. Datadog scans for the service.datadog.yaml file at the root of each repository with read permissions.

To install the GitHub integration:

1. Navigate to the integration tile.
2. Click Link GitHub Account in the Repo Configuration tab.

When the GitHub integration is set up for your service definitions, an Edit in GitHub button appears in the service’s Definition tab and links you to GitHub to commit changes.

After you update the YAML files for your repositories, your changes propagate to the Service Catalog. You can register multiple services in one YAML file by creating multiple YAML documents. Separate each document with three dashes (---).

To prevent accidental overwriting, create and modify your service definition files with either the GitHub integration or the Service Definition API endpoints. Updating the same service using both the GitHub and the API may result in unintended overwriting.

Automate service definition updates with Terraform

The Service Catalog provides a service definition as a Terraform resource. Creating and managing services in the Service Catalog through automated pipelines requires Datadog Provider v3.16.0 or later.

Open-source metadata provider

As an alternative to the GitHub integration and Terraform, you can use an open-sourced GitHub Action solution named Datadog Service Catalog Metadata Provider.

Build custom extensions

The extensions field is supported in all versions including v2.0. You can incorporate this custom field into deployment processes to standardize and codify best practices.

schema-version: v2.2
dd-service: web-store
team: shopist
...
extensions:
  shopist.com/release-scheduler:
    release-manager:
      slack: "release-train-shopist"
      schedule: "* * * * *"
      env:
        - name: "staging"
          ci_pipeline: "//domains/examples/apps/hello-joe/config/k8s:release-staging"
          branch: "hello-joe/staging"
          schedule: "* * * * 1"

IDE Plugins

Datadog provides a JSON Schema for service definitions so that when you are editing a service definition in a supporting IDE, features such as autocomplete and validation are provided.

The JSON schema for Datadog service definitions is registered with the open source Schema Store.

Further reading

Additional helpful documentation, links, and articles:

Create and manage service definitions with TerraformEXTERNAL SITE Learn about the Service Definition APIAPI Learn about the GitHub IntegrationDOCUMENTATION Import Backstage YAML files into DatadogBLOG