Metadata structure and supported versions

Software Catalog uses 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 Software Catalog side panel for any selected services.

Supported versions

Datadog supports four versions of the definition schema:

• v3.0: 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 Software Catalog

Add metadata from the Datadog UI

1. On the Software 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 Software 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 definitions in GitHub

Configure the GitHub integration to directly link from where you view the service’s definition in the Software Catalog to where it’s stored and editable in GitHub. Datadog scans for the service.datadog.yaml and entity.datadog.yaml files throughout 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 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 Software 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 definition files with either the GitHub integration or the Definition API endpoints. Updating the same service using both the GitHub and the API may result in unintended overwriting.

Automate definition updates with Terraform

The Software Catalog provides a definition as a Terraform resource. Creating and managing services in the Software 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 Software Catalog Metadata Provider.

Add metadata to endpoints

You can add metadata to APIs through the Datadog UI or API, or use automated pipelines through the GitHub integration or Terraform.

Combine metadata schema v3.0 with OpenAPI definitions by setting kind: api and specifying the owner field:

apiVersion: v3
kind: api
metadata:
  name: API Name
  description: API Description 
  displayName: API Name
  owner: dd-team
spec:
  type: openapi
  interface:
    definition:
      info:
        title: API Name
      openapi: 3.0.2
      paths:
        /api/v2/customers/{id}:
          get:
            summary: get customer information
            operationId: getCustomerInfo
            tags:
              - public
              - important
            parameters:
              - in: path
                name: id
            responses:
              '200':
                description: Successful operation
                content:
                  application/vnd.api+json:
                    schema:
                      type: object
                      properties:
                        data:
                          type: array
                          description: Contains customer information
              '400':
                description: Invalid arguments
              '401':
                description: Unauthorized operation
              '500':
                description: Internal server error

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 definitions so that when you are editing a definition in a supporting IDE, features such as autocomplete and validation are provided.

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

Further reading

Additional helpful documentation, links, and articles:

Create and manage definitions with TerraformEXTERNAL SITE Learn about the Definition APIAPI Learn about the GitHub IntegrationDOCUMENTATION Import Backstage YAML files into DatadogBLOG Improve developer experience and collaboration with Software CatalogBLOG