Skip to main content

Service specification

Before you start

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

Also have these handy reference:

Design your service specification​

Before actually creating the service, you have ask yourself some questions that we'll present in a table, so you can see how your answers impact your service specification:

QuestionGuidance
What's the name for the service?Choose a natural name (e.g., MySQL) and set it into the name field.
Which properties do I need to hold for the service?These are the properties that define the service. 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 service 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 service?Define standard actions in the service specification to control what users can do with the service.

Defining standard actions in the service spec​

You can configure the service 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 service 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 service 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 service 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 for more information on how to design actions for your services.

Create a service specification​

You can create a service specification using our CLI or API.

Craft your service specifications from the UI

You can also review and edit service and link specifications directly from the UI, making it easier than ever to work with your services.

Go to Platform settings > Services and click New service specification.

Here’s an example of a service specification that includes standard actions:

np service-specification create \
 --body '{
    "name": "my-service-specification",
    "type": "dependency",
    "visible_to": [
      "organization=1:account=1",
      "organization=1:account=2"
    ],
    "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": {}
    }
  }'
Service details

The JSON schema under attributes determines the service's attributes, fields and layout in the UI. These properties appear in the See details, Create, or Edit views in the nullplatform interface. You can further enhance the rendering of that section using UI Schema.

Some attributes to consider​

Let’s take a closer look at a few of the key fields in the JSON:

  • visible_to: Defines visibility for the service using NRN. Each entry in this array follows the format organization=<org_id>:account=<account_id>:namespace=<namespace_id>. For example:
    • "organization=1:account=2:namespace=3" makes the service visible to namespace 3 under account 2 of organization 1.
    • "organization=1:account=2:namespace=*" makes the service visible to all namespaces under account 2.
  • 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 service specification requests.