Overview

Schema v3.0 is the latest version of the Definition schema and is in Preview. It 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. Learn more about how this addition improves your experience with Datadog Code Analysis.

Metadata Schema v3.0 (in Preview)

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

Example YAML for kind:system

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:

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:

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

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.

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 Service Catalog schema v3.0BLOG