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.
• (In Preview) Custom entities: Define custom entity types beyond Service, System, Datastore, Queue, and API. Scope scorecards and actions to specific entity types.
• (In Preview) 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.
• (In Preview) 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

  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
  

  apiVersion: v3
  kind: custom.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
  

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

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

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.