feat(catalog-model): add API v1beta2 default and mcp-server schemas

Signed-off-by: benjdlambert <ben@blam.sh>
2026-04-21 10:55:27 +02:00
parent 9e0572b88c
commit 163561085b
2 changed files with 172 additions and 0 deletions
@@ -0,0 +1,93 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "ApiV1beta2McpServer",
+  "description": "An MCP (Model Context Protocol) server exposed as an API entity. See RFC backstage/backstage#32062.",
+  "examples": [
+    {
+      "apiVersion": "backstage.io/v1beta2",
+      "kind": "API",
+      "metadata": {
+        "name": "backstage-mcp-actions",
+        "title": "Backstage MCP Server",
+        "description": "Exposes tools related to the Backstage Ecosystem"
+      },
+      "spec": {
+        "type": "mcp-server",
+        "lifecycle": "experimental",
+        "owner": "backstage",
+        "remotes": [
+          {
+            "type": "streamable-http",
+            "url": "http://internal.backstage.company:7007/api/mcp-actions/v1"
+          }
+        ]
+      }
+    }
+  ],
+  "allOf": [
+    {
+      "$ref": "Entity"
+    },
+    {
+      "type": "object",
+      "required": ["spec"],
+      "properties": {
+        "apiVersion": {
+          "enum": ["backstage.io/v1beta2"]
+        },
+        "kind": {
+          "enum": ["API"]
+        },
+        "spec": {
+          "type": "object",
+          "required": ["type", "lifecycle", "owner", "remotes"],
+          "properties": {
+            "type": {
+              "const": "mcp-server",
+              "description": "Discriminant for the MCP server specType."
+            },
+            "lifecycle": {
+              "type": "string",
+              "description": "The lifecycle state of the MCP server.",
+              "examples": ["experimental", "production", "deprecated"],
+              "minLength": 1
+            },
+            "owner": {
+              "type": "string",
+              "description": "An entity reference to the owner of the MCP server.",
+              "examples": ["ai-platform-team", "user:john.johnson"],
+              "minLength": 1
+            },
+            "system": {
+              "type": "string",
+              "description": "An entity reference to the system that the MCP server belongs to.",
+              "minLength": 1
+            },
+            "remotes": {
+              "type": "array",
+              "minItems": 1,
+              "description": "Transport endpoints for the MCP server.",
+              "items": {
+                "type": "object",
+                "required": ["type", "url"],
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "description": "Transport type, e.g. streamable-http, stdio, sse.",
+                    "examples": ["streamable-http", "stdio", "sse"],
+                    "minLength": 1
+                  },
+                  "url": {
+                    "type": "string",
+                    "description": "Endpoint URL for the remote. For stdio transports this may be a command string.",
+                    "minLength": 1
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}
@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "ApiV1beta2",
+  "description": "An API describes an interface that can be exposed by a component. The API can be defined in different formats, like OpenAPI, AsyncAPI, GraphQL, gRPC, or other formats.",
+  "examples": [
+    {
+      "apiVersion": "backstage.io/v1beta2",
+      "kind": "API",
+      "metadata": {
+        "name": "artist-api",
+        "description": "Retrieve artist details",
+        "labels": {
+          "product_name": "Random value Generator"
+        },
+        "annotations": {
+          "docs": "https://github.com/..../tree/develop/doc"
+        }
+      },
+      "spec": {
+        "type": "openapi",
+        "lifecycle": "production",
+        "owner": "artist-relations-team",
+        "system": "artist-engagement-portal",
+        "definition": "openapi: \"3.0.0\"\ninfo:..."
+      }
+    }
+  ],
+  "allOf": [
+    {
+      "$ref": "Entity"
+    },
+    {
+      "type": "object",
+      "required": ["spec"],
+      "properties": {
+        "apiVersion": {
+          "enum": ["backstage.io/v1beta2"]
+        },
+        "kind": {
+          "enum": ["API"]
+        },
+        "spec": {
+          "type": "object",
+          "required": ["type", "lifecycle", "owner", "definition"],
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "The type of the API definition.",
+              "examples": ["openapi", "asyncapi", "graphql", "grpc", "trpc"],
+              "minLength": 1
+            },
+            "lifecycle": {
+              "type": "string",
+              "description": "The lifecycle state of the API.",
+              "examples": ["experimental", "production", "deprecated"],
+              "minLength": 1
+            },
+            "owner": {
+              "type": "string",
+              "description": "An entity reference to the owner of the API.",
+              "examples": ["artist-relations-team", "user:john.johnson"],
+              "minLength": 1
+            },
+            "system": {
+              "type": "string",
+              "description": "An entity reference to the system that the API belongs to.",
+              "minLength": 1
+            },
+            "definition": {
+              "type": "string",
+              "description": "The definition of the API, based on the format defined by the type.",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    }
+  ]
+}