From 306ca2f2ec0b6bd9870dec62fcb84ac3c81600b4 Mon Sep 17 00:00:00 2001
From: dgreen15 <daniel.green@datadoghq.com>
Date: Fri, 11 Apr 2025 15:39:29 -0400
Subject: [PATCH 1/9] Update _index.md
---
content/en/software_catalog/service_definitions/_index.md | 3 +++
1 file changed, 3 insertions(+)
diff --git a/content/en/software_catalog/service_definitions/_index.md b/content/en/software_catalog/service_definitions/_index.md
index a58e3b51c4349..12571952cde38 100644
--- a/content/en/software_catalog/service_definitions/_index.md
+++ b/content/en/software_catalog/service_definitions/_index.md
@@ -32,6 +32,9 @@ further_reading:
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.
+{{< callout url="https://www.datadoghq.com/product-preview/internal-developer-portal/" d_target="#signupModal" btn_hidden="false" header="Opt in to the preview for the latest version of Software Catalog!" >}}
+{{< /callout >}}
+
## Supported versions
Datadog supports four versions of the definition schema:
From 7cfab30180d70d971526818c6fbcf785bfbb86e5 Mon Sep 17 00:00:00 2001
From: dgreen15 <daniel.green@datadoghq.com>
Date: Fri, 11 Apr 2025 15:45:53 -0400
Subject: [PATCH 2/9] Update v3-0.md
---
.../service_definitions/v3-0.md | 57 +++++++++++++++++--
1 file changed, 52 insertions(+), 5 deletions(-)
diff --git a/content/en/software_catalog/service_definitions/v3-0.md b/content/en/software_catalog/service_definitions/v3-0.md
index 0ba2fd4d322ee..de0b77d67986c 100644
--- a/content/en/software_catalog/service_definitions/v3-0.md
+++ b/content/en/software_catalog/service_definitions/v3-0.md
@@ -26,15 +26,24 @@ Schema v3.0 introduces several new features and enhancements to provide more fle
## 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.
+- **(GA) 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.
+- **(GA) 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.
+- **(GA) 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.
+- **(GA)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][4] that should match paths in the repository.
+- **(GA) 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][4] that should match paths in the repository.
+
+- **(PREVIEW) Custom Entities**: Define your own entity types beyond Service, System, Datastore, Queue, and API. Scope scorecards and actions to only apply to specific entity types.
+
+- **(PREVIEW) Integrations**: Direct integrations with third-party tools to dynamically source information related to your components (e.g. Github pull requests, PagerDuty incidents, Gitlab pipelines, etc.). Report on and write scorecard rules against any third-party source
+
+- **(PREVIEW) Group by product or domain**: You can group systems or other components by products, offering multiple layers of hierachical grouping.
+
+{{< callout url="https://forms.gle/fwzarcSww6By7tn39" d_target="#signupModal" btn_hidden="false" header="Opt in to the preview for the latest version of Software Catalog!" >}}
+{{< /callout >}}
## Metadata Schema v3.0
@@ -112,6 +121,44 @@ datadog:
- fp2
{{< /code-block >}}
+### Example YAML for `kind:custom.library`
+{{< code-block lang="yaml" filename="entity.datadog.yaml" collapsible="true" >}}
+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
+{{< /code-block >}}
+
### 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:
From 5a167d8c788294ba5d824736ea7a6717faa106c3 Mon Sep 17 00:00:00 2001
From: dgreen15 <daniel.green@datadoghq.com>
Date: Fri, 11 Apr 2025 15:46:32 -0400
Subject: [PATCH 3/9] Update _index.md
---
content/en/software_catalog/service_definitions/_index.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content/en/software_catalog/service_definitions/_index.md b/content/en/software_catalog/service_definitions/_index.md
index 12571952cde38..1081435a5121c 100644
--- a/content/en/software_catalog/service_definitions/_index.md
+++ b/content/en/software_catalog/service_definitions/_index.md
@@ -32,7 +32,7 @@ further_reading:
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.
-{{< callout url="https://www.datadoghq.com/product-preview/internal-developer-portal/" d_target="#signupModal" btn_hidden="false" header="Opt in to the preview for the latest version of Software Catalog!" >}}
+{{< callout url="https://forms.gle/fwzarcSww6By7tn39" d_target="#signupModal" btn_hidden="false" header="Opt in to the preview for the latest version of Software Catalog!" >}}
{{< /callout >}}
## Supported versions
From 4666a40db827d32d0e4eb60b268927b49e06627c Mon Sep 17 00:00:00 2001
From: dgreen15 <daniel.green@datadoghq.com>
Date: Thu, 17 Apr 2025 13:25:44 -0400
Subject: [PATCH 4/9] Update
content/en/software_catalog/service_definitions/_index.md
Co-authored-by: domalessi <111786334+domalessi@users.noreply.github.com>
---
content/en/software_catalog/service_definitions/_index.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content/en/software_catalog/service_definitions/_index.md b/content/en/software_catalog/service_definitions/_index.md
index 1081435a5121c..ef605c40db326 100644
--- a/content/en/software_catalog/service_definitions/_index.md
+++ b/content/en/software_catalog/service_definitions/_index.md
@@ -32,7 +32,7 @@ further_reading:
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.
-{{< callout url="https://forms.gle/fwzarcSww6By7tn39" d_target="#signupModal" btn_hidden="false" header="Opt in to the preview for the latest version of Software Catalog!" >}}
+{{< callout url="https://forms.gle/fwzarcSww6By7tn39" d_target="#signupModal" btn_hidden="false" header="Opt in to the Preview for the latest version of Software Catalog." >}}
{{< /callout >}}
## Supported versions
From 21bf4afd68f76533846c267d0d40569cc6a8f179 Mon Sep 17 00:00:00 2001
From: dgreen15 <daniel.green@datadoghq.com>
Date: Thu, 17 Apr 2025 13:26:04 -0400
Subject: [PATCH 5/9] Update
content/en/software_catalog/service_definitions/v3-0.md
Co-authored-by: domalessi <111786334+domalessi@users.noreply.github.com>
---
content/en/software_catalog/service_definitions/v3-0.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content/en/software_catalog/service_definitions/v3-0.md b/content/en/software_catalog/service_definitions/v3-0.md
index de0b77d67986c..91cca24337914 100644
--- a/content/en/software_catalog/service_definitions/v3-0.md
+++ b/content/en/software_catalog/service_definitions/v3-0.md
@@ -36,7 +36,7 @@ Schema v3.0 introduces several new features and enhancements to provide more fle
- **(GA) 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][4] that should match paths in the repository.
-- **(PREVIEW) Custom Entities**: Define your own entity types beyond Service, System, Datastore, Queue, and API. Scope scorecards and actions to only apply to specific entity types.
+- **(In Preview) Custom Entities**: Define custom entity types beyond Service, System, Datastore, Queue, and API. Scope scorecards and actions to specific entity types.
- **(PREVIEW) Integrations**: Direct integrations with third-party tools to dynamically source information related to your components (e.g. Github pull requests, PagerDuty incidents, Gitlab pipelines, etc.). Report on and write scorecard rules against any third-party source
From afd2c2044e158b6b7dc78127be67df84e31ec183 Mon Sep 17 00:00:00 2001
From: dgreen15 <daniel.green@datadoghq.com>
Date: Thu, 17 Apr 2025 13:26:15 -0400
Subject: [PATCH 6/9] Update
content/en/software_catalog/service_definitions/v3-0.md
Co-authored-by: domalessi <111786334+domalessi@users.noreply.github.com>
---
content/en/software_catalog/service_definitions/v3-0.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content/en/software_catalog/service_definitions/v3-0.md b/content/en/software_catalog/service_definitions/v3-0.md
index 91cca24337914..83ed1569275ee 100644
--- a/content/en/software_catalog/service_definitions/v3-0.md
+++ b/content/en/software_catalog/service_definitions/v3-0.md
@@ -42,7 +42,7 @@ Schema v3.0 introduces several new features and enhancements to provide more fle
- **(PREVIEW) Group by product or domain**: You can group systems or other components by products, offering multiple layers of hierachical grouping.
-{{< callout url="https://forms.gle/fwzarcSww6By7tn39" d_target="#signupModal" btn_hidden="false" header="Opt in to the preview for the latest version of Software Catalog!" >}}
+{{< callout url="https://forms.gle/fwzarcSww6By7tn39" d_target="#signupModal" btn_hidden="false" header="Opt in to the Preview for the latest version of Software Catalog." >}}
{{< /callout >}}
## Metadata Schema v3.0
From 458faebae06682c958ed503ce223c03ee33f9a6b Mon Sep 17 00:00:00 2001
From: dgreen15 <daniel.green@datadoghq.com>
Date: Thu, 17 Apr 2025 13:27:06 -0400
Subject: [PATCH 7/9] Update v3-0.md
---
.../software_catalog/service_definitions/v3-0.md | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/content/en/software_catalog/service_definitions/v3-0.md b/content/en/software_catalog/service_definitions/v3-0.md
index 83ed1569275ee..7288cd9a87d2a 100644
--- a/content/en/software_catalog/service_definitions/v3-0.md
+++ b/content/en/software_catalog/service_definitions/v3-0.md
@@ -26,21 +26,21 @@ Schema v3.0 introduces several new features and enhancements to provide more fle
## Key features
-- **(GA) 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.
+- **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.
-- **(GA) Multi-ownership**: You can assign multiple owners to any objects defined through the v3.0 schema to specify multiple points of contact.
+- **Multi-ownership**: You can assign multiple owners to any objects defined through the v3.0 schema to specify multiple points of contact.
-- **(GA) 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.
+- **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.
-- **(GA)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.
+- **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.
-- **(GA) 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][4] that should match paths in the repository.
+- **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][4] 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) Custom entities**: Define custom entity types beyond Service, System, Datastore, Queue, and API. Scope scorecards and actions to specific entity types.
-- **(PREVIEW) Integrations**: Direct integrations with third-party tools to dynamically source information related to your components (e.g. Github pull requests, PagerDuty incidents, Gitlab pipelines, etc.). Report on and write scorecard rules against any third-party source
+- **(In Preview) Integrations**: Direct integrations with third-party tools to dynamically source information related to your components (e.g. Github pull requests, PagerDuty incidents, Gitlab pipelines, etc.). Report on and write scorecard rules against any third-party source
-- **(PREVIEW) Group by product or domain**: You can group systems or other components by products, offering multiple layers of hierachical grouping.
+- **(In Preview) Group by product or domain**: You can group systems or other components by products, offering multiple layers of hierachical grouping.
{{< callout url="https://forms.gle/fwzarcSww6By7tn39" d_target="#signupModal" btn_hidden="false" header="Opt in to the Preview for the latest version of Software Catalog." >}}
{{< /callout >}}
From a8216e965250204f73893602c614688b3e81ba24 Mon Sep 17 00:00:00 2001
From: domalessi <111786334+domalessi@users.noreply.github.com>
Date: Thu, 17 Apr 2025 13:30:37 -0400
Subject: [PATCH 8/9] Apply suggestions from code review
---
content/en/software_catalog/service_definitions/v3-0.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/content/en/software_catalog/service_definitions/v3-0.md b/content/en/software_catalog/service_definitions/v3-0.md
index 7288cd9a87d2a..a33751c99134d 100644
--- a/content/en/software_catalog/service_definitions/v3-0.md
+++ b/content/en/software_catalog/service_definitions/v3-0.md
@@ -38,9 +38,9 @@ Schema v3.0 introduces several new features and enhancements to provide more fle
- **(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**: Direct integrations with third-party tools to dynamically source information related to your components (e.g. Github pull requests, PagerDuty incidents, Gitlab pipelines, etc.). Report on and write scorecard rules against any third-party source
+- **(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**: You can group systems or other components by products, offering multiple layers of hierachical grouping.
+- **(In Preview) Group by product or domain**: Organize components by product, enabling multiple layers of hierarchical grouping.
{{< callout url="https://forms.gle/fwzarcSww6By7tn39" d_target="#signupModal" btn_hidden="false" header="Opt in to the Preview for the latest version of Software Catalog." >}}
{{< /callout >}}
From b94f741e7a5250adc2e6a079191647ca3121ec65 Mon Sep 17 00:00:00 2001
From: domalessi <111786334+domalessi@users.noreply.github.com>
Date: Thu, 17 Apr 2025 13:31:44 -0400
Subject: [PATCH 9/9] Update
content/en/software_catalog/service_definitions/v3-0.md
---
content/en/software_catalog/service_definitions/v3-0.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content/en/software_catalog/service_definitions/v3-0.md b/content/en/software_catalog/service_definitions/v3-0.md
index a33751c99134d..c26a920b4c92c 100644
--- a/content/en/software_catalog/service_definitions/v3-0.md
+++ b/content/en/software_catalog/service_definitions/v3-0.md
@@ -34,7 +34,7 @@ Schema v3.0 introduces several new features and enhancements to provide more fle
- **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][4] that should match paths in the repository.
+- **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][4] 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.