---
sidebar_label: Scope specifications
doc_id: 19ed0489-d661-4843-b36d-0a0ba375a924
description: >-
  Guide for defining agent-backed scopes using service specifications, including
  naming, parameters, and schemas.
keywords:
  - scope specification
  - agent-backed scopes
  - service specification
  - JSON schema
  - UI schema
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Scope specification

Agent-backed scopes use service specifications to define their name, category, visibility, and allowed parameters.

:::note Before you start

If you haven't done it yet, read about [scopes' main concepts](/docs/agent-backed-scopes/overview).

Also, have these handy references ready:

* **Service Specification API**
  * [Our API reference](/docs/service-specification-api-index)
* **Schemas**
    * [JSON Schema (external link)](https://json-schema.org/learn/getting-started-step-by-step) | [Additional keywords supported by nullplatform](/docs/json-ui-schema/json-schema)
    * [UI Schema (external link)](https://jsonforms.io/docs/uischema/) | [How UI schema is integrated in nullplatform](/docs/json-ui-schema/overview)
:::

## Design your scope service specification

Before you create the scope, ask yourself a few questions that we'll present in a table, so you
can see how your answers impact your scope specification:

| Question                                                      | Guidance                                                                                                                                                                                                                     |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| What's the name for the scope?                                | Choose a natural name (e.g., CronJob) and set it into the `name` field.                                                                                                                                                      |
| Which properties do I need to define for the scope?           | These are the properties that define the scope. 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 scope 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.                                                          |


## Create the scope specification

To set up an agent-backed scope:
- Create a new service of type `scope`.
- Declare the type of asset it will deploy.

You can create a scope specification using our [CLI](/docs/cli/) or [API](/docs/api/service-specification-create). 


Here’s an example of a scope that accepts `docker-image`
assets and includes a mandatory `warmup` parameter. 

<Tabs
defaultValue="create-service-spec-cli"
values={[
{ label: 'CLI', value: 'create-service-spec-cli' },
{ label: 'cURL', value: 'create-service-spec-curl' },
]}>
<TabItem value="create-service-spec-cli">

```bash
np service specification create \
    --body '{
    "name": "My scope name",                          
    "slug": "my-scope",
    "type": "scope",
    "visible_to": [
        "organization=1:account=2" // replace with a real NRN
    ],
    "attributes": {
        "schema": {
            "type": "object",
            "required": [
                "warmup"
            ],
            "properties": {
                "asset_type": {
                    "type": "string",
                    "export": false,
                    "default": "docker-image",
                    "readOnly": true
                },
                "warmup": {
                    "type": "boolean",
                    "export": false,
                    "readOnly": false
                }
            }
        },
        "values": {}
    },
    "selectors": {
        "category": "Deployment Services",
        "imported": false,
        "provider": "AWS",
        "sub_category": "Agent-backed Scope"
    }
}
```
  </TabItem>
  <TabItem value="create-service-spec-curl">

```bash
curl -L 'https://api.nullplatform.com/service_specification' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer the-token' \
-d '{
    "name": "My scope name",                          
    "type": "scope",
    "visible_to": [
        "organization=1:account=2" // replace with your NRN
    ],
    "attributes": {
        "schema": {
            "type": "object",
            "required": [
                "warmup"
            ],
            "properties": {
                "asset_type": {
                    "type": "string",
                    "export": false,
                    "default": "docker-image",
                    "readOnly": true
                },
                "warmup": {
                    "type": "boolean",
                    "export": false,
                    "readOnly": false
                }
            }
        },
        "values": {}
    },
    "selectors": {
        "category": "Deployment Services",
        "imported": false,
        "provider": "AWS",
        "sub_category": "Agent-backed Scope"
    }
}
```
  </TabItem>
</Tabs>

:::info Service details
The JSON schema under `attributes` determines the scope's attributes, fields, and layout in the UI. These properties
appear in the **See details** view in the nullplatform interface.
You can further enhance the rendering of that section using UI Schema.
:::

#### Some request details

- `attributes`: This field is mandatory and contains a JSON schema where you define:
    - the asset type for this scope.
    - the parameters that developers will have to set when creating or editing your scope.

  - `asset_type`: This parameter determines the types of assets that can be deployed to the scope.
      - **Single-asset scopes:** For scopes supporting a single asset type (e.g., `docker-images`), define 
          `asset_type` as an **optional** parameter with a default value.
      - **Multi-asset scopes:** For scopes supporting multiple asset types, make the `asset_type` a   **required** parameter so developers can select the type.

- Additional parameters: You can include optional parameters in your scope configuration. They can be:
    - **required**: Developers must provide values for these when creating a new scope.
    - **optional**: These can have default values and are not mandatory. 

    :::info
    As of April 2025, optional parameters are not displayed in the UI but can still be configured using [our API](https://docs.nullplatform.com/api/service-specification-create).
    :::