From 6207cf47c6ffce764f6e07db0e91c59f124fda5b Mon Sep 17 00:00:00 2001 From: Jordi Polo Date: Fri, 5 Jun 2020 17:47:44 -0700 Subject: [PATCH 1/2] Initial version of a json schema for the service specification --- docs/service_specification.schema.json | 117 +++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 docs/service_specification.schema.json diff --git a/docs/service_specification.schema.json b/docs/service_specification.schema.json new file mode 100644 index 0000000000..01216226c5 --- /dev/null +++ b/docs/service_specification.schema.json @@ -0,0 +1,117 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "backstage.io/v1beta1", + "type": "object", + "title": "A JSON Schema for Backstage service definitions.", + "description": "Each Backstage description file has a number of files. This schema matches each of those.", + "examples": [ + { + "apiVersion": "backstage.io/v1beta1", + "kind": "Component", + "spec": { + "type": "service" + }, + "metadata": { + "name": "LoremService", + "description": "Creates Lorems like a pro.", + "labels": { + "product_name": "Random value Generator" + }, + "annnotations": { + "docs": "https://github.com/..../tree/develop/doc" + }, + "teams": { + "name": "Team super great", + "email": "greatTeam@geemel.com" + } + } + } + ], + "required": [ + "apiVersion", + "kind", + "spec", + "metadata" + ], + "additionalProperties": false, + "properties": { + "apiVersion": { + "type": "string", + "description": "Version of the specification format for a particular file is written against.", + "default": "backstage.io/v1beta1", + "enum": [ + "backstage.io/v1beta1" + ] + }, + "kind": { + "type": "string", + "description": "High level entity type being described, from the Backstage system model.", + "enum": [ + "Compontent" + ] + }, + "spec": { + "type": "object", + "description": "Actual specification data that describes the entity. TODO: shape depend on `kind`", + "required": [ + "type" + ], + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "description": "The type of component.", + "default": "", + "examples": [ + "service" + ] + } + } + }, + "metadata": { + "type": "object", + "description": "Metadata about the entity, i.e. things that aren't directly part of the entity specification itself.", + "required": [ + "name" + ], + "additionalProperties": true, + "properties": { + "name": { + "type": "string", + "pattern": "^[a-z0-9A-Z_\\-\\.]{1,63}$", + "description": "The name of the entity. This name is both meant for human eyes to recognize the entity, and for machines and other components to reference the entity" + }, + "description": { + "type": "string", + "description": "A human readable description of the entity, to be shown in Backstage. Should be kept short and informative." + }, + "namespace": { + "type": "string", + "description": "The name of a namespace that the entity belongs to." + }, + "labels": { + "type": "object", + "description": "Labels are optional key/value pairs of that are attached to the entity, and their use is identical to kubernetes object labels.", + "additionalProperties": true, + "patternProperties": { + "^([a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\\.[a-zA-Z]{2,}\/)?[a-z0-9A-Z_\\-\\.]{1,63}$": { + "type": "string", + "pattern": "^[a-z0-9A-Z_\\-\\.]{1,63}$", + } + } + }, + "annnotations": { + "type": "object", + "description": "Arbitrary non-identifying metadata attached to the entity, identical in use to kubernetes object annotations.", + "additionalProperties": true, + "patternProperties": { + "^([a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\\.[a-zA-Z]{2,}\/)?[a-z0-9A-Z_\\-\\.]{1,63}$": { + "type": "string", + "pattern": "^[a-z0-9A-Z_\\-\\.]{1,63}$", + } + } + } + } + } + } +} From ad9225ecba087e04fef7293c7d721434c01c92da Mon Sep 17 00:00:00 2001 From: Jordi Polo Date: Tue, 9 Jun 2020 22:46:17 -0700 Subject: [PATCH 2/2] Address review comments --- docs/service_specification.schema.json | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/service_specification.schema.json b/docs/service_specification.schema.json index 01216226c5..15b31127f4 100644 --- a/docs/service_specification.schema.json +++ b/docs/service_specification.schema.json @@ -2,8 +2,8 @@ "$schema": "http://json-schema.org/draft-07/schema", "$id": "backstage.io/v1beta1", "type": "object", - "title": "A JSON Schema for Backstage service definitions.", - "description": "Each Backstage description file has a number of files. This schema matches each of those.", + "title": "A JSON Schema for Backstage catalog entities.", + "description": "Each descriptor file has a number of entities. This schema matches each of those.", "examples": [ { "apiVersion": "backstage.io/v1beta1", @@ -20,17 +20,16 @@ "annnotations": { "docs": "https://github.com/..../tree/develop/doc" }, - "teams": { + "teams": [{ "name": "Team super great", "email": "greatTeam@geemel.com" - } + }] } } ], "required": [ "apiVersion", "kind", - "spec", "metadata" ], "additionalProperties": false, @@ -38,7 +37,6 @@ "apiVersion": { "type": "string", "description": "Version of the specification format for a particular file is written against.", - "default": "backstage.io/v1beta1", "enum": [ "backstage.io/v1beta1" ] @@ -47,7 +45,7 @@ "type": "string", "description": "High level entity type being described, from the Backstage system model.", "enum": [ - "Compontent" + "Component" ] }, "spec": { @@ -78,7 +76,7 @@ "properties": { "name": { "type": "string", - "pattern": "^[a-z0-9A-Z_\\-\\.]{1,63}$", + "pattern": "^[a-z0-9A-Z_.-]{1,63}$", "description": "The name of the entity. This name is both meant for human eyes to recognize the entity, and for machines and other components to reference the entity" }, "description": { @@ -96,7 +94,7 @@ "patternProperties": { "^([a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\\.[a-zA-Z]{2,}\/)?[a-z0-9A-Z_\\-\\.]{1,63}$": { "type": "string", - "pattern": "^[a-z0-9A-Z_\\-\\.]{1,63}$", + "pattern": "^[a-z0-9A-Z_.-]{1,63}$" } } }, @@ -107,7 +105,7 @@ "patternProperties": { "^([a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\\.[a-zA-Z]{2,}\/)?[a-z0-9A-Z_\\-\\.]{1,63}$": { "type": "string", - "pattern": "^[a-z0-9A-Z_\\-\\.]{1,63}$", + "pattern": "^[a-z0-9A-Z_.-]{1,63}$" } } }