Skip to main content

Entity

What is an Entity?

An Entity is an object that matches the type defined by a Blueprint, and it represents the data of the software components which is defined by the Blueprint properties.

Entity JSON structure

This is the basic structure of an Entity:

{
"identifier": "UniqueID",
"title": "Title",
"team": "",
"blueprint": "blueprintName",
"properties": {
"property1": "",
"property2": ""
},
"relations": {}
}

Structure table

FieldTypeDescription
identifierStringUnique identifier.
Note that while the identifier is unique, it can be changed after creation.
titleStringEntity name that will be shown in the UI.
teamArrayOptional Field. An array of the associated teams. Only available teams can be added.
Note that group permissions are handled according to this array, see Teams and ownership.
blueprintStringThe name of the Blueprint that this Entity is based on.
propertiesObjectAn object containing key-value pairs, where each key is a property as defined in the Blueprint definition, and each value applies the type of the property.
relationsobjectAn object containing key-value pairs.
Each key is the identifier of the Relation that is defined on the blueprint.

See more in the Related entities section.

Teams and ownership

teams and ownership

The team key defines ownership over an Entity and controls who can modify or delete an existing Entity.

To Explore more about Ownership in Port see our Permissions section.

Example

A microservice entity
In this example, you can see how a `microservice` Entity is defined:
{
"identifier": "my-service",
"title": "My Service",
"team": "Infra",
"blueprint": "microservice",
"properties": {
"repo-link": "https://github.com/port-labs/my-service",
"health-status": "Ready"
},
"relations": {}
}
note

This Entity is based on the following Blueprint definition, where the repo-link is mandatory.

{
"identifier": "microservice",
"title": "microservice",
"icon": "Microservice",
"formulaProperties": {},
"calculationProperties": {},
"schema": {
"properties": {
"repo-link": {
"type": "string",
"format": "url"
"title": "Repo URL"
},
"health-status": {
"type": "string",
"enum": [
"Ready",
"Down"
],
"title": "Service Health Status"
}
},
"required": [
"repo-link"
]
}
}

When two Blueprints are connected, creating an Entity of the source Blueprint will show an additional option - a Relation.

This option is shown under the relations section as follows:

Entity Relation example - many = false

When a Relation between Blueprints is configured with many = false, you can add a Relation to an Entity by adding the relationIdentifier as key, and the relatedEntityIdentifier as value:

"relations": {
"relation-identifier": "relatedEntityIdentifier"
}

Entity Relation example - many = true

When a Relation between Blueprints is configured with many = true, you can add a Relation to an Entity by adding the relationIdentifier as key, and an array of relatedEntityIdentifier(s) as value:

"relations": {
"relation-identifier": ["relatedEntityIdentifier1", "relatedEntityIdentifier2"]
}
tip

Click for more details about relations.

Relation mapping example

Let's assume we have a Relation between the deployment and microservice Blueprints named microservice.

One of our microservices is called Notification Service with the identifier notificationService.

In order to map this microservice to our notificationServiceDeploymentV1 deployment we will use the following relations key (In the notificationServiceDeploymentV1 Entity JSON):

"relations": {
"microservice": "notificationService"
}

Specifying the notificationService under the Relation maps the connection between our notificationServiceDeploymentV1 Entity and the notificationService Entity, so that when you view the notificationServiceDeploymentV1 entity you will also see the related notificationService entity.

In addition, you will be able to use Mirror Properties to map additional properties from the microservice Blueprint to the deployment Entity

Next Steps

Explore How to Create, Edit, and Delete Entities with basic examples

Dive into advanced operations on Entities with our API ➡️