Entity Model

Documentos > Internal Developer Portal > Software Catalog > Entity Model

This page is not yet available in Spanish. We are working on its translation.
If you have any questions or feedback about our current translation project, feel free to reach out to us!

Overview

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.

Share feedback on new and upcoming Software Catalog features!

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.

Request Access

Key features

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.
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.

Schema structure

You can see the full schema definitions on Github.

V3.0 contains the following changes from v2.2:

schema_version is now apiVersion
kind field is new and defines the type of component: service, queue, datastore, system, or API
dd-service is now metadata.name
team is now owner and additionalOwners if there are multiple teams
lifecycle, tier, languages, and type are now under spec
links, contacts, and description, and tags are now under metadata
application has been enhanced to become its own kind: system. It no longer exists as a discrete field on a service.

Example YAML files

Component of `kind:system`

entity.datadog.yaml

  apiVersion: v3
  kind: system
  metadata:
    name: myapp
    displayName: My App
    tags:
      - tag:value
    links:
      - name: shopping-cart runbook
        type: runbook
        url: https://runbook/shopping-cart
      - name: shopping-cart architecture
        provider: gdoc
        url: https://google.drive/shopping-cart-architecture
        type: doc
      - name: shopping-cart Wiki
        provider: wiki
        url: https://wiki/shopping-cart
        type: doc
      - name: shopping-cart source code
        provider: github
        url: http://github/shopping-cart
        type: repo
    contacts:
      - name: Support Email
        type: email
        contact: team@shopping.com
      - name: Support Slack
        type: slack
        contact: https://www.slack.com/archives/shopping-cart
    owner: myteam
    additionalOwners:
      - name: opsTeam
        type: operator
  integrations:
    pagerduty:
      serviceURL: https://www.pagerduty.com/service-directory/Pshopping-cart
    opsgenie:
      serviceURL: https://www.opsgenie.com/service/shopping-cart
      region: US
  spec:
    components:
      - service:myservice
      - service:otherservice
  extensions:
    datadoghq.com/shopping-cart:
      customField: customValue
  datadog:
    codeLocations:
      - repositoryURL: https://github.com/myorganization/myrepo.git
        paths:
          - path/to/service/code/**
    events:
      - name: "deployment events"
        query: "app:myapp AND type:github"
      - name: "event type B"
        query: "app:myapp AND type:github"
    logs:
      - name: "critical logs"
        query: "app:myapp AND type:github"
      - name: "ops logs"
        query: "app:myapp AND type:github"
    pipelines:
      fingerprints:
        - fp1
        - fp2
  

Component of `kind:library`

entity.datadog.yaml

  apiVersion: v3
  kind: library
  metadata:
    name: my-library
    displayName: My Library
    tags:
      - tag:value
    links:
      - name: shopping-cart runbook
        type: runbook
        url: https://runbook/shopping-cart
      - name: shopping-cart architecture
        provider: gdoc
        url: https://google.drive/shopping-cart-architecture
        type: doc
      - name: shopping-cart Wiki
        provider: wiki
        url: https://wiki/shopping-cart
        type: doc
      - name: shopping-cart source code
        provider: github
        url: http://github/shopping-cart
        type: repo
    contacts:
      - name: Support Email
        type: email
        contact: team@shopping.com
      - name: Support Slack
        type: slack
        contact: https://www.slack.com/archives/shopping-cart
    owner: myteam
    additionalOwners:
      - name: opsTeam
        type: operator
  

Components that are part of multiple systems

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:

entity.datadog.yaml

  apiVersion: v3
  kind: system
  spec:
    components:
      - datastore:orders-postgres
      - datastore:foo-postgres
      - datastore:bar-postgres
  metadata:
    name: managed-postgres
    owner: db-team
  

For the web application (shopping-cart), declare a separate definition for kind:system:

entity.datadog.yaml

  apiVersion: v3
  kind: system
  spec:
    lifecycle: production
    tier: critical
    components:
      - service:shopping-cart-api
      - service:shopping-cart-processor
      - queue:orders-queue
      - datastore:orders-postgres
  metadata:
    name: shopping-cart
    owner: shopping-team
    additionalOwners:
      - name: sre-team
        type: operator
  ---
  apiVersion: v3
  kind: datastore
  metadata:
    name: orders-postgres
    additionalOwners:
      - name: db-team
        type: operator
  ---
  apiVersion: v3
  kind: service
  metadata:
    name: shopping-cart-api
  ---
  apiVersion: v3
  kind: service
  metadata:
    name: shopping-cart-processor
  ---
  

Explicit and implicit metadata inheritance

Explicit inheritance

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 module 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

Schema structure

The full schema is available on GitHub.

Example YAML:

schema-version: v2.2
dd-service: shopping-cart
team: e-commerce
application: shopping-app
tier: "1"
type: web
languages:
  - go
  - python
contacts:
  - type: slack
    contact: https://yourorg.slack.com/archives/e-commerce
  - type: email
    contact: ecommerce@example.com
  - type: microsoft-teams
    contact: https://teams.microsoft.com/example
links:
  - name: Runbook
    type: runbook
    url: http://runbook/shopping-cart
  - name: Source
    type: repo
    provider: github
    url: https://github.com/shopping-cart
  - name: Deployment
    type: repo
    provider: github
    url: https://github.com/shopping-cart
  - name: Config
    type: repo
    provider: github
    url: https://github.com/consul-config/shopping-cart
  - name: E-Commerce Team
    type: doc
    provider: wiki
    url: https://wiki/ecommerce
  - name: Shopping Cart Architecture
    type: doc
    provider: wiki
    url: https://wiki/ecommerce/shopping-cart
  - name: Shopping Cart RFC
    type: doc
    provider: google doc
    url: https://doc.google.com/shopping-cart
tags:
  - business-unit:retail
  - cost-center:engineering
integrations:
  pagerduty:
    service-url: https://www.pagerduty.com/service-directory/PSHOPPINGCART
  opsgenie:
    service-url: "https://www.opsgenie.com/service/uuid"
    region: "US"
ci-pipeline-fingerprints:
  - id1
  - id2
extensions:
  additionalProperties:
    customField1: customValue1
    customField2: customValue2

API reference documentation

To create, get, and delete service definitions, see the Service Definitions API reference.
To create, get, and delete definitions for new component types like systems, datastores, and queues, see the Software Catalog API reference.
To create and update service scorecard rules and outcomes, see the Service Scorecards API reference.

Key features

New UI elements such as service groupings and fields for application, tier, and lifecycle
Application and Teams can be used as grouping variables in Software Catalog
Lifecycle field indicates development stage to differentiate between production, experimental, or deprecated services
Tier field indicates service criticality for prioritizing during incident triage

Schema structure

The full schema is available on GitHub.

Example YAML:

schema-version: v2.1
dd-service: delivery-state-machine
team: serverless
application: delivery-state-machine
tier: tier0
lifecycle: production
contacts:
  - type: slack
    contact: https://datadogincidents.slack.com/archives/C01EWN6319S
links:
  - name: Demo Dashboard
    type: dashboard
    url: https://app.datadoghq.com/dashboard/krp-bq6-362
  - name: Source
    provider: github
    url: https://github.com/DataDog/shopist-serverless/tree/main/delivery-state-machine
    type: repo
  - name: Deployment
    provider: github
    url: https://github.com/DataDog/shopist-serverless/blob/main/delivery-state-machine/serverless.yml
    type: repo
  - name: Datadog Doc
    provider: link
    url: https://docs.datadoghq.com/
    type: doc
tags:
  - "app:serverless-delivery"
  - "tier:3"
  - "business-unit:operations"

API reference documentation

To create, get, and delete service definitions, see the Service Definitions API reference.
To create, get, and delete definitions for new component types like systems, datastores, and queues, see the Software Catalog API reference.
To create and update service scorecard rules and outcomes, see the Service Scorecards API reference.

Key features

Basic service metadata
Team associations
Contact information
External links

Schema structure

The full schema is available on GitHub.

Example YAML:

schema-version: v2
dd-service: delivery-api
team: distribution-management
contacts:
  - type: slack
    contact: https://datadogincidents.slack.com/archives/C01EWN6319S
links:
  - name: Demo Dashboard
    type: dashboard
    url: https://app.datadoghq.com/dashboard/krp-bq6-362
repos:
  - name: Source
    provider: github
    url: https://github.com/DataDog/shopist/tree/prod/rails-storefront
docs:
  - name: Datadog Doc
    provider: link
    url: https://docs.datadoghq.com/
tags: []
integrations:
  pagerduty: https://datadog.pagerduty.com/service-directory/PXZNFXP

API reference documentation

To create, get, and delete service definitions, see the Service Definitions API reference.
To create, get, and delete definitions for new component types like systems, datastores, and queues, see the Software Catalog API reference.
To create and update service scorecard rules and outcomes, see the Service Scorecards API reference.

Build custom extensions

Custom extensions are in Limited Availability.

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

service.datadog.yaml

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: "ci-tool://shopist/k8s/staging-deploy"
          branch: "main"
          schedule: "0 9 * * 1"

Schema validation through IDE plugin

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.