Special schema keys

Inside your services, links, and action specifications, you'll have JSON schemas that define which attributes will be part of your specification. Inside these schemas, there are a set of keys that have a special meaning for the services API and you must be familiarized with them to implement your services.

List of special keys

These are the special keys that you have to know about:

Keyword	Description	Description and examples
`secret`	Use it to mark specific attributes within a service or link as secret.	See the secret keyword section
`export`	Use it to export the value of this attribute as an application parameter	See the export keyword section.
`exportIgnore`	Specifies attributes to ignore when exporting their values to parameters.	See the export ignore section
`target`	Indicates which service/link attribute is modified by an action result.	See the specifying a target section.
`config`	Use it to retrieve if an attribute or action parameter retrieves its value from an NRN entry.	See the config keyword section.
`additionalKeywords`	Specifies additional keywords to generate a dynamic schema with values from a service instance, application, or scopes.	See the additional keywords section
`visibleOn`	Use it to make properties visible depending on the lifecycle of the instance.	See the visibleOn section
`editableOn`	Use it to make properties editable depending on the lifecycle of the instance.	See the editableOn section

Secret

The secret keyword is used to mark specific attributes within a service or link as secret. This ensures that sensitive information is handled securely and not exposed in API responses or the UI.

To mark an attribute as secret, set secret: true inside its schema definition.

{
// service spec...
"attributes": {
  "schema": {
    "password": {
      "type": "integer",
      "secret": true
      },
      "readOnly": true
    }
  }
}

note

If you have an action, remember to add the secret keyword in the parameters and results of the associated secret attribute.

Export

Use this keyword to export the value of this attribute as an application parameter.

The field can be either boolean or an object.

As a boolean:
- true will export the attribute as an environment variable using the name of the attribute as the parameter attribute name.
- false will not export the attribute (it has the same effect as when the value is not present at all).

As an object it must have this shape:

{
    "type": "environment_variable" | "file",
    "target": "name-of-the-env-var-or-file",
    "secret": true | false  
}

When using the object variant, note that:

The target parameter allows expression evaluation using the service and link as variables, for example:

{
  "type": "environment_variable",
  "target": "${service.slug}_${link.slug}",
  "secret": false  
}

Exporting a secret

If you need to export a sensible value, set the secret flag to true so nullplatform can generate a secret parameter in your application.

Here's an example:

{
  // service spec...
  "attributes": {
    "schema": {
      "password": {
        "type": "integer",
        "export": {
          // This will tell nullplatform to create a secret
          // parameter for the applications using this service 
          "secret": true
        },
        "readOnly": true
      }   
    }
  }
}

Export ignore

Use the exportIgnore keyword to control which service parameters should be excluded when exporting values to parameters. You define it at the object level in a link specification’s attribute schema.

For example, to ignore a single attribute:

exportIgnore: 'my_attribute'

To ignore multiple attributes:

exportIgnore: ['my_attribute', 'another_attribute']

Target

You can use the target field to map an action result to a service or link attribute.

Here's an example:

 {
  "id": "12341234-4321-abcd-134-abcd1324bdcda",
  "name": "S3 Bucket Update Action",
  "slug": "s3-bucket-update-action",
  "type": "update",
  // ... more properties
  "results": {
    "schema": {
      "type": "object",
      "required": [
        "bucket_arn",
        "bucket_id"
      ],
      "properties": {
        "bucket_id": {
          "type": "string",
          "target": "bucket_id"
          // <== the action's result 'bucket_id' will be assigned to the service's 'bucket_id'
        },
        "bucket_arn": {
          "type": "string",
          "target": "bucket_arn"
          // <== the action's result 'bucket_arn' will be assigned to the service's 'bucket_arn'
        }
      }
    },
    "values": {}
  }
}

targets must be explicitly declared

We won't automatically map attributes between action results and services/links if you don't explicitly create a target field.

Config

This config keyword tells nullplatform to map a field to an NRN key.

Here's an example where the account_id field will be filled with the aws.account_id key from the NRN API:

{
  "id": "12ced23430-bbff-495b-bbff-02fed729b0",
  "name": "Dynamo DB",
  "slug": "dynamodb",
  "type": "dependency",
  // ... service spec
  "attributes": {
    "schema": {
      "account_id": {
        "type": "string",
        "config": {
          // Here account_id will automatically take
          // the value from NRN's aws.account_id key
          "key": "aws.account_id"
        },
        "export": false,
        "readOnly": true
      }
    }
  }
}

Additional keywords

Use additionalKeywords to generate a dynamic schema with values from a service instance, application, or scopes.

Create enums using `additionalKeywords`

Example: how to choose roles from a list of available roles for the service.

...
{
  "roles": {
    "type": "array",
    "items": {
      "type": "string",
      "additionalKeywords": {
        "enum": ".service.attributes.availableRoles"
      }
    }
  }
}
...

You can apply additionalKeywords to any JSON schema keyword to make it dynamic, such as enum, default, minimum, maximum, etc.
The value of each additionalKeywords entry must be a jq command-line filter applied to the provided context, structured as follows:
```
{
  "service": { ... },
  "link": { ... },
  "application":{ ... },
  "scopes": [{ ... }, { ... }],
  "services": [{ ... }, { ... }]
}
```
keyword details
- service: The attributes of a specific service. You can reference values directly within the service.
- link: The attributes of a service link. You can reference values directly within the link.
- application: The attributes of the application. You can reference values directly within the application.
- scopes: All active scopes within the application. For example, it allows you to select services by scope_slug.
- services: All active services within the application. For example, it allows you to select services by specification_id.

Practical examples of using additionalKeywords with different jq filters:

{
  "additionalKeywords": {
    "enum": ".service.attributes.availableRoles",
    "enum": ". | [.scopes[]?.slug // \"You need to create an scope\"]",
    "enum": "[.services[] | select(.specification_id == \"xxx\") | .slug] | if length == 0 then [\"You need to create a yyyy\"] else . end",
    "default": ".application.metadata.my_metadata"
  }
}

VisibleOn

The visibleOn keyword is used to control the visibility of properties based on the lifecycle of the instance. It's an array of string that can contain the following values:

create: The property is visible when the instance is being created.
read: The property is visible when the instance is being read.
update: The property is visible when the instance is being updated. If the array is empty, the property won't be visible in all lifecycle stages.

Example

{
  "attributes": {
    "schema": {
      "my_property": {
        "type": "string",
        "visibleOn": ["create", "update"]
      }
    }
  }
}

EditableOn

The editableOn keyword is used to control the modification of properties based on the lifecycle of the instance. It's an array of string that can contain the following values:

create: The property is editable when the instance is being created.
read: The property is editable when the instance is being read.
update: The property is editable when the instance is being updated. If the array is empty, the property won't be editable in all lifecycle stages.

Example

{
  "attributes": {
    "schema": {
      "my_property": {
        "type": "string",
        "editableOn": ["create"]
      }
    }
  }
}

This indicates that my_property is only available to be set when the instance is being created.

List of special keys​

Secret​

Export​

Exporting a secret​

Export ignore​

Target​

Config​

Additional keywords​

Create enums using additionalKeywords​

VisibleOn​

Example​

EditableOn​

Example​

List of special keys

Secret

Export

Exporting a secret

Export ignore

Target

Config

Additional keywords

Create enums using `additionalKeywords`

VisibleOn

Example

EditableOn

Example