diff --git a/.backstage/backstage-go.yaml b/.backstage/backstage-go.yaml new file mode 100644 index 0000000..4fa03d1 --- /dev/null +++ b/.backstage/backstage-go.yaml @@ -0,0 +1,13 @@ +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: backstage-go + description: Backstage SDK for Go + links: + - url: https://pkg.go.dev/go.einride.tech/backstage + title: GoDoc + icon: docs +spec: + type: go-library + lifecycle: production + owner: team-cloud-control diff --git a/.sage/main.go b/.sage/main.go index 76be0a6..4b7afc0 100644 --- a/.sage/main.go +++ b/.sage/main.go @@ -37,7 +37,7 @@ func Default(ctx context.Context) error { sg.Deps(ctx, GoLint, GoReview) sg.Deps(ctx, GoTest) sg.Deps(ctx, GoModTidy) - sg.Deps(ctx, GoLicenses, GitVerifyNoDiff) + sg.Deps(ctx, BackstageCatalogValidate, GoLicenses, GitVerifyNoDiff) return nil } @@ -86,6 +86,13 @@ func GitVerifyNoDiff(ctx context.Context) error { return sggit.VerifyNoDiff(ctx) } +func BackstageCatalogValidate(ctx context.Context) error { + sg.Logger(ctx).Println("validating Backstage catalog entities...") + cmd := sg.Command(ctx, "go", "run", ".", "catalog", "entities", "validate", sg.FromGitRoot(".backstage")) + cmd.Dir = sg.FromGitRoot("cmd", "backstage") + return cmd.Run() +} + func SemanticRelease(ctx context.Context, repo string, dry bool) error { sg.Logger(ctx).Println("triggering release...") args := []string{ diff --git a/.sage/schema.go b/.sage/schema.go new file mode 100644 index 0000000..a8474af --- /dev/null +++ b/.sage/schema.go @@ -0,0 +1,61 @@ +package main + +import ( + "context" + "fmt" + "io" + "net/http" + "os" + "path/filepath" + + "go.einride.tech/sage/sg" +) + +func Schema(ctx context.Context) error { + sg.Deps( + ctx, + sg.Fn(downloadSchema, "Entity.schema.json"), + sg.Fn(downloadSchema, "EntityEnvelope.schema.json"), + sg.Fn(downloadSchema, "EntityMeta.schema.json"), + sg.Fn(downloadSchema, "shared/common.schema.json"), + sg.Fn(downloadSchema, "kinds/API.v1alpha1.schema.json"), + sg.Fn(downloadSchema, "kinds/Component.v1alpha1.schema.json"), + sg.Fn(downloadSchema, "kinds/Domain.v1alpha1.schema.json"), + sg.Fn(downloadSchema, "kinds/Group.v1alpha1.schema.json"), + sg.Fn(downloadSchema, "kinds/Location.v1alpha1.schema.json"), + sg.Fn(downloadSchema, "kinds/Resource.v1alpha1.schema.json"), + sg.Fn(downloadSchema, "kinds/System.v1alpha1.schema.json"), + sg.Fn(downloadSchema, "kinds/User.v1alpha1.schema.json"), + ) + return nil +} + +func downloadSchema(ctx context.Context, path string) error { + const version = "v1.12.1" + url := fmt.Sprintf( + "https://raw.githubusercontent.com/backstage/backstage/%s/packages/catalog-model/src/schema/%s", + version, + path, + ) + request, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) + if err != nil { + return err + } + response, err := http.DefaultClient.Do(request) + if err != nil { + return err + } + defer func() { + _ = response.Body.Close() + }() + data, err := io.ReadAll(response.Body) + if err != nil { + return err + } + out := sg.FromGitRoot("cmd", "backstage", "internal", "schema", filepath.Base(path)) + if err := os.WriteFile(out, data, 0o600); err != nil { + return err + } + sg.Logger(ctx).Println("wrote schema", out) + return nil +} diff --git a/Makefile b/Makefile index eccc5fb..5821cdb 100644 --- a/Makefile +++ b/Makefile @@ -43,6 +43,10 @@ update-sage: $(go) clean-sage: @git clean -fdx .sage/tools .sage/bin .sage/build +.PHONY: backstage-catalog-validate +backstage-catalog-validate: $(sagefile) + @$(sagefile) BackstageCatalogValidate + .PHONY: convco-check convco-check: $(sagefile) @$(sagefile) ConvcoCheck @@ -90,6 +94,10 @@ go-review: $(sagefile) go-test: $(sagefile) @$(sagefile) GoTest +.PHONY: schema +schema: $(sagefile) + @$(sagefile) Schema + .PHONY: semantic-release semantic-release: $(sagefile) ifndef repo diff --git a/cmd/backstage/go.mod b/cmd/backstage/go.mod index 956d600..acbf46a 100644 --- a/cmd/backstage/go.mod +++ b/cmd/backstage/go.mod @@ -4,8 +4,10 @@ go 1.20 require ( github.com/adrg/xdg v0.4.0 + github.com/santhosh-tekuri/jsonschema v1.2.4 github.com/spf13/cobra v1.6.1 go.einride.tech/backstage v0.0.0-00010101000000-000000000000 + gopkg.in/yaml.v3 v3.0.1 ) require ( diff --git a/cmd/backstage/go.sum b/cmd/backstage/go.sum index 293bc60..c79eb38 100644 --- a/cmd/backstage/go.sum +++ b/cmd/backstage/go.sum @@ -9,6 +9,8 @@ github.com/inconshreveable/mousetrap v1.0.1/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLf github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +github.com/santhosh-tekuri/jsonschema v1.2.4 h1:hNhW8e7t+H1vgY+1QeEQpveR6D4+OwKPXCfD2aieJis= +github.com/santhosh-tekuri/jsonschema v1.2.4/go.mod h1:TEAUOeZSmIxTTuHatJzrvARHiuO9LYd+cIxzgEHCQI4= github.com/spf13/cobra v1.6.1 h1:o94oiPyS4KD1mPy2fmcYYHHfCxLqYjJOhGsCHFZtEzA= github.com/spf13/cobra v1.6.1/go.mod h1:IOw/AERYS7UzyrGinqmz6HLUo219MORXGxhbaJUqzrY= github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA= @@ -18,6 +20,7 @@ github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5Cc github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= golang.org/x/sys v0.0.0-20211025201205-69cdffdb9359 h1:2B5p2L5IfGiD7+b9BOoRMC6DgObAVZV+Fsp050NqXik= golang.org/x/sys v0.0.0-20211025201205-69cdffdb9359/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= diff --git a/cmd/backstage/internal/schema/API.v1alpha1.schema.json b/cmd/backstage/internal/schema/API.v1alpha1.schema.json new file mode 100644 index 0000000..3d5af71 --- /dev/null +++ b/cmd/backstage/internal/schema/API.v1alpha1.schema.json @@ -0,0 +1,79 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "ApiV1alpha1", + "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/v1alpha1", + "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/v1alpha1", "backstage.io/v1beta1"] + }, + "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 + } + } + } + } + } + ] +} diff --git a/cmd/backstage/internal/schema/Component.v1alpha1.schema.json b/cmd/backstage/internal/schema/Component.v1alpha1.schema.json new file mode 100644 index 0000000..34fc48d --- /dev/null +++ b/cmd/backstage/internal/schema/Component.v1alpha1.schema.json @@ -0,0 +1,101 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "ComponentV1alpha1", + "description": "A Component describes a software component. It is typically intimately linked to the source code that constitutes the component, and should be what a developer may regard a \"unit of software\", usually with a distinct deployable or linkable artifact.", + "examples": [ + { + "apiVersion": "backstage.io/v1alpha1", + "kind": "Component", + "metadata": { + "name": "LoremService", + "description": "Creates Lorems like a pro.", + "labels": { + "product_name": "Random value Generator" + }, + "annotations": { + "docs": "https://github.com/..../tree/develop/doc" + } + }, + "spec": { + "type": "service", + "lifecycle": "production", + "owner": "tools" + } + } + ], + "allOf": [ + { + "$ref": "Entity" + }, + { + "type": "object", + "required": ["spec"], + "properties": { + "apiVersion": { + "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"] + }, + "kind": { + "enum": ["Component"] + }, + "spec": { + "type": "object", + "required": ["type", "lifecycle", "owner"], + "properties": { + "type": { + "type": "string", + "description": "The type of component.", + "examples": ["service", "website", "library"], + "minLength": 1 + }, + "lifecycle": { + "type": "string", + "description": "The lifecycle state of the component.", + "examples": ["experimental", "production", "deprecated"], + "minLength": 1 + }, + "owner": { + "type": "string", + "description": "An entity reference to the owner of the component.", + "examples": ["artist-relations-team", "user:john.johnson"], + "minLength": 1 + }, + "system": { + "type": "string", + "description": "An entity reference to the system that the component belongs to.", + "minLength": 1 + }, + "subcomponentOf": { + "type": "string", + "description": "An entity reference to another component of which the component is a part.", + "minLength": 1 + }, + "providesApis": { + "type": "array", + "description": "An array of entity references to the APIs that are provided by the component.", + "items": { + "type": "string", + "minLength": 1 + } + }, + "consumesApis": { + "type": "array", + "description": "An array of entity references to the APIs that are consumed by the component.", + "items": { + "type": "string", + "minLength": 1 + } + }, + "dependsOn": { + "type": "array", + "description": "An array of references to other entities that the component depends on to function.", + "items": { + "type": "string", + "minLength": 1 + } + } + } + } + } + } + ] +} diff --git a/cmd/backstage/internal/schema/Domain.v1alpha1.schema.json b/cmd/backstage/internal/schema/Domain.v1alpha1.schema.json new file mode 100644 index 0000000..a1a09b1 --- /dev/null +++ b/cmd/backstage/internal/schema/Domain.v1alpha1.schema.json @@ -0,0 +1,47 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "DomainV1alpha1", + "description": "A Domain groups a collection of systems that share terminology, domain models, business purpose, or documentation, i.e. form a bounded context.", + "examples": [ + { + "apiVersion": "backstage.io/v1alpha1", + "kind": "Domain", + "metadata": { + "name": "artists", + "description": "Everything about artists" + }, + "spec": { + "owner": "artist-relations-team" + } + } + ], + "allOf": [ + { + "$ref": "Entity" + }, + { + "type": "object", + "required": ["spec"], + "properties": { + "apiVersion": { + "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"] + }, + "kind": { + "enum": ["Domain"] + }, + "spec": { + "type": "object", + "required": ["owner"], + "properties": { + "owner": { + "type": "string", + "description": "An entity reference to the owner of the component.", + "examples": ["artist-relations-team", "user:john.johnson"], + "minLength": 1 + } + } + } + } + } + ] +} diff --git a/cmd/backstage/internal/schema/Entity.schema.json b/cmd/backstage/internal/schema/Entity.schema.json new file mode 100644 index 0000000..90eb9dd --- /dev/null +++ b/cmd/backstage/internal/schema/Entity.schema.json @@ -0,0 +1,70 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "Entity", + "description": "The parts of the format that's common to all versions/kinds of entity.", + "examples": [ + { + "apiVersion": "backstage.io/v1alpha1", + "kind": "Component", + "metadata": { + "name": "LoremService", + "description": "Creates Lorems like a pro.", + "labels": { + "product_name": "Random value Generator" + }, + "annotations": { + "docs": "https://github.com/..../tree/develop/doc" + } + }, + "spec": { + "type": "service", + "lifecycle": "production", + "owner": "tools" + } + } + ], + "type": "object", + "required": ["apiVersion", "kind", "metadata"], + "additionalProperties": false, + "properties": { + "apiVersion": { + "type": "string", + "description": "The version of specification format for this particular entity that this is written against.", + "minLength": 1, + "examples": ["backstage.io/v1alpha1", "my-company.net/v1", "1.0"] + }, + "kind": { + "type": "string", + "description": "The high level entity type being described.", + "minLength": 1, + "examples": [ + "API", + "Component", + "Domain", + "Group", + "Location", + "Resource", + "System", + "Template", + "User" + ] + }, + "metadata": { + "$ref": "EntityMeta" + }, + "spec": { + "type": "object", + "description": "The specification data describing the entity itself." + }, + "relations": { + "type": "array", + "description": "The relations that this entity has with other entities.", + "items": { + "$ref": "common#relation" + } + }, + "status": { + "$ref": "common#status" + } + } +} diff --git a/cmd/backstage/internal/schema/EntityEnvelope.schema.json b/cmd/backstage/internal/schema/EntityEnvelope.schema.json new file mode 100644 index 0000000..7e64039 --- /dev/null +++ b/cmd/backstage/internal/schema/EntityEnvelope.schema.json @@ -0,0 +1,61 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "EntityEnvelope", + "description": "The envelope skeleton parts of an entity - whatever is necessary to be able to give it a ref and pass to further validation / policy checking.", + "examples": [ + { + "apiVersion": "backstage.io/v1alpha1", + "kind": "Component", + "metadata": { + "name": "LoremService" + } + } + ], + "type": "object", + "required": ["apiVersion", "kind", "metadata"], + "additionalProperties": true, + "properties": { + "apiVersion": { + "type": "string", + "description": "The version of specification format for this particular entity that this is written against.", + "minLength": 1, + "examples": ["backstage.io/v1alpha1", "my-company.net/v1", "1.0"] + }, + "kind": { + "type": "string", + "description": "The high level entity type being described.", + "minLength": 1, + "examples": [ + "API", + "Component", + "Domain", + "Group", + "Location", + "Resource", + "System", + "Template", + "User" + ] + }, + "metadata": { + "type": "object", + "required": ["name"], + "additionalProperties": true, + "properties": { + "name": { + "type": "string", + "description": "The name of the entity. Must be unique within the catalog at any given point in time, for any given namespace + kind pair.", + "examples": ["metadata-proxy"], + "minLength": 1 + }, + "namespace": { + "type": "string", + "description": "The namespace that the entity belongs to.", + "default": "default", + "examples": ["default", "admin"], + "minLength": 1 + } + } + } + } +} diff --git a/cmd/backstage/internal/schema/EntityMeta.schema.json b/cmd/backstage/internal/schema/EntityMeta.schema.json new file mode 100644 index 0000000..483e69f --- /dev/null +++ b/cmd/backstage/internal/schema/EntityMeta.schema.json @@ -0,0 +1,122 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "EntityMeta", + "description": "Metadata fields common to all versions/kinds of entity.", + "examples": [ + { + "uid": "e01199ab-08cc-44c2-8e19-5c29ded82521", + "etag": "lsndfkjsndfkjnsdfkjnsd==", + "name": "my-component-yay", + "namespace": "the-namespace", + "labels": { + "backstage.io/custom": "ValueStuff" + }, + "annotations": { + "example.com/bindings": "are-secret" + }, + "tags": ["java", "data"] + } + ], + "type": "object", + "required": ["name"], + "additionalProperties": true, + "properties": { + "uid": { + "type": "string", + "description": "A globally unique ID for the entity. This field can not be set by the user at creation time, and the server will reject an attempt to do so. The field will be populated in read operations. The field can (optionally) be specified when performing update or delete operations, but the server is free to reject requests that do so in such a way that it breaks semantics.", + "examples": ["e01199ab-08cc-44c2-8e19-5c29ded82521"], + "minLength": 1 + }, + "etag": { + "type": "string", + "description": "An opaque string that changes for each update operation to any part of the entity, including metadata. This field can not be set by the user at creation time, and the server will reject an attempt to do so. The field will be populated in read operations. The field can (optionally) be specified when performing update or delete operations, and the server will then reject the operation if it does not match the current stored value.", + "examples": ["lsndfkjsndfkjnsdfkjnsd=="], + "minLength": 1 + }, + "name": { + "type": "string", + "description": "The name of the entity. Must be unique within the catalog at any given point in time, for any given namespace + kind pair.", + "examples": ["metadata-proxy"], + "minLength": 1 + }, + "namespace": { + "type": "string", + "description": "The namespace that the entity belongs to.", + "default": "default", + "examples": ["default", "admin"], + "minLength": 1 + }, + "title": { + "type": "string", + "description": "A display name of the entity, to be presented in user interfaces instead of the name property, when available.", + "examples": ["React SSR Template"], + "minLength": 1 + }, + "description": { + "type": "string", + "description": "A short (typically relatively few words, on one line) description of the entity." + }, + "labels": { + "type": "object", + "description": "Key/value pairs of identifying information attached to the entity.", + "additionalProperties": true, + "patternProperties": { + "^.+$": { + "type": "string" + } + } + }, + "annotations": { + "type": "object", + "description": "Key/value pairs of non-identifying auxiliary information attached to the entity.", + "additionalProperties": true, + "patternProperties": { + "^.+$": { + "type": "string" + } + } + }, + "tags": { + "type": "array", + "description": "A list of single-valued strings, to for example classify catalog entities in various ways.", + "items": { + "type": "string", + "minLength": 1 + } + }, + "links": { + "type": "array", + "description": "A list of external hyperlinks related to the entity. Links can provide additional contextual information that may be located outside of Backstage itself. For example, an admin dashboard or external CMS page.", + "items": { + "type": "object", + "required": ["url"], + "properties": { + "url": { + "type": "string", + "description": "A url in a standard uri format.", + "examples": ["https://admin.example-org.com"], + "minLength": 1 + }, + "title": { + "type": "string", + "description": "A user friendly display name for the link.", + "examples": ["Admin Dashboard"], + "minLength": 1 + }, + "icon": { + "type": "string", + "description": "A key representing a visual icon to be displayed in the UI.", + "examples": ["dashboard"], + "minLength": 1 + }, + "type": { + "type": "string", + "description": "An optional value to categorize links into specific groups.", + "examples": ["runbook", "documentation", "logs", "dashboard"], + "minLength": 1 + } + } + } + } + } +} diff --git a/cmd/backstage/internal/schema/Group.v1alpha1.schema.json b/cmd/backstage/internal/schema/Group.v1alpha1.schema.json new file mode 100644 index 0000000..14c9d27 --- /dev/null +++ b/cmd/backstage/internal/schema/Group.v1alpha1.schema.json @@ -0,0 +1,104 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "GroupV1alpha1", + "description": "A group describes an organizational entity, such as for example a team, a business unit, or a loose collection of people in an interest group. Members of these groups are modeled in the catalog as kind User.", + "examples": [ + { + "apiVersion": "backstage.io/v1alpha1", + "kind": "Group", + "metadata": { + "name": "infrastructure", + "description": "The infra business unit" + }, + "spec": { + "type": "business-unit", + "profile": { + "displayName": "Infrastructure", + "email": "infrastructure@example.com", + "picture": "https://example.com/groups/bu-infrastructure.jpeg" + }, + "parent": "ops", + "children": ["backstage", "other"] + } + } + ], + "allOf": [ + { + "$ref": "Entity" + }, + { + "type": "object", + "required": ["spec"], + "properties": { + "apiVersion": { + "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"] + }, + "kind": { + "enum": ["Group"] + }, + "spec": { + "type": "object", + "required": ["type", "children"], + "properties": { + "type": { + "type": "string", + "description": "The type of group. There is currently no enforced set of values for this field, so it is left up to the adopting organization to choose a nomenclature that matches their org hierarchy.", + "examples": ["team", "business-unit", "product-area", "root"], + "minLength": 1 + }, + "profile": { + "type": "object", + "description": "Optional profile information about the group, mainly for display purposes. All fields of this structure are also optional. The email would be a group email of some form, that the group may wish to be used for contacting them. The picture is expected to be a URL pointing to an image that's representative of the group, and that a browser could fetch and render on a group page or similar.", + "properties": { + "displayName": { + "type": "string", + "description": "A simple display name to present to users.", + "examples": ["Infrastructure"], + "minLength": 1 + }, + "email": { + "type": "string", + "description": "An email where this entity can be reached.", + "examples": ["infrastructure@example.com"], + "minLength": 1 + }, + "picture": { + "type": "string", + "description": "The URL of an image that represents this entity.", + "examples": [ + "https://example.com/groups/bu-infrastructure.jpeg" + ], + "minLength": 1 + } + } + }, + "parent": { + "type": "string", + "description": "The immediate parent group in the hierarchy, if any. Not all groups must have a parent; the catalog supports multi-root hierarchies. Groups may however not have more than one parent. This field is an entity reference.", + "examples": ["ops"], + "minLength": 1 + }, + "children": { + "type": "array", + "description": "The immediate child groups of this group in the hierarchy (whose parent field points to this group). The list must be present, but may be empty if there are no child groups. The items are not guaranteed to be ordered in any particular way. The entries of this array are entity references.", + "items": { + "type": "string", + "examples": ["backstage", "other"], + "minLength": 1 + } + }, + "members": { + "type": "array", + "description": "The users that are members of this group. The entries of this array are entity references.", + "items": { + "type": "string", + "examples": ["jdoe"], + "minLength": 1 + } + } + } + } + } + } + ] +} diff --git a/cmd/backstage/internal/schema/Location.v1alpha1.schema.json b/cmd/backstage/internal/schema/Location.v1alpha1.schema.json new file mode 100644 index 0000000..b70df9e --- /dev/null +++ b/cmd/backstage/internal/schema/Location.v1alpha1.schema.json @@ -0,0 +1,75 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "LocationV1alpha1", + "description": "A location is a marker that references other places to look for catalog data.", + "examples": [ + { + "apiVersion": "backstage.io/v1alpha1", + "kind": "Location", + "metadata": { + "name": "org-data" + }, + "spec": { + "type": "url", + "targets": [ + "http://github.com/myorg/myproject/org-data-dump/catalog-info-staff.yaml", + "http://github.com/myorg/myproject/org-data-dump/catalog-info-consultants.yaml" + ] + } + } + ], + "allOf": [ + { + "$ref": "Entity" + }, + { + "type": "object", + "required": ["spec"], + "properties": { + "apiVersion": { + "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"] + }, + "kind": { + "enum": ["Location"] + }, + "spec": { + "type": "object", + "required": [], + "properties": { + "type": { + "type": "string", + "description": "The single location type, that's common to the targets specified in the spec. If it is left out, it is inherited from the location type that originally read the entity data.", + "examples": ["url"], + "minLength": 1 + }, + "target": { + "type": "string", + "description": "A single target as a string. Can be either an absolute path/URL (depending on the type), or a relative path such as ./details/catalog-info.yaml which is resolved relative to the location of this Location entity itself.", + "examples": ["./details/catalog-info.yaml"], + "minLength": 1 + }, + "targets": { + "type": "array", + "description": "A list of targets as strings. They can all be either absolute paths/URLs (depending on the type), or relative paths such as ./details/catalog-info.yaml which are resolved relative to the location of this Location entity itself.", + "items": { + "type": "string", + "examples": [ + "./details/catalog-info.yaml", + "http://github.com/myorg/myproject/org-data-dump/catalog-info-staff.yaml" + ], + "minLength": 1 + } + }, + "presence": { + "type": "string", + "description": "Whether the presence of the location target is required and it should be considered an error if it can not be found", + "default": "required", + "examples": ["required"], + "enum": ["required", "optional"] + } + } + } + } + } + ] +} diff --git a/cmd/backstage/internal/schema/Resource.v1alpha1.schema.json b/cmd/backstage/internal/schema/Resource.v1alpha1.schema.json new file mode 100644 index 0000000..4958afc --- /dev/null +++ b/cmd/backstage/internal/schema/Resource.v1alpha1.schema.json @@ -0,0 +1,68 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "ResourceV1alpha1", + "description": "A resource describes the infrastructure a system needs to operate, like BigTable databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together with components and systems allows to visualize resource footprint, and create tooling around them.", + "examples": [ + { + "apiVersion": "backstage.io/v1alpha1", + "kind": "Resource", + "metadata": { + "name": "artists-db", + "description": "Stores artist details" + }, + "spec": { + "type": "database", + "owner": "artist-relations-team", + "system": "artist-engagement-portal" + } + } + ], + "allOf": [ + { + "$ref": "Entity" + }, + { + "type": "object", + "required": ["spec"], + "properties": { + "apiVersion": { + "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"] + }, + "kind": { + "enum": ["Resource"] + }, + "spec": { + "type": "object", + "required": ["type", "owner"], + "properties": { + "type": { + "type": "string", + "description": "The type of resource.", + "examples": ["database", "s3-bucket", "cluster"], + "minLength": 1 + }, + "owner": { + "type": "string", + "description": "An entity reference to the owner of the resource.", + "examples": ["artist-relations-team", "user:john.johnson"], + "minLength": 1 + }, + "dependsOn": { + "type": "array", + "description": "An array of references to other entities that the resource depends on to function.", + "items": { + "type": "string", + "minLength": 1 + } + }, + "system": { + "type": "string", + "description": "An entity reference to the system that the resource belongs to.", + "minLength": 1 + } + } + } + } + } + ] +} diff --git a/cmd/backstage/internal/schema/System.v1alpha1.schema.json b/cmd/backstage/internal/schema/System.v1alpha1.schema.json new file mode 100644 index 0000000..2cdbc37 --- /dev/null +++ b/cmd/backstage/internal/schema/System.v1alpha1.schema.json @@ -0,0 +1,54 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "SystemV1alpha1", + "description": "A system is a collection of resources and components. The system may expose or consume one or several APIs. It is viewed as abstraction level that provides potential consumers insights into exposed features without needing a too detailed view into the details of all components. This also gives the owning team the possibility to decide about published artifacts and APIs.", + "examples": [ + { + "apiVersion": "backstage.io/v1alpha1", + "kind": "System", + "metadata": { + "name": "artist-engagement-portal", + "description": "Handy tools to keep artists in the loop" + }, + "spec": { + "owner": "artist-relations-team", + "domain": "artists" + } + } + ], + "allOf": [ + { + "$ref": "Entity" + }, + { + "type": "object", + "required": ["spec"], + "properties": { + "apiVersion": { + "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"] + }, + "kind": { + "enum": ["System"] + }, + "spec": { + "type": "object", + "required": ["owner"], + "properties": { + "owner": { + "type": "string", + "description": "An entity reference to the owner of the component.", + "examples": ["artist-relations-team", "user:john.johnson"], + "minLength": 1 + }, + "domain": { + "type": "string", + "description": "An entity reference to the domain that the system belongs to.", + "examples": ["artists"], + "minLength": 1 + } + } + } + } + } + ] +} diff --git a/cmd/backstage/internal/schema/User.v1alpha1.schema.json b/cmd/backstage/internal/schema/User.v1alpha1.schema.json new file mode 100644 index 0000000..a71409d --- /dev/null +++ b/cmd/backstage/internal/schema/User.v1alpha1.schema.json @@ -0,0 +1,80 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "UserV1alpha1", + "description": "A user describes a person, such as an employee, a contractor, or similar. Users belong to Group entities in the catalog. These catalog user entries are connected to the way that authentication within the Backstage ecosystem works. See the auth section of the docs for a discussion of these concepts.", + "examples": [ + { + "apiVersion": "backstage.io/v1alpha1", + "kind": "User", + "metadata": { + "name": "jdoe" + }, + "spec": { + "profile": { + "displayName": "Jenny Doe", + "email": "jenny-doe@example.com", + "picture": "https://example.com/staff/jenny-with-party-hat.jpeg" + }, + "memberOf": ["team-b", "employees"] + } + } + ], + "allOf": [ + { + "$ref": "Entity" + }, + { + "type": "object", + "required": ["spec"], + "properties": { + "apiVersion": { + "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"] + }, + "kind": { + "enum": ["User"] + }, + "spec": { + "type": "object", + "required": ["memberOf"], + "properties": { + "profile": { + "type": "object", + "description": "Optional profile information about the user, mainly for display purposes. All fields of this structure are also optional. The email would be a primary email of some form, that the user may wish to be used for contacting them. The picture is expected to be a URL pointing to an image that's representative of the user, and that a browser could fetch and render on a profile page or similar.", + "properties": { + "displayName": { + "type": "string", + "description": "A simple display name to present to users.", + "examples": ["Jenny Doe"], + "minLength": 1 + }, + "email": { + "type": "string", + "description": "An email where this user can be reached.", + "examples": ["jenny-doe@example.com"], + "minLength": 1 + }, + "picture": { + "type": "string", + "description": "The URL of an image that represents this user.", + "examples": [ + "https://example.com/staff/jenny-with-party-hat.jpeg" + ], + "minLength": 1 + } + } + }, + "memberOf": { + "type": "array", + "description": "The list of groups that the user is a direct member of (i.e., no transitive memberships are listed here). The list must be present, but may be empty if the user is not member of any groups. The items are not guaranteed to be ordered in any particular way. The entries of this array are entity references.", + "items": { + "type": "string", + "examples": ["team-b", "employees"], + "minLength": 1 + } + } + } + } + } + } + ] +} diff --git a/cmd/backstage/internal/schema/common.schema.json b/cmd/backstage/internal/schema/common.schema.json new file mode 100644 index 0000000..5a5eb97 --- /dev/null +++ b/cmd/backstage/internal/schema/common.schema.json @@ -0,0 +1,128 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "common", + "type": "object", + "description": "Common definitions to import from other schemas", + "definitions": { + "reference": { + "$id": "#reference", + "type": "object", + "description": "A reference by name to another entity.", + "required": ["kind", "namespace", "name"], + "additionalProperties": false, + "properties": { + "kind": { + "type": "string", + "description": "The kind field of the entity.", + "minLength": 1 + }, + "namespace": { + "type": "string", + "description": "The metadata.namespace field of the entity.", + "minLength": 1 + }, + "name": { + "type": "string", + "description": "The metadata.name field of the entity.", + "minLength": 1 + } + } + }, + "relation": { + "$id": "#relation", + "type": "object", + "description": "A directed relation from one entity to another.", + "required": ["type", "target"], + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "minLength": 1, + "pattern": "^\\w+$", + "description": "The type of relation." + }, + "target": { + "$ref": "#reference" + }, + "targetRef": { + "type": "string", + "minLength": 1, + "description": "The entity ref of the target of this relation." + } + } + }, + "status": { + "$id": "#status", + "type": "object", + "description": "The current status of the entity, as claimed by various sources.", + "required": [], + "additionalProperties": true, + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#statusItem" + } + } + } + }, + "statusItem": { + "$id": "#statusItem", + "type": "object", + "description": "A specific status item on a well known format.", + "required": ["type", "level", "message"], + "additionalProperties": true, + "properties": { + "type": { + "type": "string", + "minLength": 1 + }, + "level": { + "$ref": "#statusLevel", + "description": "The status level / severity of the status item." + }, + "message": { + "type": "string", + "description": "A brief message describing the status, intended for human consumption." + }, + "error": { + "$ref": "#error", + "description": "An optional serialized error object related to the status." + } + } + }, + "statusLevel": { + "$id": "#statusLevel", + "type": "string", + "description": "A status level / severity.", + "enum": ["info", "warning", "error"] + }, + "error": { + "$id": "#error", + "type": "object", + "description": "A serialized error object.", + "required": ["name", "message"], + "additionalProperties": true, + "properties": { + "name": { + "type": "string", + "examples": ["Error", "InputError"], + "description": "The type name of the error", + "minLength": 1 + }, + "message": { + "type": "string", + "description": "The message of the error" + }, + "code": { + "type": "string", + "description": "An error code associated with the error" + }, + "stack": { + "type": "string", + "description": "An error stack trace" + } + } + } + } +} diff --git a/cmd/backstage/internal/schema/schema.go b/cmd/backstage/internal/schema/schema.go new file mode 100644 index 0000000..3c5c95a --- /dev/null +++ b/cmd/backstage/internal/schema/schema.go @@ -0,0 +1,15 @@ +// Package schema provides primitives for working with catalog entity JSON schemas. +package schema + +import ( + "embed" + "io/fs" +) + +//go:embed *.schema.json +var schemasFS embed.FS + +// FS returns a file system with catalog entity JSON schemas. +func FS() fs.FS { + return schemasFS +} diff --git a/cmd/backstage/main.go b/cmd/backstage/main.go index ae83b03..53d35c9 100644 --- a/cmd/backstage/main.go +++ b/cmd/backstage/main.go @@ -3,12 +3,20 @@ package main import ( "bytes" "encoding/json" + "errors" "fmt" + "io" + "io/fs" "os" + "path/filepath" + "strings" "github.com/adrg/xdg" + "github.com/santhosh-tekuri/jsonschema" "github.com/spf13/cobra" "go.einride.tech/backstage/catalog" + "go.einride.tech/backstage/cmd/backstage/internal/schema" + "gopkg.in/yaml.v3" ) func main() { @@ -105,7 +113,8 @@ func newCatalogCommand() *cobra.Command { func newEntitiesCommand() *cobra.Command { cmd := newCommand() cmd.Use = "entities" - cmd.Short = "Read entities from the Backstage catalog" + cmd.Short = "Work with entities in the Backstage catalog" + cmd.AddCommand(newEntitiesValidateCommand()) cmd.AddCommand(newEntitiesListCommand()) cmd.AddCommand(newEntitiesGetByUIDCommand()) cmd.AddCommand(newEntitiesGetByNameCommand()) @@ -249,6 +258,89 @@ func newEntitiesBatchGetByRefsCommand() *cobra.Command { return cmd } +func newEntitiesValidateCommand() *cobra.Command { + cmd := newCommand() + cmd.Use = "validate [FILES]" + cmd.Short = "Validate entity files" + cmd.Args = cobra.MinimumNArgs(1) + cmd.RunE = func(cmd *cobra.Command, args []string) error { + compiler, err := newEntitySchemaCompiler() + if err != nil { + return err + } + var count int + for _, arg := range args { + if err := filepath.WalkDir(arg, func(path string, d fs.DirEntry, err error) error { + if d.IsDir() { + return nil + } + switch filepath.Ext(path) { + case ".json": + return fmt.Errorf("validation of JSON files not supported") + case ".yaml", ".yml": + data, err := os.ReadFile(path) + if err != nil { + return err + } + decoder := yaml.NewDecoder(bytes.NewReader(data)) + for { + var entity map[string]any + if err := decoder.Decode(&entity); err != nil { + if errors.Is(err, io.EOF) { + break + } + return err + } + kind, ok := entity["kind"].(string) + if !ok { + return fmt.Errorf("%s: unable to determine entity kind", path) + } + entitySchema, err := compiler.Compile(kind) + if err != nil { + return err + } + if err := entitySchema.ValidateInterface(entity); err != nil { + return err + } + count++ + } + } + return nil + }); err != nil { + return err + } + } + cmd.Printf("%d valid catalog entities", count) + return nil + } + return cmd +} + +func newEntitySchemaCompiler() (*jsonschema.Compiler, error) { + files, err := fs.ReadDir(schema.FS(), ".") + if err != nil { + return nil, err + } + result := jsonschema.NewCompiler() + for _, file := range files { + data, err := fs.ReadFile(schema.FS(), file.Name()) + if err != nil { + return nil, err + } + // Patch schema URI to have empty fragment (required by santhosh-tekuri/jsonschema). + data = bytes.ReplaceAll( + data, + []byte(`"http://json-schema.org/draft-07/schema"`), + []byte(`"http://json-schema.org/draft-07/schema#"`), + ) + entityName, _, _ := strings.Cut(file.Name(), ".") + if err := result.AddResource(entityName, bytes.NewReader(data)); err != nil { + return nil, err + } + } + return result, nil +} + func printRawJSON(cmd *cobra.Command, raw json.RawMessage) { var indented bytes.Buffer indented.Grow(len(raw) * 2)