Build the solution · 4 / 5

Make the supplier API discoverable

Package the delivery contract with its endpoint for integration authors.

YOUR TASK

Make this happen

3 steps

Add a separate OPENAPI_3 external_schema.api backed by api.json. Define POST /deliveries, createDelivery, required Delivery request body and 202 response; retain the original JSON contract resource.
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 a separate OPENAPI_3 external_schema.api backed by api.json. Define POST /deliveries, createDelivery, required Delivery request body and 202 response; retain the original JSON contract resource.

Files to work in

api.cococo, api.json. 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.

One contract, a discoverable endpoint

The request references a reusable model rather than copying its fields. OpenAPI adds endpoints, parameters and responses to the schema inventory that integration authors search.

Finish on the platform

After upload, wait for READY; FAILED exposes errorMessage. Search the indexed endpoint/model entries, then build a schema client. Browser checking here does not upload, fetch external references or create embeddings. Documents are limited to 5 MB.

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: api.cococo, api.json

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"
  # Source file supplied for this field: api.json
  # TODO: attach it with sourceText = file(...).
}

api.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Supplier delivery API",
    "version": "1.0.0"
  },
  "paths": {},
  "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
      }
    }
  }
}

Reference: schemas · authoring schemas · external-schemas