Manage Service Catalog entries efficiently with the Service Definition JSON Schema

The Datadog Service Catalog helps you centralize knowledge about your organization’s services, giving you a single source of truth to improve collaboration, service governance, and incident response. Datadog automatically detects your APM-instrumented services and writes their metadata to a service definition before adding them to the catalog. You can also create your own service definitions—as JSON or YAML files—to manually register new services or update existing ones with contact information, on-call schedules, and other key metadata. In this post, we’ll show you how the Service Definition JSON Schema helps you efficiently create and update Service Catalog records by leveraging your IDE’s abilities to:

• autocomplete data in your service definitions
• automatically validate your service definitions
• POST your service definitions to the Datadog Service Definition API

Finally, we’ll show you how to add custom metadata to your service definitions.

Create and maintain service definition files in your IDE

The Service Definition JSON Schema follows the widely used JSON Schema specification and describes a valid service definition in a machine-readable format, which enables your IDE to autocomplete and validate your metadata as you edit it. We’ve contributed the schema to the open source JSON Schema Store, where many IDEs—including VS Code and IntelliJ IDEA—can automatically retrieve it. This means that teams can manage Service Catalog records using the same tools and practices—including version control and code reviews—they already use for source code and configuration files.

The schema includes information that tells the IDEs which filenames it applies to—service.datadog.yaml, service.datadog.yml, and service.datadog.json. Below, you can see a sample service.datadog.yaml file that includes links to the service’s Slack channel, dashboard, code repositories, documentation, and PagerDuty schedule.

---
schema-version: v2
dd-service: my-service
team: dba
contacts:
  - type: slack
    contact: https://my-org.slack.com/archives/AAAA0000
links:
  - name: Overview Dashboard
    type: dashboard
    url: https://app.datadoghq.com/dashboard/AAA-000-AAA
repos:
  - name: Source
    provider: github
    url: https://github.com/DataDog/AAAA0000/my-service
  - name: Helm Chart
    url: https://github.com/DataDog/AAAA0000/k8s/my-service
docs:
  - name: My Service Docs
    provider: link
    url: https://docs.my-service.my-org.com/
tags:
  - "criticality: 2"
  - "business_unit: e-commerce"
integrations:
  pagerduty: https://my-org.pagerduty.com/service-directory/my-service

Use autocomplete to efficiently manage your service definitions

Autocomplete is a vital tool for engineers to quickly and accurately create and edit source code and configuration files. The Service Definition JSON Schema enables IDEs to autocomplete entries as you work with your service definition files. This makes it easy to create complete, accurate data—without stopping to reference any documentation—and gives you the efficient experience you expect from your IDE.

For example, the video below shows how VS Code autocompletes the names of the dictionary keys in the service.datadog.yaml file. When the user accepts the autocomplete option for the contacts key, the IDE automatically creates the keys for that list’s required fields—type and contact.

IDEs automatically download the schema from the JSON Schema Store, so your autocomplete hints will always be up to date. For example, if a future version of the schema includes a property that does not exist today, your IDE will automatically present that property as an autocomplete option.

Rely on your IDE to automatically validate your service definitions

A mistake in a service definition—such as a missing value or an incorrect data type—could cause you to create a service with invalid data, or introduce an error into the metadata of an existing service. The screenshot below shows a Service Catalog page displaying an error message that indicates an incorrectly formatted URL in the contacts property of a service definition. Service Catalog has successfully registered the service, but users won’t be able to navigate to the relevant team’s Slack channel as expected.

To prevent an error like this from making its way into the Service Catalog, the Service Definition JSON Schema enables your IDE to validate your data as you edit the file. The video below shows validation messages appearing in VS Code as the user introduces an error into the service.datadog.yaml file.

Automatic validation prompts you to correct any problems before you save the file, commit it to a source code repository, and POST the revised data to the Service Definition API.

POST service definitions using your IDE’s REST/HTTP client

Once you have a valid service definition file, you can POST it to the Service Definition API to create or update the relevant record in the Service Catalog. Many IDEs provide an HTTP client that offers this capability, including VS Code’s REST client extension and IntelliJ IDEA’s HTTP client.

The video below shows a user posting service metadata to the Service Definition API using VS Code. This API will read the data from the service.datadog.json file and create a service named my-service, or update that service if it already exists in the Service Catalog.

See your IDE’s documentation for specific information on how to execute HTTP calls to REST endpoints and the Service Definition API documentation for examples of how to format your POST request.

Use the schema’s extensions field to store custom metadata

The Service Definition JSON Schema’s extensions field allows you to address your organization’s unique needs by including custom metadata in your service definitions. The data in the extensions field is optional, and isn’t validated by the IDE nor visible in the Service Catalog UI. But if you have custom data that you’ll access programmatically—as opposed to viewing it within Service Catalog—you can use this field to store that data within your service definition.

For example, you can use the extensions field to identify the service’s owner—as it’s known to your HR software—in order to attribute and track that team’s work in their employment records. The code snippet below shows a service definition that identifies ​​internal-team-id: sre in the extensions field.

---
schema-version: v2
dd-service: my-service
extensions:
  my-org/metadata:
    department: engineering
    internal-team-id: sre

Leverage your existing tools for Service Catalog management

The Service Definition JSON Schema brings autocomplete and data validation to your existing IDE, so you don’t need to memorize the structure of the data or refer to any documentation as you create and update your service definitions. To get started, make sure your IDE supports YAML or JSON—either out of the box or through an extension—and has an HTTP/REST extension enabled so you can POST your metadata to the Service Definition API.

Coming soon, we’ll extend the Service Definition JSON Schema to display rich error messages and allow you to create custom validation rules. And we’ll add more schemas to the Datadog JSON Schema repository.

See the documentation for more information about how to use the Service Catalog and the Service Definition JSON Schema. If you’re not already using Datadog, sign up for a free 14-day trial.