This product is not supported for your selected Datadog site. ().
Entity Model schema v3.0 is not available in the selected site at this time.
Overview
Software Catalog uses definition schemas to store and display relevant metadata about your entities. 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:
Feature
v3.0
v2.2
v2.1
v2.0
Basic Metadata
Service Groupings
User Annotations
CI Pipeline Associations
Expanded Data Model
Multi-ownership
Manual Dependency Declaration
For detailed information about each version, including full schemas and example YAML files, see the individual version pages in Supported versions.
Version details
Opt in to the Preview for the latest version of Software Catalog.
Expanded data model: v3.0 supports multiple kinds of entities. You can organize your systems using various components such as systems, services, queues, and datastores.
Multi-ownership: You can assign multiple owners to any objects defined through the v3.0 schema to specify multiple points of contact.
Enhanced relationship mapping: With APM and USM data, you can automatically detect dependencies among components. v3.0 supports manual declaration to augment auto-detected system topology to ensure a complete overview of how components interact within your systems.
Inheritance of system metadata: Components within a system automatically inherit the system’s metadata. It’s no longer necessary to declare metadata for all related components one-by-one as in v2.1 and v2.2.
Precise code location: Add the mapping of your code location for your service. The codeLocations section in v3.0 specifies the locations of the code with the repository that contains the code and its associated paths. The paths attribute is a list of globs that should match paths in the repository.
Filtered logs & events: Declare saved logs and event queries for a system through the logs and events sections and view results on the System page.
Custom entities: Define custom entity types beyond Service, System, Datastore, Queue, and API. Scope scorecards and actions to specific entity types.
(Upcoming) Integrations: Integrate with third-party tools to dynamically source information related to your components (for example, GitHub pull requests, PagerDuty incidents, and GitLab pipelines). Report on and write scorecard rules against any third-party source.
(Upcoming) Group by product or domain: Organize components by product, enabling multiple layers of hierarchical grouping.
If a single component is part of multiple systems, you must specify that component in the YAML for each system. For example, if the datastore orders-postgres is a component of both a postgres fleet and a web application, specify two YAMLs:
For the postgres fleet (managed-postgres), specify a definition for kind:system:
The inheritFrom field instructs the ingestion pipeline to inherit metadata from the entity’s metadata referenced by <entity_kind>:<name>.
entity.datadog.yaml
inheritFrom:<entity_kind>:<name>
Implicit inheritance
Components (kind:service, kind:datastore, kind:queue, kind:ui) inherit all metadata from the system that they belong to under the following conditions:
There is only one system defined in the YAML file.
The clause inheritFrom:<entity_kind>:<name> is absent in the YAML file.
Migrating to v3.0
v3.0 supports the same methods of creating metadata as previous versions, including Github, API, Terraform, Backstage, ServiceNow, and the UI. However, there are new API endpoints and a new Terraform resource for v3.0.
API reference documentation
To create, get, and delete definitions for all entity types like endpoints, systems, datastores, and queues, see the Software Catalog API reference.
Key features
User annotations
Overwriting auto-detected service type and languages using type and languages
Associate CI pipeline with a service using ci-pipeline-fingerprints
Less restrictive validation logic for contact.type and link.type
Custom extensions are in Limited Availability for all schema versions.
Custom extensions allow you to attach organization-specific metadata to entities, enabling support for custom tooling and workflows. For example, use the extensions field to include release notes, compliance tags, or ownership models in your entity definitions.
Datadog also supports specific extension keys for certain features. These include:
datadoghq.com/dora-metrics: Define source code path patterns for filtering Git commits when calculating DORA metrics.
datadoghq.com/cd-visibility: Control which commits are considered as part of a deployment in CD Visibility.
The following example defines a custom extension used to manage release scheduling across environments:
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.
