@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

package/src/schemas/types/xyz-d65-color/from-linear-srgb.tokenscript

@@ -0,0 +1,38 @@
+// Linear sRGB to XYZ-D65 Conversion
+// Uses the sRGB primaries transformation matrix
+// Reference: IEC 61966-2-1:1999 (sRGB specification)
+//
+// Matrix (Linear RGB → XYZ-D65):
+// [X]   [0.4123908  0.3575843  0.1804808] [R]
+// [Y] = [0.2126390  0.7151687  0.0721923] [G]
+// [Z]   [0.0193308  0.1191948  0.9505322] [B]
+//
+// Input: Color.LinearSRGB with r, g, b in linear 0-1 range
+// Output: Color.XYZD65 with x, y, z tristimulus values
+
+// Get input linear sRGB values
+variable r: Number = {input}.r;
+variable g: Number = {input}.g;
+variable b: Number = {input}.b;
+
+// Matrix multiplication: M × [R, G, B]ᵀ
+// Row 1: X = 0.4123908 * R + 0.3575843 * G + 0.1804808 * B
+variable x: Number = r * 0.41239079926595934 + g * 0.357584339383878 + b * 0.1804807884018343;
+
+// Row 2: Y = 0.2126390 * R + 0.7151687 * G + 0.0721923 * B
+variable y: Number = r * 0.21263900587151027 + g * 0.715168678767756 + b * 0.07219231536073371;
+
+// Row 3: Z = 0.0193308 * R + 0.1191948 * G + 0.9505322 * B
+variable z: Number = r * 0.01933081871559182 + g * 0.11919477979462598 + b * 0.9505321522496607;
+
+// Create output
+variable output: Color.XYZD65;
+output.x = x;
+output.y = y;
+output.z = z;
+
+return output;
+
+
+
+

package/src/schemas/types/xyz-d65-color/from-oklab.tokenscript

@@ -0,0 +1,44 @@
+// OKLab to XYZ-D65 Conversion
+// Reference: ColorJS oklab.js (inverse transformation)
+//
+// Algorithm:
+// 1. Apply inverse Lab-to-LMS matrix to get LMS cone responses
+// 2. Cube the LMS values (inverse of cube root)
+// 3. Apply inverse LMS-to-XYZ matrix
+//
+// Input: Color.OKLab with l, a, b perceptual coordinates
+// Output: Color.XYZD65 with x, y, z tristimulus values
+
+// Get input OKLab values
+variable ok_l: Number = {input}.l;
+variable ok_a: Number = {input}.a;
+variable ok_b: Number = {input}.b;
+
+// Inverse LMStoLab_M matrix (Lab to LMS')
+// These are the inverse of the matrix used in from-xyz-d65.tokenscript
+variable lms_l: Number = 1.0 * ok_l + 0.3963377773761749 * ok_a + 0.2158037573099136 * ok_b;
+variable lms_m: Number = 1.0 * ok_l + -0.1055613458156586 * ok_a + -0.0638541728258133 * ok_b;
+variable lms_s: Number = 1.0 * ok_l + -0.0894841775298119 * ok_a + -1.2914855480194092 * ok_b;
+
+// Cube the values (inverse of cube root)
+variable lms_l_cubed: Number = lms_l * lms_l * lms_l;
+variable lms_m_cubed: Number = lms_m * lms_m * lms_m;
+variable lms_s_cubed: Number = lms_s * lms_s * lms_s;
+
+// Inverse XYZtoLMS_M matrix (LMS to XYZ)
+// From ColorJS oklab.js
+variable x: Number = 1.2268798758459243 * lms_l_cubed + -0.5578149944602171 * lms_m_cubed + 0.2813910456659647 * lms_s_cubed;
+variable y: Number = -0.0405757452148008 * lms_l_cubed + 1.1122868032803170 * lms_m_cubed + -0.0717110580655164 * lms_s_cubed;
+variable z: Number = -0.0763729366746601 * lms_l_cubed + -0.4214933324022432 * lms_m_cubed + 1.5869240198367816 * lms_s_cubed;
+
+// Create output
+variable output: Color.XYZD65;
+output.x = x;
+output.y = y;
+output.z = z;
+
+return output;
+
+
+
+

package/src/schemas/types/xyz-d65-color/initializer.tokenscript

