Skip to main content

Link specifications

Before you start

If you haven't done it yet, read about services' main concepts.

Also have these handy reference:

Now that you have your service and actions specification, you can link your service.

Here are some design questions to answer:

QuestionGuidance
Which roles will applications have when linking my service?It's common for services to be linked for roles such as read, write, push, consume, etc. In simple scenarios, you can just handle these situations with a property, but in more complex scenarios, you'll want to implement multiple link types. Read the section for more details.
Which properties do I need to hold for the link?These are the properties that define the link. They are usually a combination of input parameters plus values obtained from the cloud provider upon service creation. Set these as a JSON schema in the attributes field.
Where in the organization is the link going to be available?A good default is to start by making the service visible everywhere with the value organization=your-org-id:account=*. Set your choice in the visible_to array.
What can be done with the link?Define standard actions in the link specification to control what users can do with the service.

As with service specs, you can configure the link specification to automatically generate standard actions—create, update, and delete. This helps keep your spec and its actions in sync, with less manual upkeep.

To enable this:

  • Set "use_default_actions": true in your link specification.
  • Use the visibleOn and editableOn keywords in your schema to control when each property should be shown or editable during the instance lifecycle.

For example:

  • visibleOn: ["create", "update"] makes a property visible when creating or updating an instance.
  • editableOn: ["create"] makes a property editable only at creation time.

You can check our Special schema keys page for more information on these keywords.

By using this approach, you manage everything from a single source of truth—the link specification schema—without the need to define or maintain separate action specifications.

Autogenerated actions vs. Action specifications

We recommend defining autogenerated standard actions directly in the link spec unless:

  • You need to update your standard actions. Autogenerated actions can't be edited directly—changes and updates must be made using action specifications.
  • You prefer to manage the default create, update, and delete actions manually using action specifications.

See Action specifications or more information on how to design actions for your services.

When applications need to link your service for different uses such as "read", "write", "push", "consume", it can be smart to have several link types. By doing so you will be able to:

  • Have separate forms, schemas, and parameters for each link type.
  • Implement different set of actions, particularly custom actions.

When you create several link specifications for the same service, the platform will display a dropdown menu for end users to select the type of link they want to create:

Service multilinks

The drawback of multiple link types is that you end up with more specifications to manage, but it greatly improves UX and simplifies the provisioning code.

Link specifications work much like service specifications, and you can create them using our CLI or API.

Here’s an example of how to create one:

np link_specification create \
 --body '{
  "name": "my-link-specification",
  "specification_id": "fb2c761d-a3d5-19c3-58e7-72a182d49b61",
  "unique": true,
  "dimensions": {
    "environment": "production"
  },
  "use_default_actions": true,    // When set to 'true', enables generation of default actions in the spec
  "attributes": {         // Defines the structure and layout of the form
    "schema": {
      "type": "object",
      "properties": {
        "my_string_property": {
          "type": "string",
          "visibleOn": ["read", "create", "update"],
          "editableOn": ["create"]
        },
        "my_number_property": {
          "type": "number",
          "default": 0,
          "visibleOn": ["read", "create"],
          "editableOn": ["create"]
        }
      },
      "required": [
        "my_string_property"
      ]
    },
    "values": {}
  }
}'

Some attributes to consider​

Here’s a breakdown of a few key fields from the JSON above:

  • specification_id: The unique ID of the service specification this link is associated with.
  • assignable_to: Determines what type of entities the link can be assigned to.
  • use_default_actions: When set to true, we automatically generate standard create, update, and delete actions.
  • attributes: Describes the configuration and layout of the service using JSON Schema.

You can always refer to our API reference for more details on link specification requests.