1 KDSL JSON Schema Format

This document describes the JSON Schema format used to represent the interfaces of Kumori DSL Components and Services. This schema allows for external tools and systems to understand and validate the configuration, resources, and communication contracts of KDSL artifacts.

The kdsl tool, particularly the kdsl mod schema get command, generates schemas conforming to this specification.

1.1 Core JSON Schema Compatibility

The KDSLSchemaV1 format is built upon the JSON Schema Draft 2020-12 specification. This means that standard JSON Schema keywords are supported for defining data types and structures.

[!TIP] You can find a guides and specs of the JSONSchema syntax in the official json-schema.org website.

Currently, the following standard JSON Schema constructs are utilized:

type: Defines the basic data type of a value.
- string: For text values.
- number: For numerical values (integers or floats).
- boolean: For true/false values.
- null: For null values.
- array: For ordered lists of items.
  - items: Defines the schema for items within the array. Can be a single schema or an array of schemas for tuple validation.
- object: For unordered sets of key-value pairs.
  - properties: Defines the schema for specific named properties.
  - required: An array of strings listing properties that must be present.
  - additionalProperties: Defines the schema for properties not explicitly listed in properties.
const: Defines a fixed value that a property must be equal to (can be a string, number, or boolean).
oneOf: Specifies that the data must validate against exactly one of the provided subschemas.
An empty object {}: Represents a schema that allows any value.

While JSON Schema Draft 2020-12 offers many more keywords (e.g., enum, anyOf, allOf, not, patternProperties), KDSLSchemaV1 currently implements a subset of these, focusing on the essential elements for interface description.

1.2 KDSL-Specific Extensions

In addition to standard JSON Schema, KDSLSchemaV1 introduces a custom extension to represent KDSL’s strong type system, particularly for named types imported from other KDSL packages or the standard library.

1.2.1 `KDSLSchemaV1ExtensionNamedType`

This extension allows the schema to explicitly declare that a property’s type is a named KDSL type (e.g., kumori.Port, my.module/package.MyCustomType), while also providing its underlying JSON Schema representation.

1.2.2 Structure

A schema item representing a KDSL named type will have the following structure:

type: "kdsl": This is the primary indicator that this is a KDSL-specific type extension.
$kdsl: An object containing KDSL-specific metadata.
- NamedType: An object detailing the named type.
  - Import: A string representing the KDSL import path where the named type is defined (e.g., "kumori", "example.com/remote/example/package").
  - Name: A string representing the simple name of the type within its import (e.g., "Port", "HTTPServer").
inner: This property holds the standard JSON Schema definition that the KDSL named type ultimately resolves to. For instance, kumori.Port might internally be a string with specific format constraints. This allows JSON Schema validators to still understand the underlying data type.

1.2.3 Example

Consider a KDSL type kumori.Port that is fundamentally a string. Its representation in KDSLSchemaV1 might look like this:

{
  "type": "kdsl",
  "$kdsl": {
    "NamedType": {
      "Import": "kumori",
      "Name": "Port"
    }
  },
  "inner": { "type": "string" }
}

1.3 Top-Level Schema Structure (`KDSLSchemaV1`)

A complete KDSLSchemaV1 document for a Component or Service interface will have the following top-level properties:

$schema: Always set to "https://json-schema.org/draft/2020-12/schema", indicating the base JSON Schema draft.
$spec: Set to "kumori/schema/v1", identifying this as a KDSL-specific schema version.
$id: A string representing a unique identifier for this particular schema, typically derived from the module path, package path, artifact name, and version.
The rest of the schema will conform to KDSLSchemaV1Item, typically an object type describing the artifact’s config and resource properties.

Example of a Top-Level Schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$spec": "kumori/schema/v1",
  "$id": "<opaque_identifier>",
  "type": "object",
  "description": "Schema for the EchoServer component interface.",
  "properties": {
    "config": {
      "type": "object",
      "properties": {
        "Port": {
          "type": "number",
          "description": "The port number for the EchoServer."
        },
        "Response": {
          "type": "string",
          "description": "The response message from the EchoServer."
        }
      },
      "required": ["Port", "Response"]
    },
    "resource": {
      "type": "object",
      "properties": {
        "Volume": {
          "type": "kdsl",
          "$kdsl": {
            "NamedType": {
              "Import": "kumori",
              "Name": "Volume"
            }
          },
          "inner": {
            "type": "object",
            "properties": {
              "size": { "type": "number" },
              "unit": { "type": "string", "const": "G" }
            },
            "required": ["size", "unit"]
          }
        }
      },
      "required": ["Volume"]
    }
  },
  "required": []
}

This KDSLSchemaV1 format provides a robust and extensible way to describe KDSL artifact interfaces, enabling introspection and automation.