--- title: Entity Model description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > Internal Developer Portal > Software Catalog > Entity Model --- # Entity Model {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site). (). {% /alert %} {% /callout %} {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com {% alert level="danger" %} Entity Model schema v3.0 is not available in the selected site at this time. {% /alert %} {% /callout %} ## Overview{% #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. {% image source="https://docs.dd-static.net/images/tracing/internal_developer_portal/entity-model-flow-chart.93d852a20c59cba69bfcf013995f5a2d.png?auto=format" alt="A flow chart showing how components of Software Catalog connect with each other and with your cloud environment " /%} ## Supported versions{% #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{% #version-comparison %} The following features are supported in each version: | Feature | v3.0 | v2.2 | v2.1 | v2.0 | | ----------------------------- | ---- | ---- | ---- | ---- | | Basic Metadata | yes | yes | yes | yes | | Service Groupings | yes | yes | yes | | User Annotations | yes | yes | | CI Pipeline Associations | yes | yes | | Expanded Data Model | yes | | Multi-ownership | yes | | Manual Dependency Declaration | yes | For detailed information about each version, including full schemas and example YAML files, see the individual version pages in Supported versions. ## Version details{% #version-details %} {% callout %} ##### Opt in to the Preview for the latest version of Software Catalog. [Request Access](https://forms.gle/fwzarcSww6By7tn39) {% /callout %} {% tab title="v3.0" %} ### Key features{% #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](https://en.wikipedia.org/wiki/Glob_%28programming%29) 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. ### Schema structure{% #schema-structure %} You can see the [full schema definitions on Github](https://github.com/DataDog/schema/tree/main/service-catalog/v3). 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{% #example-yaml-files %} {% collapsible-section #id-for-anchoring %} #### Component of `kind:system` In the `entity.datadog.yaml` file: ```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 ``` {% /collapsible-section %} {% collapsible-section #id-for-anchoring %} #### Component of `kind:library` In the `entity.datadog.yaml` file: ```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 ``` {% /collapsible-section %} {% collapsible-section #id-for-anchoring %} #### 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`: In the `entity.datadog.yaml` file: ```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`: In the `entity.datadog.yaml` file: ```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 --- ``` {% /collapsible-section %} ### Explicit and implicit metadata inheritance{% #explicit-and-implicit-metadata-inheritance %} #### Explicit inheritance{% #explicit-inheritance %} The `inheritFrom` field instructs the ingestion pipeline to inherit metadata from the entity's metadata referenced by `:`. In the `entity.datadog.yaml` file: ```yaml inheritFrom:: ``` #### Implicit inheritance{% #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::` is absent in the YAML file. ### Migrating to v3.0{% #migrating-to-v30 %} 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](https://docs.datadoghq.com/api/latest/software-catalog/) and a new [Terraform resource](https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/software_catalog) for v3.0. ### API reference documentation{% #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](https://docs.datadoghq.com/api/latest/software-catalog/). {% /tab %} {% tab title="v2.2" %} ### Key features{% #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{% #schema-structure %} The [full schema is available on GitHub](https://github.com/DataDog/schema/tree/main/service-catalog/v2.2). Example YAML: ```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{% #api-reference-documentation %} - To create, get, and delete service definitions, see the [Service Definitions API reference](https://docs.datadoghq.com/api/latest/service-definition/). - To create, get, and delete definitions for new component types like systems, datastores, and queues, see the [Software Catalog API reference](https://docs.datadoghq.com/api/latest/software-catalog/). - To create and update service scorecard rules and outcomes, see the [Service Scorecards API reference](https://docs.datadoghq.com/api/latest/service-scorecards/). {% /tab %} {% tab title="v2.1" %} ### Key features{% #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{% #schema-structure %} The [full schema is available on GitHub](https://github.com/DataDog/schema/tree/main/service-catalog/v2.1). Example YAML: ```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{% #api-reference-documentation %} - To create, get, and delete service definitions, see the [Service Definitions API reference](https://docs.datadoghq.com/api/latest/service-definition/). - To create, get, and delete definitions for new component types like systems, datastores, and queues, see the [Software Catalog API reference](https://docs.datadoghq.com/api/latest/software-catalog/). - To create and update service scorecard rules and outcomes, see the [Service Scorecards API reference](https://docs.datadoghq.com/api/latest/service-scorecards/). {% /tab %} {% tab title="v2.0" %} ### Key features{% #key-features %} - Basic service metadata - Team associations - Contact information - External links ### Schema structure{% #schema-structure %} The [full schema is available on GitHub](https://github.com/DataDog/schema/tree/main/service-catalog/v2). Example YAML: ```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{% #api-reference-documentation %} - To create, get, and delete service definitions, see the [Service Definitions API reference](https://docs.datadoghq.com/api/latest/service-definition/). - To create, get, and delete definitions for new component types like systems, datastores, and queues, see the [Software Catalog API reference](https://docs.datadoghq.com/api/latest/software-catalog/). - To create and update service scorecard rules and outcomes, see the [Service Scorecards API reference](https://docs.datadoghq.com/api/latest/service-scorecards/). {% /tab %} ## Build custom extensions{% #build-custom-extensions %} {% alert level="info" %} Custom extensions are in Limited Availability for all schema versions. {% /alert %} 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](https://docs.datadoghq.com/dora_metrics/setup/#handling-multiple-services-in-the-same-repository). - `datadoghq.com/cd-visibility`: Control which commits are considered as part of a deployment in [CD Visibility](https://docs.datadoghq.com/continuous_delivery/features/code_changes_detection?tab=github#specify-service-file-path-patterns). The following example defines a custom extension used to manage release scheduling across environments: In the `service.datadog.yaml` file: ```yaml apiVersion: v3 kind: system metadata: name: payment-platform displayName: "Payment Platform" links: - name: Runbook type: runbook url: https://runbook/payment-platform contacts: - name: Payment Team type: team contact: https://www.slack.com/archives/payments owner: payments-team additionalOwners: - name: finance-team type: stakeholder spec: components: - service:payment-api - queue:payment-requests - datastore:payment-db 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{% #schema-validation-through-ide-plugin %} Datadog provides a [JSON Schema](http://json-schema.org/) for definitions so that when you are editing a definition in a [supporting IDE](https://www.schemastore.org), features such as autocomplete and validation are provided. {% image source="https://docs.dd-static.net/images/tracing/software_catalog/ide_plugin.e3e279ddcbfa074b445c0e1701f2f333.png?auto=format" alt="VSCode recognizing problem to fix" /%} The [JSON schema for Datadog definitions](https://raw.githubusercontent.com/DataDog/schema/refs/heads/main/service-catalog/service.schema.json) is registered with the open source [Schema Store](https://www.schemastore.org). ## Further reading{% #further-reading %} - [Create and manage definitions with Terraform](https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/service_definition_yaml) - [Learn about the Definition API](https://docs.datadoghq.com/api/latest/service-definition/) - [Learn about the GitHub Integration](https://docs.datadoghq.com/integrations/github) - [Import Backstage YAML files into Datadog](https://www.datadoghq.com/blog/service-catalog-backstage-yaml/) - [Improve developer experience and collaboration with Service Catalog schema version 3.0](https://www.datadoghq.com/blog/service-catalog-schema-v3/) - [Model your architecture with custom entities in the Datadog Software Catalog](https://www.datadoghq.com/blog/software-catalog-custom-entities/)