The core of Rely is its software catalog. Every entity in your software catalog can be represented as a JSON file which we call entity descriptor.

Entity ID

You'll see us refer to the "entity ID" throughout the docs. The entity ID is a unique identifier that's used throughout Rely.io to declare relations to other entities or look-up information. The entity ID must be globally unique across all entities.

An entity ID is usually the very first field in the entity's descriptor.

Entity Descriptor.

Regardless of whether you're using UI editing or GitOps to manage your entities, the definitions are backed by JSON files. Each file is a fully compliant OpenAPI 3 spec file, with our own specific extensions.

You can still use Rely even if you don't use OpenAPI/Swagger.

We use the OpenAPI spec as a base for entity & blueprint data, since it's an open spec with official support for extensions. That lets us extend it to be an entity or blueprint descriptor spec with optional usage of actual OpenAPI fields.

All entities have three other metadata fields besides the entity id:

  • Name: A user-friendly display name.

  • Blueprint ID: A reference to the entity's type.

  • Description (Optional): A concise overview of the entity for further context.

An entity descriptor also contains all relevant data that makes up the entity itself which might envolve:

  • Properties: The defining characteristics and attributes of an entity.

  • Relations: These indicate how the entity is connected to or interacts with other entities within Rely.

  • Sources: These specify where the entity's data originates from in the case of automated integrations with external systems via Rely's plugins.

Example Service Entity

  "id": "advertising",
  "blueprintId": "service",
  "title": "Advertising",
  "description": "A Helm chart for deploying a Python app for advertising purposes",
  "properties": {
    "tier": "Customer Facing",
    "readme": "https://github.com/rely.io/demo-ads/-/blob/master/README.md?ref_type=heads",
    "on-call": "tim-cook@gmail.com",
    "version": "0.1.5",
    "language": "Python",
    "lifecycle": "Production",
    "repo-link": "https://github.com/rely/ads",
    "code-owners": [
    "handles-pii": false,
    "monitor-links": [
    "quality_gate_status": "Passed",
    "unit-tests-coverage": 87,
    "communication-method": "GraphQL"
  "relations": {
    "team": {
      "value": "marketing-and-advertising-team"
    "internal-dependencies": {
      "value": [
    "running-instances": {
      "value": [
    "GitlabRepository": {
      "value": "adversiting"
  "sources": {
    "automation.rely.gitlab.v1.repository-to-service.gitlab.v1.repository.adversiting": {
      "type": "automation",
      "config": {
        "automationId": "rely.gitlab.v1.repository-to-service",
        "blueprintId": "gitlab.v1.repository",
        "entityId": "adversiting",
        "fields": [
      "activeMappings": {
        "title": null,
        "description": null,
        "properties/readme": null,
        "properties/language": null,
        "properties/repo-link": null,
        "relations/GitlabRepository": null

Learn More

Last updated