Schema compatibility requirements

When you click New service like this or Sync service with another, nullplatform tries to open a form with many of the original service’s values already filled in. This only works if two schemas are compatible:

1. Service spec attributes schema – defines the data structure stored in the service.
2. Action spec parameters schema – defines the data required to create or update the service.

important

To populate the form correctly, the parameter schema for the create and update actions must match—or be compatible with— the service’s attribute schema.

Here’s what that looks like in practice:

• If you're using default actions (use_default_actions: true):

  Compatibility is taken care of automatically. You don’t need to worry about the schemas matching—nullplatform ensures they align. See Service actions for more on use_default_actions.

• If you're not using default actions:

  You must ensure that the parameter inputs expected by your create or update action match the structure of your service’s attributes. For example, if the service includes endpoint_type, endpoints, and mtls_enabled, then the create action must also include these parameter inputs with the same types and structure.

// Example service attribute schema (subset)
"attributes": {
  "schema": {
    "type": "object",
    "required": ["endpoint_type"],
    "properties": {
      "endpoint_type": {
        "type": "string",
        "enum": ["PRIVATE", "PUBLIC"]
      },
      "endpoints": {
        "type": "array",
        "items": {
          "type": "object",
          "required": ["method", "path", "scope"],
          "properties": {
            "method": { "type": "string" },
            "path": { "type": "string" },
            "scope": { "type": "string" }
          }
        }
      },
      "mtls_enabled": {
        "type": "boolean"
      }
    }
  }
}

// Example create action parameter-input schema (subset)
"parameters": {
  "schema": {
    "type": "object",
    "required": ["endpoint_type"],
    "properties": {
      "endpoint_type": {
        "type": "string",
        "enum": ["PRIVATE", "PUBLIC"]
      },
      "endpoints": {
        "type": "array",
        "items": {
          "type": "object",
          "required": ["method", "path", "scope"],
          "properties": {
            "method": { "type": "string" },
            "path": { "type": "string" },
            "scope": { "type": "string" }
          }
        }
      },
      "mtls_enabled": {
        "type": "boolean"
      }
    }
  }
}

If the schemas don’t align, the form may not render correctly or the service creation or update may fail.

If you're encountering unexpected behavior when creating a new service based on another, double-check that the schemas are compatible—especially if you’re using custom definitions.