Definition Schema v3.0

Overview

Schema v3.0 introduces several new features and enhancements to provide more flexibility and detailed definitions.

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: You can 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.

Metadata Schema v3.0

The Entity Definition Schema is a structure that contains basic information about an entity. See the full schema on GitHub.

In v3.0, the application field has been replaced with system in the documentation to match the updated public schema terminology.

Example YAML for 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

Specify common 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

entity.datadog.yaml

inheritFrom:<entity_kind>:<name>

The inheritFrom field instructs the ingestion pipeline to inherit metadata from the entity’s metadata referenced by <entity_kind>:<name>.

Note: The entity reference only applies to an entity from the same YAML file.

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.

v3.0 API endpoints

To view v3.0 API endpoints, see the latest API documentation.

Schema Overview

You can see the full schema definitions on Github. Here is an overview of the schema structure:

  • api_version is the schema version: 2.0, 2.1, 3.0
  • kind field is new and defines the type of component: service, queue, datastore, system, or API
  • metadata includes naming, description, ownership, links (documentation, runbooks, repositories, contacts, dashboards), and tags
  • spec includes tier, lifecycle, language, type, and relationships to other components
  • integrations includes connections to PagerDuty & OpsGenie
  • datadog includes ways to filter and link to other Datadog data, such as code locations, pipelines, logs, and events

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.

You can see the full schema definitions on Github. V3.0 contains the following changes from v2.2:

  • schema_version is now api_version
  • 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

Further reading

Additional helpful documentation, links, and articles:

Create and manage definitions with TerraformEXTERNAL SITE more more Learn about the Definition APIAPI more more Learn about the GitHub IntegrationDOCUMENTATION more more Import Backstage YAML files into DatadogBLOG more more Improve developer experience and collaboration with Service Catalog schema v3.0BLOG more more