Skip to main content

Special schema keys

Inside your services and scopes (and their links/actions), and catalogs, you’ll define JSON schemas that specify the attributes of each specification. Within those schemas, there is a set of keys that have a special meaning across the platform. Get familiar with them to implement specs effectively.

List of special keys​

These are the special keys you should know about:

KeywordDescriptionApplicable toMore
secretMark attributes within a service or link as secret.• Services
• Scopes		See the secret section.
exportExport an attribute value as an application parameter.• Services
• Scopes		See the export section.
exportIgnoreExclude attributes when exporting values to application parameters.• Services
• Scopes		See export ignore.
targetMap an action result to an attribute in a service, catalog, scope, or link.• Services
• Scopes		See target.
configUse it to determine if an attribute or action parameter retrieves its value from an NRN entry.• Services
• Scopes		See config.
additionalKeywordsPopulate schema keywords dynamically from runtime context (instance, application, services, scopes).• Services
• Scopes		See additional keywords.
comparableExclude attributes from diff/compare views to avoid noisy changes.• Services
• Scopes		See comparable.
visibleOnControl property visibility by lifecycle stage (create, read, update).• Services
• Scopes
• Catalogs		See visibleOn.
editableOnControl when a property is editable by lifecycle stage.• Services
• Scopes
• Catalogs		See editableOn.

Secret​

Use secret: true to mark sensitive attributes within a service, scope, or link as secret so they’re hidden/redacted in responses and the UI.

{
  "attributes": {
    "schema": {
      "password": {
        "type": "string",
        "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​

Export an attribute’s value as an application parameter. The field can be either boolean or an object.

  • Boolean form
    • true: export as an environment variable using the spec slug and the attribute name.
    • false: do not export (equivalent to omitting the field).
  • Object form
{
  "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 sensitive value, set secret: true so the platform generates a secret parameter in your application.

{
  "attributes": {
    "schema": {
      "password": {
        "type": "integer",
        "export": {
          "secret": true
        },
        "readOnly": true
      }
    }
  }
}

Export ignore​

Use exportIgnore at the object level to exclude attributes when exporting values to application parameters.

exportIgnore: "my_attribute"
// or
exportIgnore: ["my_attribute", "another_attribute"]

Target​

Use target to map an action result to an attribute in your service or link.

 {
  "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 explicit

Attributes are not auto-mapped. You must declare a target for each result you want to persist.

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 make schema keywords dynamic using data from the current **service instance, application, or scopes.

Example: building enums dynamically​

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

You can apply additionalKeywords to any JSON Schema keyword (enum, default, minimum, maximum, …). Values are jq filters applied to a context of the form:

{
  "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​

Control visibility by lifecycle stage of the instance (service, catalog entity, or scope).

  • create — visible when creating the instance
  • read — visible when reading/viewing
  • update — visible when editing
  • list — visible as list columns (only available for builds at the moment)
{
  "attributes": {
    "schema": {
      "my_property": {
        "type": "string",
        "visibleOn": ["create", "update"]
      }
    }
  }
}
note

If empty, the default setting is "visibleOn": ["read", "create", "update"].

EditableOn​

Control when a property is editable by lifecycle stage.

  • create, read, update

If empty, the property is not editable in any stage.

{
  "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.

note

If empty, the default setting is "editableOn": ["read", "create", "update"].

Comparable​

To avoid noisy diffs, you can mark attributes non-comparable in your service specification using the comparable: false flag.

  • Default is true.

Example:

{
  "attributes": {
    "schema": {
      "account_id": {
        "type": "string",
        "config": { "key": "aws.account_id" },
        "export": false,
        "readOnly": true,
        "comparable": false
      }
    }
  }
}

These attributes will be excluded from diff outputs.