{ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://json.schemastore.org/catalog-info.json", "anyOf": [ { "$schema": "http://json-schema.org/draft-07/schema#", "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": "https://json.schemastore.org/catalog-info.json#/definitions/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"], "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", "object"], "description": "The definition of the API, based on the format defined by the type.", "minLength": 1, "properties": { "$json": { "type": "string", "description": "Interprets the contents of the referenced file as JSON and embeds the parsed structure.", "minLength": 1 }, "$text": { "type": "string", "description": "Interprets the contents of the referenced file as plain text and embeds it as a string.", "minLength": 1 }, "$yaml": { "type": "string", "description": "Interprets the contents of the referenced file as YAML and embeds the parsed structure.", "minLength": 1 } }, "minProperties": 1, "maxProperties": 1 } } } } } ] }, { "$schema": "http://json-schema.org/draft-07/schema#", "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": "https://json.schemastore.org/catalog-info.json#/definitions/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 } } } } } } ] }, { "$schema": "http://json-schema.org/draft-07/schema#", "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": "https://json.schemastore.org/catalog-info.json#/definitions/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 } } } } } ] }, { "$schema": "http://json-schema.org/draft-07/schema#", "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": "https://json.schemastore.org/catalog-info.json#/definitions/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 } } } } } } ] }, { "$schema": "http://json-schema.org/draft-07/schema#", "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": "https://json.schemastore.org/catalog-info.json#/definitions/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 } } } } } } ] }, { "$schema": "http://json-schema.org/draft-07/schema#", "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": "https://json.schemastore.org/catalog-info.json#/definitions/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 } } } } } ] }, { "$schema": "http://json-schema.org/draft-07/schema#", "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": "https://json.schemastore.org/catalog-info.json#/definitions/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 } } } } } ] }, { "$schema": "http://json-schema.org/draft-07/schema#", "description": "A Template describes a scaffolding task for use with the Scaffolder. It describes the required parameters as well as a series of steps that will be taken to execute the scaffolding task.", "examples": [ { "apiVersion": "backstage.io/v1beta2", "kind": "Template", "metadata": { "name": "react-ssr-template", "title": "React SSR Template", "description": "Next.js application skeleton for creating isomorphic web applications.", "tags": ["recommended", "react"] }, "spec": { "owner": "artist-relations-team", "type": "website", "parameters": { "required": ["name", "description"], "properties": { "name": { "title": "Name", "type": "string", "description": "Unique name of the component" }, "description": { "title": "Description", "type": "string", "description": "Description of the component" } } }, "steps": [ { "id": "fetch", "name": "Fetch", "action": "fetch:plain", "parameters": { "url": "./template" } }, { "id": "publish", "name": "Publish to GitHub", "action": "publish:github", "parameters": { "repoUrl": "{{ parameters.repoUrl }}" }, "if": "{{ parameters.repoUrl }}" } ], "output": { "catalogInfoUrl": "{{ steps.publish.output.catalogInfoUrl }}" } } } ], "allOf": [ { "$ref": "https://json.schemastore.org/catalog-info.json#/definitions/entity" }, { "type": "object", "required": ["spec"], "properties": { "apiVersion": { "enum": ["backstage.io/v1beta2"] }, "kind": { "enum": ["Template"] }, "spec": { "type": "object", "required": ["type", "steps"], "properties": { "type": { "type": "string", "description": "The type of component created by the template. The software catalog accepts any type value, but an organization should take great care to establish a proper taxonomy for these. Tools including Backstage itself may read this field and behave differently depending on its value. For example, a website type component may present tooling in the Backstage interface that is specific to just websites.", "examples": ["service", "website", "library"], "minLength": 1 }, "parameters": { "oneOf": [ { "type": "object", "description": "The JSONSchema describing the inputs for the template." }, { "type": "array", "description": "A list of separate forms to collect parameters.", "items": { "type": "object", "description": "The JSONSchema describing the inputs for the template." } } ] }, "steps": { "type": "array", "description": "A list of steps to execute.", "items": { "type": "object", "description": "A description of the step to execute.", "required": ["action"], "properties": { "id": { "type": "string", "description": "The ID of the step, which can be used to refer to its outputs." }, "name": { "type": "string", "description": "The name of the step, which will be displayed in the UI during the scaffolding process." }, "action": { "type": "string", "description": "The name of the action to execute." }, "input": { "type": "object", "description": "A templated object describing the inputs to the action." }, "if": { "type": ["string", "boolean"], "description": "A templated condition that skips the step when evaluated to false. If the condition is true or not defined, the step is executed. The condition is true, if the input is not `false`, `undefined`, `null`, `\"\"`, `0`, or `[]`." } } } }, "output": { "type": "object", "description": "A templated object describing the outputs of the scaffolding task.", "properties": { "links": { "type": "array", "description": "A list of external hyperlinks, typically pointing to resources created or updated by the template", "items": { "type": "object", "required": [], "properties": { "url": { "type": "string", "description": "A url in a standard uri format.", "examples": [ "https://github.com/my-org/my-new-repo" ], "minLength": 1 }, "entityRef": { "type": "string", "description": "An entity reference to an entity in the catalog.", "examples": ["Component:default/my-app"], "minLength": 1 }, "title": { "type": "string", "description": "A user friendly display name for the link.", "examples": ["View new repo"], "minLength": 1 }, "icon": { "type": "string", "description": "A key representing a visual icon to be displayed in the UI.", "examples": ["dashboard"], "minLength": 1 } } } } }, "additionalProperties": { "type": "string" } }, "owner": { "type": "string", "description": "The user (or group) owner of the template", "minLength": 1 } } } } } ] }, { "$schema": "http://json-schema.org/draft-07/schema", "description": "A Template describes a scaffolding task for use with the Scaffolder. It describes the required parameters as well as a series of steps that will be taken to execute the scaffolding task.", "examples": [ { "apiVersion": "scaffolder.backstage.io/v1beta3", "kind": "Template", "metadata": { "name": "react-ssr-template", "title": "React SSR Template", "description": "Next.js application skeleton for creating isomorphic web applications.", "tags": ["recommended", "react"] }, "spec": { "owner": "artist-relations-team", "type": "website", "parameters": { "required": ["name", "description", "repoUrl"], "backstage:permissions": { "tags": ["one", "two"] }, "properties": { "name": { "title": "Name", "type": "string", "description": "Unique name of the component" }, "description": { "title": "Description", "type": "string", "description": "Description of the component" }, "repoUrl": { "title": "Pick a repository", "type": "string", "ui:field": "RepoUrlPicker" } } }, "steps": [ { "id": "fetch", "name": "Fetch", "action": "fetch:plain", "parameters": { "url": "./template" }, "backstage:permissions": { "tags": ["one", "two"] } }, { "id": "publish", "name": "Publish to GitHub", "action": "publish:github", "parameters": { "repoUrl": "${{ parameters.repoUrl }}" }, "if": "${{ parameters.repoUrl }}" } ], "output": { "catalogInfoUrl": "${{ steps.publish.output.catalogInfoUrl }}" } } } ], "allOf": [ { "$ref": "https://json.schemastore.org/catalog-info.json#/definitions/entity" }, { "type": "object", "required": ["spec"], "properties": { "apiVersion": { "enum": ["scaffolder.backstage.io/v1beta3"] }, "kind": { "enum": ["Template"] }, "spec": { "type": "object", "required": ["type", "steps"], "properties": { "type": { "type": "string", "description": "The type of component created by the template. The software catalog accepts any type value, but an organization should take great care to establish a proper taxonomy for these. Tools including Backstage itself may read this field and behave differently depending on its value. For example, a website type component may present tooling in the Backstage interface that is specific to just websites.", "examples": ["service", "website", "library"], "minLength": 1 }, "owner": { "type": "string", "description": "The user (or group) owner of the template", "minLength": 1 }, "parameters": { "oneOf": [ { "type": "object", "description": "The JSONSchema describing the inputs for the template.", "properties": { "backstage:permissions": { "type": "object", "description": "Object used for authorizing the parameter", "properties": { "tags": { "type": "array", "items": { "type": "string" } } } } } }, { "type": "array", "description": "A list of separate forms to collect parameters.", "items": { "type": "object", "description": "The JSONSchema describing the inputs for the template.", "properties": { "backstage:permissions": { "type": "object", "description": "Object used for authorizing the parameter", "properties": { "tags": { "type": "array", "items": { "type": "string" } } } } } } } ] }, "presentation": { "type": "object", "description": "A way to redefine the presentation of the scaffolder.", "properties": { "buttonLabels": { "type": "object", "description": "A way to redefine the labels for actionable buttons.", "properties": { "backButtonText": { "type": "string", "description": "A button which return the user to one step back." }, "createButtonText": { "type": "string", "description": "A button which start the execution of the template." }, "reviewButtonText": { "type": "string", "description": "A button which open the review step to verify the input prior to start the execution." } } } } }, "EXPERIMENTAL_recovery": { "type": "object", "description": "A task recovery section.", "properties": { "EXPERIMENTAL_strategy": { "type": "string", "description": "Recovery strategy for your task (none or startOver). By default none" } } }, "EXPERIMENTAL_formDecorators": { "type": "array", "description": "A list of decorators and their inputs that the form should trigger before submitting the job", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The form hook ID" }, "input": { "type": "object", "description": "A object describing the inputs to the form hook." } } } }, "steps": { "type": "array", "description": "A list of steps to execute.", "items": { "type": "object", "description": "A description of the step to execute.", "required": ["action"], "properties": { "id": { "type": "string", "description": "The ID of the step, which can be used to refer to its outputs." }, "name": { "type": "string", "description": "The name of the step, which will be displayed in the UI during the scaffolding process." }, "action": { "type": "string", "description": "The name of the action to execute." }, "input": { "type": "object", "description": "A templated object describing the inputs to the action." }, "if": { "type": ["string", "boolean"], "description": "A templated condition that skips the step when evaluated to false. If the condition is true or not defined, the step is executed. The condition is true, if the input is not `false`, `undefined`, `null`, `\"\"`, `0`, or `[]`." }, "backstage:permissions": { "type": "object", "description": "Object used for authorizing the step", "properties": { "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "output": { "type": "object", "description": "A templated object describing the outputs of the scaffolding task.", "properties": { "links": { "type": "array", "description": "A list of external hyperlinks, typically pointing to resources created or updated by the template", "items": { "type": "object", "required": [], "properties": { "url": { "type": "string", "description": "A url in a standard uri format.", "examples": [ "https://github.com/my-org/my-new-repo" ], "minLength": 1 }, "entityRef": { "type": "string", "description": "An entity reference to an entity in the catalog.", "examples": ["Component:default/my-app"], "minLength": 1 }, "title": { "type": "string", "description": "A user friendly display name for the link.", "examples": ["View new repo"], "minLength": 1 }, "icon": { "type": "string", "description": "A key representing a visual icon to be displayed in the UI.", "examples": ["dashboard"], "minLength": 1 } } } }, "text": { "type": "array", "description": "A list of Markdown text blobs, like output data from the template.", "items": { "type": "object", "required": [], "properties": { "title": { "type": "string", "description": "A user friendly display name for the text.", "examples": ["Output Content"], "minLength": 1 }, "icon": { "type": "string", "description": "A key representing a visual icon to be displayed in the UI.", "examples": ["dashboard"], "minLength": 1 }, "content": { "type": "string", "description": "The text blob to display in the UI, rendered as Markdown.", "examples": ["**hey** _I'm_ Markdown"] } } } } }, "additionalProperties": { "type": "string" } } } } } } ] }, { "$schema": "http://json-schema.org/draft-07/schema#", "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": "https://json.schemastore.org/catalog-info.json#/definitions/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 } } } } } } ] } ], "definitions": { "entity": { "$schema": "http://json-schema.org/draft-07/schema#", "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": { "$schema": "http://json-schema.org/draft-07/schema#", "description": "Metadata fields common to all versions/kinds of entity.", "examples": [ { "uid": "e01199ab-08cc-44c2-8e19-5c29ded82521", "etag": "lsndfkjsndfkjnsdfkjnsd==", "generation": 13, "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 }, "generation": { "type": "integer", "description": "A positive nonzero number that indicates the current generation of data for this entity; the value is incremented each time the spec changes. 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.", "examples": [1], "minimum": 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", "object"], "properties": { "$json": { "type": "string", "minLength": 1 }, "$text": { "type": "string", "minLength": 1 }, "$yaml": { "type": "string", "minLength": 1 } }, "additionalProperties": false } } }, "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 } } } } } }, "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": "https://json.schemastore.org/catalog-info.json#/definitions/common/definitions/relation" } }, "status": { "$ref": "https://json.schemastore.org/catalog-info.json#/definitions/common/definitions/status" } } }, "common": { "$schema": "http://json-schema.org/draft-07/schema#", "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": "https://json.schemastore.org/catalog-info.json#/definitions/common/definitions/reference" } } }, "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": "https://json.schemastore.org/catalog-info.json#/definitions/common/definitions/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": "https://json.schemastore.org/catalog-info.json#/definitions/common/definitions/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": "https://json.schemastore.org/catalog-info.json#/definitions/common/definitions/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" } } } } } }, "type": "object" }