@@ -0,0 +1,16 @@
+// XYZ-D65 Color Initializer
+// Creates an XYZ-D65 color from tristimulus values
+// Input: List of [x, y, z] tristimulus values
+
+variable xyz_values: List = {input};
+variable output: Color.XYZD65;
+
+output.x = xyz_values.get(0);
+output.y = xyz_values.get(1);
+output.z = xyz_values.get(2);
+
+return output;
+
+
+
+

package/src/schemas/types/xyz-d65-color/schema.json

@@ -0,0 +1,68 @@
+{
+  "name": "XYZD65",
+  "type": "color",
+  "description": "CIE XYZ color space with D65 white point. The primary connection hub for color space conversions.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "x": {
+        "type": "number",
+        "description": "X tristimulus value"
+      },
+      "y": {
+        "type": "number",
+        "description": "Y tristimulus value (luminance)"
+      },
+      "z": {
+        "type": "number",
+        "description": "Z tristimulus value"
+      }
+    },
+    "required": ["x", "y", "z"],
+    "order": ["x", "y", "z"],
+    "additionalProperties": false
+  },
+  "initializers": [
+    {
+      "title": "XYZ-D65 Color Initializer",
+      "keyword": "xyzd65",
+      "description": "Creates an XYZ-D65 color from tristimulus values",
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./initializer.tokenscript"
+      }
+    }
+  ],
+  "conversions": [
+    {
+      "source": "/api/v1/core/srgb-linear-color/0/",
+      "target": "$self",
+      "description": "Converts Linear sRGB to XYZ-D65 using the sRGB transformation matrix",
+      "lossless": true,
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./from-linear-srgb.tokenscript"
+      }
+    },
+    {
+      "source": "/api/v1/core/p3-linear-color/0/",
+      "target": "$self",
+      "description": "Converts Linear P3 to XYZ-D65 using the P3 transformation matrix",
+      "lossless": true,
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./from-linear-p3.tokenscript"
+      }
+    },
+    {
+      "source": "/api/v1/core/oklab-color/0/",
+      "target": "$self",
+      "description": "Converts OKLab to XYZ-D65 using inverse LMS transformation",
+      "lossless": true,
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./from-oklab.tokenscript"
+      }
+    }
+  ]
+}

package/src/schemas/types/xyz-d65-color/unit.test.ts

