schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/DataDog/schema/main/service-catalog/v2/schema.json",
  "title": "Service Definition Schema v2",
  "description": "A service definition for providing additional service metadata and integrations v2",
  "type": "object",
  "properties": {
    "schema-version": {
      "description": "Schema version being used",
      "examples": ["v2"],
      "type": "string",
      "default": "v2",
      "enum": ["v2"]
    },
    "dd-service": {
      "description": "Unique identifier of the service. Must be unique across all services, and is used to match with a service in Datadog",
      "examples": ["my-service"],
      "type": "string",
      "minLength": 1
    },
    "team": {
      "description": "Team that owns the service",
      "examples": ["my-team"],
      "type": "string",
      "minLength": 1
    },
    "dd-team": {
      "description": "Experimental feature. A Team handle that matches a Team in the Datadog Teams product.",
      "examples": ["my-team"],
      "type": "string",
      "minLength": 1,
      "pattern": "[^A-Z ]+"
    },
    "contacts": {
      "description": "A list of contacts related to the services. ",
      "type": "array",
      "items": {
        "$ref": "#/$defs/contact"
      }
    },
    "links": {
      "description": "A list of links related to the services. ",
      "type": "array",
      "items": {
        "$ref": "#/$defs/link"
      }
    },
    "repos": {
      "description": "A list of code repositories related to the services. ",
      "type": "array",
      "items": {
        "$ref": "#/$defs/repo"
      }
    },
    "docs": {
      "description": "A list of documentations related to the services. ",
      "type": "array",
      "items": {
        "$ref": "#/$defs/doc"
      }
    },
    "tags": {
      "description": "A set of custom tags",
      "examples": [["my:tag"]],
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "integrations": {
      "description": "Third party integrations that Datadog supports",
      "type": "object",
      "properties": {
        "pagerduty": {
          "description": "pagerduty service url for the service",
          "examples": ["https://my-org.pagerduty.com/service-directory/PMyService"],
          "type": "string",
          "pattern": "^(https?://)?[a-zA-Z\\d_\\-.]+\\.pagerduty\\.com/service-directory/(P[a-zA-Z\\d_\\-]+)/?$"
        },
        "opsgenie": {
          "description": "Opsgenie integration for the service",
          "type": "object",
          "properties": {
            "service-url": {
              "description": "Opsgenie Service URL",
              "examples": ["https://www.opsgenies.com/service/123e4567-e89b-12d3-a456-426614174000"],
              "type": "string",
              "pattern": "^(https?://)?[a-zA-Z\\d_\\-.]+\\.opsgenie\\.com/service/([a-zA-Z\\d_\\-]+)/?$"
            },
            "region": {
              "description": "Opsgenie Instance Region",
              "type": "string",
              "examples": ["US", "EU"],
              "enum": ["US", "EU"]
            }
          },
          "required": ["service-url"],
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "extensions": {
      "description": "Custom extensions",
      "type": "object",
      "additionalProperties": true
    }
  },
  "additionalProperties": false,
  "required": ["schema-version", "dd-service"],
  "$defs": {
    "link": {
      "additionalProperties": false,
      "type": "object",
      "properties": {
        "name": {
          "description": "Link name",
          "examples": ["Runbook", "Dashboard"],
          "type": "string",
          "minLength": 1
        },
        "type": {
          "description": "Link type",
          "examples": ["runbook", "dashboard"],
          "type": "string",
          "enum": [
            "doc",
            "wiki",
            "runbook",
            "url",
            "repo",
            "dashboard",
            "oncall",
            "code",
            "link"
          ]
        },
        "url": {
          "description": "Link url",
          "examples": ["https://my-runbook"],
          "type": "string",
          "format": "uri"
        }
      },
      "required": [
        "name",
        "type",
        "url"
      ]
    },
    "contact": {
      "additionalProperties": false,
      "type": "object",
      "properties": {
        "name": {
          "description": "Contact name",
          "examples": ["Oncall Slack", "Team Email"],
          "type": "string",
          "minLength": 2
        },
        "type": {
          "description": "Contact type",
          "examples": ["email", "slack", "microsoft-teams"],
          "type": "string",
          "enum": [
            "email",
            "slack",
            "microsoft-teams"
          ]
        },
        "contact": {
          "description": "Contact value",
          "examples": ["contact@datadoghq.com", "https://my-org.slack.com/archives/my-channel"],
          "type": "string"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "type": {
                "const": "email"
              }
            }
          },
          "then": {
            "properties": {
              "contact": {
                "format": "email"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "slack"
              }
            }
          },
          "then": {
            "properties": {
              "contact": {
                "pattern": "^https://.+"
              }
            }
          }
        }
      ],
      "required": [
        "type",
        "contact"
      ]
    },
    "doc": {
      "additionalProperties": false,
      "type": "object",
      "properties": {
        "name": {
          "description": "Doc name",
          "examples": ["Architecture", "RFC", "Design"],
          "type": "string",
          "minLength": 1
        },
        "provider": {
          "description": "Doc provider",
          "examples": ["google drive", "figma"],
          "type": "string",
          "minLength": 1
        },
        "url": {
          "description": "Doc url",
          "examples": ["https://gdrive/mydoc"],
          "type": "string",
          "format": "uri"
        }
      },
      "required": [
        "name",
        "url"
      ]
    },
    "repo": {
      "additionalProperties": false,
      "type": "object",
      "properties": {
        "name": {
          "description": "Repo name",
          "examples": ["Source Code"],
          "type": "string",
          "minLength": 1
        },
        "provider": {
          "description": "Repo provider",
          "examples": ["Github"],
          "type": "string",
          "minLength": 1
        },
        "url": {
          "description": "Repo url",
          "examples": ["https://github.com/DataDog/schema"],
          "type": "string",
          "format": "uri"
        }
      },
      "required": [
        "name",
        "url"
      ]
    }
  }
}