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
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

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

The exportIgnore keyword specifies at the object level in a link specification attributes schema whether one or more service parameters should be ignored when exporting their values to parameters. For example:

exportIgnore: 'my_attribute'

or:

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"
    }
  }