@@ -0,0 +1,319 @@
+/**
+ * XYZ-D65 Color Schema Tests
+ *
+ * Tests for the CIE XYZ-D65 color space (the connection hub)
+ * Validates against ColorJS for parity
+ */
+
+import { log } from "@tests/helpers/logger";
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import Color from "colorjs.io";
+import { describe, expect, it } from "vitest";
+import type { ColorSpecification } from "@/bundler/types";
+
+// ColorJS reference tolerance
+const TOLERANCE = 1e-9;
+
+describe("XYZ-D65 Color Schema", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("xyz-d65-color")) as ColorSpecification;
+
+      expect(schema.name).toBe("XYZD65");
+      expect(schema.type).toBe("color");
+      expect(schema.schema).toBeDefined();
+      expect(schema.schema?.properties).toHaveProperty("x");
+      expect(schema.schema?.properties).toHaveProperty("y");
+      expect(schema.schema?.properties).toHaveProperty("z");
+      expect(schema.schema?.required).toEqual(["x", "y", "z"]);
+    });
+
+    it("should have xyzd65 initializer", async () => {
+      const schema = (await getBundledSchema("xyz-d65-color")) as ColorSpecification;
+
+      expect(schema.initializers).toHaveLength(1);
+      expect(schema.initializers[0].keyword).toBe("xyzd65");
+      expect(schema.initializers[0].script.script).toContain("Color.XYZD65");
+    });
+
+    it("should have conversions from Linear sRGB and Linear P3", async () => {
+      const schema = (await getBundledSchema("xyz-d65-color")) as ColorSpecification;
+
+      expect(schema.conversions.length).toBeGreaterThanOrEqual(2);
+
+      const linearSrgbToXyz = schema.conversions.find((c: { source: string }) =>
+        c.source.includes("srgb-linear-color"),
+      );
+      expect(linearSrgbToXyz).toBeDefined();
+      expect(linearSrgbToXyz?.lossless).toBe(true);
+
+      const linearP3ToXyz = schema.conversions.find((c: { source: string }) =>
+        c.source.includes("p3-linear-color"),
+      );
+      expect(linearP3ToXyz).toBeDefined();
+      expect(linearP3ToXyz?.lossless).toBe(true);
+    });
+  });
+
+  describe("Initialization", () => {
+    it("should create XYZ-D65 color from values", async () => {
+      const result = await executeWithSchema(
+        "xyz-d65-color",
+        "type",
+        `
+        variable c: Color.XYZD65;
+        c.x = 0.5;
+        c.y = 0.4;
+        c.z = 0.3;
+        c
+      `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      expect((result as any).subType).toBe("XYZD65");
+      expect((result as any).value.x.value).toBeCloseTo(0.5, 10);
+      expect((result as any).value.y.value).toBeCloseTo(0.4, 10);
+      expect((result as any).value.z.value).toBeCloseTo(0.3, 10);
+    });
+  });
+
+  describe("Conversion from Linear sRGB to XYZ-D65", () => {
+    it("should convert linear red to XYZ-D65", async () => {
+      const result = await executeWithSchema(
+        "xyz-d65-color",
+        "type",
+        `
+        variable linear: Color.LinearSRGB;
+        linear.r = 1;
+        linear.g = 0;
+        linear.b = 0;
+        linear.to.xyzd65()
+      `,
+      );
+
+      // ColorJS reference
+      const colorJS = new Color("srgb-linear", [1, 0, 0]).to("xyz-d65");
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      expect((result as any).subType).toBe("XYZD65");
+      expect((result as any).value.x.value).toBeCloseTo(colorJS.coords[0], 9);
+      expect((result as any).value.y.value).toBeCloseTo(colorJS.coords[1], 9);
+      expect((result as any).value.z.value).toBeCloseTo(colorJS.coords[2], 9);
+    });
+
+    it("should convert linear green to XYZ-D65", async () => {
+      const result = await executeWithSchema(
+        "xyz-d65-color",
+        "type",
+        `
+        variable linear: Color.LinearSRGB;
+        linear.r = 0;
+        linear.g = 1;
+        linear.b = 0;
+        linear.to.xyzd65()
+      `,
+      );
+
+      const colorJS = new Color("srgb-linear", [0, 1, 0]).to("xyz-d65");
+
+      expect((result as any).value.x.value).toBeCloseTo(colorJS.coords[0], 9);
+      expect((result as any).value.y.value).toBeCloseTo(colorJS.coords[1], 9);
+      expect((result as any).value.z.value).toBeCloseTo(colorJS.coords[2], 9);
+    });
+
+    it("should convert linear blue to XYZ-D65", async () => {
+      const result = await executeWithSchema(
+        "xyz-d65-color",
+        "type",
+        `
+        variable linear: Color.LinearSRGB;
+        linear.r = 0;
+        linear.g = 0;
+        linear.b = 1;
+        linear.to.xyzd65()
+      `,
+      );
+
+      const colorJS = new Color("srgb-linear", [0, 0, 1]).to("xyz-d65");
+
+      expect((result as any).value.x.value).toBeCloseTo(colorJS.coords[0], 9);
+      expect((result as any).value.y.value).toBeCloseTo(colorJS.coords[1], 9);
+      expect((result as any).value.z.value).toBeCloseTo(colorJS.coords[2], 9);
+    });
+
+    it("should convert linear white to XYZ-D65 (D65 white point)", async () => {
+      const result = await executeWithSchema(
+        "xyz-d65-color",
+        "type",
+        `
+        variable linear: Color.LinearSRGB;
+        linear.r = 1;
+        linear.g = 1;
+        linear.b = 1;
+        linear.to.xyzd65()
+      `,
+      );
+
+      const colorJS = new Color("srgb-linear", [1, 1, 1]).to("xyz-d65");
+
+      // D65 white point should sum the matrix rows
+      log.info(`\n=== D65 WHITE POINT ===`);
+      log.info(
+        `TokenScript: { x: ${(result as any).value.x.value}, y: ${(result as any).value.y.value}, z: ${(result as any).value.z.value} }`,
+      );
+      log.info(
+        `ColorJS:     { x: ${colorJS.coords[0]}, y: ${colorJS.coords[1]}, z: ${colorJS.coords[2]} }`,
+      );
+
+      expect((result as any).value.x.value).toBeCloseTo(colorJS.coords[0], 9);
+      expect((result as any).value.y.value).toBeCloseTo(colorJS.coords[1], 9);
+      expect((result as any).value.z.value).toBeCloseTo(colorJS.coords[2], 9);
+    });
+  });
+
+  describe("ColorJS Parity", () => {
+    const testCases = [
+      { name: "red", linear: [1, 0, 0] },
+      { name: "green", linear: [0, 1, 0] },
+      { name: "blue", linear: [0, 0, 1] },
+      { name: "black", linear: [0, 0, 0] },
+      { name: "white", linear: [1, 1, 1] },
+      { name: "gray-21.4%", linear: [0.214, 0.214, 0.214] }, // sRGB 50% gray
+      { name: "coral-linear", linear: [1, 0.095, 0.033] },
+      { name: "cyan", linear: [0, 1, 1] },
+      { name: "magenta", linear: [1, 0, 1] },
+      { name: "yellow", linear: [1, 1, 0] },
+    ];
+
+    for (const { name, linear } of testCases) {
+      it(`should match ColorJS for ${name}`, async () => {
+        const result = await executeWithSchema(
+          "xyz-d65-color",
+          "type",
+          `
+          variable linear: Color.LinearSRGB;
+          linear.r = ${linear[0]};
+          linear.g = ${linear[1]};
+          linear.b = ${linear[2]};
+          linear.to.xyzd65()
+        `,
+        );
+
+        // ColorJS reference
+        const colorJS = new Color("srgb-linear", linear as [number, number, number]).to("xyz-d65");
+
+        const tsX = (result as any).value.x.value;
+        const tsY = (result as any).value.y.value;
+        const tsZ = (result as any).value.z.value;
+
+        const diffX = Math.abs(tsX - colorJS.coords[0]);
+        const diffY = Math.abs(tsY - colorJS.coords[1]);
+        const diffZ = Math.abs(tsZ - colorJS.coords[2]);
+        const maxDiff = Math.max(diffX, diffY, diffZ);
+
+        log.info(`\n=== ${name.toUpperCase()} ColorJS Parity ===`);
+        log.info(`Input Linear: { r: ${linear[0]}, g: ${linear[1]}, b: ${linear[2]} }`);
+        log.info(
+          `TokenScript:  { x: ${tsX.toFixed(9)}, y: ${tsY.toFixed(9)}, z: ${tsZ.toFixed(9)} }`,
+        );
+        log.info(
+          `ColorJS:      { x: ${colorJS.coords[0].toFixed(9)}, y: ${colorJS.coords[1].toFixed(9)}, z: ${colorJS.coords[2].toFixed(9)} }`,
+        );
+        log.info(`Max Diff:     ${maxDiff.toExponential(2)}`);
+        log.info(`Status:       ${maxDiff < TOLERANCE ? "✅ PASS" : "❌ FAIL"}`);
+
+        expect(maxDiff).toBeLessThan(TOLERANCE);
+      });
+    }
+  });
+
+  describe("Full Conversion Chain: sRGB → Linear sRGB → XYZ-D65", () => {
+    it("should convert sRGB red through to XYZ-D65", async () => {
+      const result = await executeWithSchema(
+        "xyz-d65-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 1;
+        srgb.g = 0;
+        srgb.b = 0;
+        
+        variable linear: Color.LinearSRGB = srgb.to.linearsrgb();
+        linear.to.xyzd65()
+      `,
+      );
+
+      // ColorJS reference: sRGB → XYZ-D65
+      const colorJS = new Color("srgb", [1, 0, 0]).to("xyz-d65");
+
+      expect((result as any).value.x.value).toBeCloseTo(colorJS.coords[0], 9);
+      expect((result as any).value.y.value).toBeCloseTo(colorJS.coords[1], 9);
+      expect((result as any).value.z.value).toBeCloseTo(colorJS.coords[2], 9);
+    });
+
+    it("should convert sRGB mid-gray through to XYZ-D65", async () => {
+      const result = await executeWithSchema(
+        "xyz-d65-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 0.5;
+        srgb.g = 0.5;
+        srgb.b = 0.5;
+        
+        variable linear: Color.LinearSRGB = srgb.to.linearsrgb();
+        linear.to.xyzd65()
+      `,
+      );
+
+      // ColorJS reference
+      const colorJS = new Color("srgb", [0.5, 0.5, 0.5]).to("xyz-d65");
+
+      log.info(`\n=== sRGB 50% GRAY → XYZ-D65 (full chain) ===`);
+      log.info(
+        `TokenScript: { x: ${(result as any).value.x.value}, y: ${(result as any).value.y.value}, z: ${(result as any).value.z.value} }`,
+      );
+      log.info(
+        `ColorJS:     { x: ${colorJS.coords[0]}, y: ${colorJS.coords[1]}, z: ${colorJS.coords[2]} }`,
+      );
+
+      expect((result as any).value.x.value).toBeCloseTo(colorJS.coords[0], 9);
+      expect((result as any).value.y.value).toBeCloseTo(colorJS.coords[1], 9);
+      expect((result as any).value.z.value).toBeCloseTo(colorJS.coords[2], 9);
+    });
+  });
+
+  describe("Full Conversion Chain: RGB (0-255) → sRGB → Linear sRGB → XYZ-D65", () => {
+    it("should convert RGB #ff5733 through entire chain to XYZ-D65", async () => {
+      const result = await executeWithSchema(
+        "xyz-d65-color",
+        "type",
+        `
+        variable rgb: Color.Rgb;
+        rgb.r = 255;
+        rgb.g = 87;
+        rgb.b = 51;
+        
+        variable srgb: Color.SRGB = rgb.to.srgb();
+        variable linear: Color.LinearSRGB = srgb.to.linearsrgb();
+        linear.to.xyzd65()
+      `,
+      );
+
+      // ColorJS reference: #ff5733 → XYZ-D65
+      const colorJS = new Color("#ff5733").to("xyz-d65");
+
+      log.info(`\n=== RGB #ff5733 → XYZ-D65 (full chain) ===`);
+      log.info(
+        `TokenScript: { x: ${(result as any).value.x.value}, y: ${(result as any).value.y.value}, z: ${(result as any).value.z.value} }`,
+      );
+      log.info(
+        `ColorJS:     { x: ${colorJS.coords[0]}, y: ${colorJS.coords[1]}, z: ${colorJS.coords[2]} }`,
+      );
+
+      expect((result as any).value.x.value).toBeCloseTo(colorJS.coords[0], 8);
+      expect((result as any).value.y.value).toBeCloseTo(colorJS.coords[1], 8);
+      expect((result as any).value.z.value).toBeCloseTo(colorJS.coords[2], 8);
+    });
+  });
+});

