Build the solution · 5 / 5

Collect installation settings safely

Turn a schema into a clear integration configuration form.

YOUR TASK

Make this happen

3 steps

Add integration_document.settings in settings.cococo with identity com.academy.supplier, SDK 2.0 and version 1.0.0. Define required endpoint/token and optional retries default 3; mark token as password. Preserve both external schemas.
Keep the working capabilities from the previous lesson and connect the new pieces to the same solution.
Check the complete solution, then inspect any unmet requirements.

THE IDEA BEHIND IT

What this step adds

Add integration_document.settings in settings.cococo with identity com.academy.supplier, SDK 2.0 and version 1.0.0. Define required endpoint/token and optional retries default 3; mark token as password. Preserve both external schemas.

Files to work in

settings.cococo. Other files are the working baseline. New files include named resource skeletons and TODO guidance. Complete their fields and connect them using the objectives, schema completion and reference guide.

A contract in a real host

integration_document.configurationSchema accepts the native JSON Schema value. XML schema authoring is another representation of the same contract; native IaC objects avoid adding an XML layer here.

Annotations belong to their consumer

In integration configuration, x-input-type=password marks a secret input. The schema advertises required installation configuration; it does not supply credentials. A schema default is not a secret store. Product templates and workspace handlers use different supported vocabularies.

Local IaC input checks and lesson contracts do not replace platform JSON Schema/OpenAPI processing. No external references, uploads or embeddings run here.

Files to change: settings.cococo

What you’re building: Define a reliable supplier delivery contract, then make its API discoverable.

This step starts with the earlier solution and one new challenge. Each lesson keeps its own draft.

Read the starter files

main.cococo

external_schema "supplier" {
  name = "Supplier delivery contract"
  format = "JSON_SCHEMA"
  sourceText = file("contract.json")
}

contract.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Supplier delivery",
  "type": "object",
  "properties": {
    "trackingId": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "dispatched",
        "delivered"
      ],
      "default": "dispatched"
    },
    "packages": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "weightKg": {
            "type": "number",
            "exclusiveMinimum": 0
          }
        },
        "required": [
          "weightKg"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "trackingId",
    "packages"
  ],
  "additionalProperties": false
}

api.cococo

external_schema "api" {
  name = "Supplier delivery contract"
  format = "OPENAPI_3"
  sourceText = file("api.json")
}

api.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Supplier delivery API",
    "version": "1.0.0"
  },
  "paths": {
    "/deliveries": {
      "post": {
        "operationId": "createDelivery",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Delivery"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Delivery accepted"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Delivery": {
        "title": "Supplier delivery",
        "type": "object",
        "properties": {
          "trackingId": {
            "type": "string",
            "minLength": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "dispatched",
              "delivered"
            ],
            "default": "dispatched"
          },
          "packages": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "properties": {
                "weightKg": {
                  "type": "number",
                  "exclusiveMinimum": 0
                }
              },
              "required": [
                "weightKg"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "trackingId",
          "packages"
        ],
        "additionalProperties": false
      }
    }
  }
}

settings.cococo

integration_document "settings" {
  integrationId = "com.academy.supplier"
  sdkVersion = "2.0"
  version = "1.0.0"
  configurationSchema = {
    type = "object"
    additionalProperties = false
    properties = {
      # TODO: define endpoint (URI), token (password) and retries (integer).
    }
    required = [] # TODO: require endpoint and token.
    "x-propertyOrder" = ["endpoint", "token", "retries"]
  }
}

Reference: schemas · authoring schemas · external-schemas