package/src/utils/schema-uri.ts

@@ -0,0 +1,192 @@
+/**
+ * Utilities for working with TokenScript schema URIs
+ *
+ * Handles URI construction, parsing, and manipulation for the TokenScript schema registry.
+ */
+
+import { isObject } from "./type";
+
+export type SemanticVersion =
+  | { major: number }
+  | { major: number; minor: number }
+  | { major: number; minor: number; patch: number };
+
+type SchemaVersion = "latest" | SemanticVersion | null;
+
+export interface SchemaUriComponents {
+  baseUrl: string;
+  category: "schema" | "core" | "function";
+  name: string;
+  version: SchemaVersion;
+}
+
+export const DEFAULT_REGISTRY_URL = "https://schema.tokenscript.dev.gcp.tokens.studio";
+
+export const DEFAULT_API_PATH = "/api/v1";
+
+function safeParseInt(value: string): number | null {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+export function parseSemverFromString(versionString: string): SemanticVersion | null {
+  const parts = versionString.split(".");
+  const numbers: number[] = [];
+
+  for (const part of parts) {
+    const num = safeParseInt(part);
+    if (num === null) return null;
+    numbers.push(num);
+  }
+
+  if (numbers.length !== parts.length) return null;
+
+  if (numbers.length === 3) {
+    return { major: numbers[0], minor: numbers[1], patch: numbers[2] };
+  }
+
+  if (numbers.length === 2) {
+    return { major: numbers[0], minor: numbers[1] };
+  }
+
+  if (numbers.length === 1) {
+    return { major: numbers[0] };
+  }
+
+  return null;
+}
+
+export function parseVersionString(versionString: string): SchemaVersion {
+  return versionString === "latest" ? "latest" : parseSemverFromString(versionString);
+}
+
+export function semverToString(version: SchemaVersion | undefined): string {
+  if (version === undefined) {
+    return "latest";
+  }
+  if (isObject(version)) {
+    if ("patch" in version) return `${version.major}.${version.minor}.${version.patch}`;
+    if ("minor" in version) return `${version.major}.${version.minor}`;
+    return `${version.major}`;
+  }
+  return "latest";
+}
+
+export function buildSchemaUri(
+  params: Partial<SchemaUriComponents> & { category: string; name: string },
+): string {
+  const { baseUrl, category, name, version } = params;
+
+  const versionString = semverToString(version);
+
+  const effectiveBaseUrl = baseUrl === undefined ? DEFAULT_REGISTRY_URL : baseUrl;
+
+  if (effectiveBaseUrl === "") {
+    return `${DEFAULT_API_PATH}/${category}/${name}/${versionString}/`;
+  }
+
+  return `${effectiveBaseUrl}${DEFAULT_API_PATH}/${category}/${name}/${versionString}/`;
+}
+
+/**
+ * Parse a schema URI into its components
+ *
+ * @example
+ * parseSchemaUri("https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/schema/rgb-color/0.0.1/")
+ * // => { baseUrl: "...", category: "schema", name: "rgb-color", version: "0.0.1" }
+ *
+ * parseSchemaUri("/api/v1/schema/rgb-color/0.0.1/")
+ * // => { baseUrl: "", category: "schema", name: "rgb-color", version: "0.0.1" }
+ */
+export function parseSchemaUri(uri: string): SchemaUriComponents | null {
+  let baseUrl = "";
+  let pathname = uri;
+
+  // Try parsing as full URL first
+  try {
+    const url = new URL(uri);
+    baseUrl = `${url.protocol}//${url.host}`;
+    pathname = url.pathname;
+  } catch {
+    // If URL parsing fails, treat as relative path
+    // Check if it starts with a protocol (incomplete URL)
+    if (uri.includes("://")) {
+      return null;
+    }
+    // It's a relative path, use as-is
+    pathname = uri;
+  }
+
+  // Parse pathname: /api/v1/schema/rgb-color/0.0.1/
+  const pathParts = pathname.split("/").filter((part) => part !== "");
+
+  // Expected format: [api, v1, category, name, version]
+  if (pathParts.length < 5) {
+    return null;
+  }
+
+  // Check if it starts with api/vN
+  if (pathParts[0] !== "api" || !pathParts[1].startsWith("v")) {
+    return null;
+  }
+
+  const category = pathParts[2];
+  if (category !== "schema" && category !== "core" && category !== "function") {
+    return null;
+  }
+
+  const name = pathParts[3];
+  const version = parseVersionString(pathParts[4]);
+
+  return {
+    baseUrl,
+    category: category as "schema" | "core" | "function",
+    name,
+    version,
+  };
+}
+
+/**
+ * Extract the base URI without version
+ *
+ * @example
+ * getBaseUri("https://.../api/v1/schema/rgb-color/0.0.1/")
+ * // => "https://.../api/v1/schema/rgb-color/"
+ *
+ * getBaseUri("/api/v1/schema/rgb-color/0.0.1/")
+ * // => "/api/v1/schema/rgb-color/"
+ */
+export function getBaseUri(uri: string): string {
+  const components = parseSchemaUri(uri);
+
+  if (!components) {
+    return uri;
+  }
+
+  const { baseUrl, category, name } = components;
+
+  if (baseUrl === "") {
+    return `${DEFAULT_API_PATH}/${category}/${name}/`;
+  }
+
+  return `${baseUrl}${DEFAULT_API_PATH}/${category}/${name}/`;
+}
+
+/**
+ * Extract schema name from URI
+ *
+ * @example
+ * extractSchemaName("https://.../api/v1/schema/rgb-color/0.0.1/")
+ * // => "rgb-color"
+ */
+export function extractSchemaName(uri: string): string | null {
+  const components = parseSchemaUri(uri);
+  return components?.name || null;
+}
+
+/**
+ * Normalize URI to ensure it ends with trailing slash
+ */
+export function normalizeUri(uri: string): string {
+  return uri.endsWith("/") ? uri : `${uri}/`;
+}