@openpkg-ts/spec 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -8,13 +8,113 @@ type SpecTag = {
 	version?: string;
 	reason?: string;
 };
+type SpecTypeAliasKind = "alias" | "conditional" | "mapped" | "template-literal" | "infer";
+type SpecConditionalType = {
+	checkType: string;
+	extendsType: string;
+	trueType: string;
+	falseType: string;
+};
+type SpecMappedType = {
+	typeParameter: string;
+	nameType?: string;
+	valueType?: string;
+	readonly?: "+" | "-" | true;
+	optional?: "+" | "-" | true;
+};
+type SpecDecorator = {
+	name: string;
+	arguments?: unknown[];
+	argumentsText?: string[];
+};
+type SpecThrows = {
+	type?: string;
+	description?: string;
+};
 type SpecSource = {
 	file?: string;
 	line?: number;
 	url?: string;
 };
-type SpecSchema = unknown;
-type SpecExample = Record<string, unknown>;
+type SpecSchemaPrimitive = {
+	type: "string";
+	format?: string;
+	enum?: string[];
+} | {
+	type: "number";
+	enum?: number[];
+} | {
+	type: "boolean";
+	enum?: boolean[];
+} | {
+	type: "integer";
+	format?: string;
+} | {
+	type: "null";
+} | {
+	type: "undefined";
+} | {
+	type: "any";
+} | {
+	type: "unknown";
+} | {
+	type: "never";
+} | {
+	type: "void";
+};
+type SpecSchemaComposite = {
+	type: "array";
+	items?: SpecSchema;
+} | {
+	type: "tuple";
+	items: SpecSchema[];
+	minItems?: number;
+	maxItems?: number;
+} | {
+	type: "object";
+	properties?: Record<string, SpecSchema>;
+	required?: string[];
+	additionalProperties?: boolean | SpecSchema;
+	description?: string;
+} | {
+	type: "function";
+	signatures?: SpecSignature[];
+};
+type SpecSchemaCombinator = {
+	anyOf: SpecSchema[];
+	discriminator?: {
+		propertyName: string;
+	};
+} | {
+	allOf: SpecSchema[];
+} | {
+	oneOf: SpecSchema[];
+};
+type SpecSchemaRef = {
+	$ref: string;
+};
+type SpecSchemaFallback = {
+	type: string;
+	tsType?: string;
+};
+type SpecSchemaGeneric = Record<string, unknown>;
+type SpecSchema = string | SpecSchemaPrimitive | SpecSchemaComposite | SpecSchemaCombinator | SpecSchemaRef | SpecSchemaFallback | SpecSchemaGeneric;
+type SpecExampleLanguage = "ts" | "js" | "tsx" | "jsx" | "shell" | "json";
+type SpecExample = {
+	code: string;
+	title?: string;
+	description?: string;
+	language?: SpecExampleLanguage;
+	runnable?: boolean;
+	expectedOutput?: string;
+	tags?: string[];
+};
+type SpecRelationType = "uses" | "returns" | "implements" | "extends" | "see-also" | "companion";
+type SpecRelation = {
+	type: SpecRelationType;
+	target: string;
+	description?: string;
+};
 type SpecExtension = Record<string, unknown>;
 type SpecDocSignal = "description" | "params" | "returns" | "examples";
 type SpecDocDrift = {
@@ -41,6 +141,7 @@ type SpecSignatureParameter = {
 	schema: SpecSchema;
 	default?: unknown;
 	rest?: boolean;
+	decorators?: SpecDecorator[];
 };
 type SpecSignatureReturn = {
 	schema: SpecSchema;
@@ -54,6 +155,7 @@ type SpecSignature = {
 	typeParameters?: SpecTypeParameter[];
 	overloadIndex?: number;
 	isImplementation?: boolean;
+	throws?: SpecThrows[];
 };
 type SpecMember = {
 	id?: string;
@@ -65,6 +167,7 @@ type SpecMember = {
 	flags?: Record<string, unknown>;
 	schema?: SpecSchema;
 	signatures?: SpecSignature[];
+	decorators?: SpecDecorator[];
 };
 type SpecExportKind = "function" | "class" | "variable" | "interface" | "type" | "enum" | "module" | "namespace" | "reference" | "external";
 type SpecTypeKind = "class" | "interface" | "type" | "enum" | "external";
@@ -83,7 +186,7 @@ type SpecExport = {
 	type?: string | SpecSchema;
 	schema?: SpecSchema;
 	description?: string;
-	examples?: string[];
+	examples?: (string | SpecExample)[];
 	docs?: SpecDocsMetadata;
 	source?: SpecSource;
 	deprecated?: boolean;
@@ -91,6 +194,13 @@ type SpecExport = {
 	tags?: SpecTag[];
 	extends?: string;
 	implements?: string[];
+	typeAliasKind?: SpecTypeAliasKind;
+	conditionalType?: SpecConditionalType;
+	mappedType?: SpecMappedType;
+	decorators?: SpecDecorator[];
+	isAugmentation?: boolean;
+	augmentedModule?: string;
+	related?: SpecRelation[];
 };
 type SpecType = {
 	id: string;
@@ -110,6 +220,10 @@ type SpecType = {
 	rawComments?: string;
 	extends?: string;
 	implements?: string[];
+	typeAliasKind?: SpecTypeAliasKind;
+	conditionalType?: SpecConditionalType;
+	mappedType?: SpecMappedType;
+	related?: SpecRelation[];
 };
 type OpenPkgMeta = {
 	name: string;
@@ -211,4 +325,4 @@ declare function assertSpec(spec: unknown, version?: SchemaVersion): asserts spe
 * @returns Array of validation errors (empty if valid)
 */
 declare function getValidationErrors(spec: unknown, version?: SchemaVersion): SpecError[];
-export { validateSpec, normalize, getValidationErrors, diffSpec, dereference, categorizeBreakingChanges, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecType, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchema, SpecMember, SpecExtension, SpecExportKind, SpecExport, SpecExample, SpecDocsMetadata, SpecDocSignal, SpecDocDrift, SpecDiff, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, CategorizedBreaking, BreakingSeverity };
+export { validateSpec, normalize, getValidationErrors, diffSpec, dereference, categorizeBreakingChanges, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecRelationType, SpecRelation, SpecMember, SpecMappedType, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDocsMetadata, SpecDocSignal, SpecDocDrift, SpecDiff, SpecDecorator, SpecConditionalType, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, CategorizedBreaking, BreakingSeverity };

package/dist/index.js

@@ -1244,7 +1244,7 @@ var openpkg_schema_default3 = {
           type: "array",
           description: "Usage examples from documentation",
           items: {
-            type: "string"
+            $ref: "#/$defs/example"
           }
         },
         signatures: {
@@ -1285,6 +1285,38 @@ var openpkg_schema_default3 = {
         docs: {
           $ref: "#/$defs/docsMetadata",
           description: "Documentation coverage metadata for this export"
+        },
+        typeAliasKind: {
+          $ref: "#/$defs/typeAliasKind",
+          description: "Kind of type alias (for type exports)"
+        },
+        conditionalType: {
+          $ref: "#/$defs/conditionalType",
+          description: "Structural details for conditional types"
+        },
+        mappedType: {
+          $ref: "#/$defs/mappedType",
+          description: "Structural details for mapped types"
+        },
+        decorators: {
+          type: "array",
+          description: "Decorators applied to this export (class/function)",
+          items: { $ref: "#/$defs/decorator" }
+        },
+        isAugmentation: {
+          type: "boolean",
+          description: "True if this is a module augmentation (declare module)"
+        },
+        augmentedModule: {
+          type: "string",
+          description: "The module being augmented (e.g., 'express')"
+        },
+        related: {
+          type: "array",
+          description: "Related exports/types (auto-detected + @see tags)",
+          items: {
+            $ref: "#/$defs/relation"
+          }
         }
       }
     },
@@ -1359,6 +1391,25 @@ var openpkg_schema_default3 = {
         },
         source: {
           $ref: "#/$defs/sourceLocation"
+        },
+        typeAliasKind: {
+          $ref: "#/$defs/typeAliasKind",
+          description: "Kind of type alias"
+        },
+        conditionalType: {
+          $ref: "#/$defs/conditionalType",
+          description: "Structural details for conditional types"
+        },
+        mappedType: {
+          $ref: "#/$defs/mappedType",
+          description: "Structural details for mapped types"
+        },
+        related: {
+          type: "array",
+          description: "Related exports/types (auto-detected + @see tags)",
+          items: {
+            $ref: "#/$defs/relation"
+          }
         }
       }
     },
@@ -1433,6 +1484,11 @@ var openpkg_schema_default3 = {
         isImplementation: {
           type: "boolean",
           description: "True if this is the implementation signature (not user-callable)"
+        },
+        throws: {
+          type: "array",
+          description: "Exceptions that can be thrown by this signature",
+          items: { $ref: "#/$defs/throwsInfo" }
         }
       }
     },
@@ -1479,6 +1535,11 @@ var openpkg_schema_default3 = {
         rest: {
           type: "boolean",
           description: "Whether this is a rest parameter (...args)"
+        },
+        decorators: {
+          type: "array",
+          description: "Decorators applied to this parameter",
+          items: { $ref: "#/$defs/decorator" }
         }
       }
     },
@@ -1495,28 +1556,39 @@ var openpkg_schema_default3 = {
       }
     },
     schema: {
-      anyOf: [
-        {
-          type: "boolean"
-        },
+      description: "Flexible JSON Schema for type representation",
+      oneOf: [
+        { type: "string" },
+        { type: "boolean" },
         {
           type: "object",
           properties: {
-            $ref: {
-              type: "string",
-              description: "Reference to another type",
-              pattern: "^#/types/[A-Za-z0-9_.-]+$"
-            }
-          },
-          required: ["$ref"],
-          additionalProperties: false
-        },
-        {
-          type: "object",
-          not: {
-            required: ["$ref"]
-          },
-          additionalProperties: true
+            type: { type: "string" },
+            format: { type: "string" },
+            enum: { type: "array" },
+            items: { $ref: "#/$defs/schema" },
+            properties: {
+              type: "object",
+              additionalProperties: { $ref: "#/$defs/schema" }
+            },
+            required: { type: "array", items: { type: "string" } },
+            additionalProperties: {
+              oneOf: [{ type: "boolean" }, { $ref: "#/$defs/schema" }]
+            },
+            anyOf: { type: "array", items: { $ref: "#/$defs/schema" } },
+            allOf: { type: "array", items: { $ref: "#/$defs/schema" } },
+            oneOf: { type: "array", items: { $ref: "#/$defs/schema" } },
+            $ref: { type: "string" },
+            discriminator: {
+              type: "object",
+              properties: { propertyName: { type: "string" } }
+            },
+            tsType: { type: "string" },
+            description: { type: "string" },
+            minItems: { type: "integer" },
+            maxItems: { type: "integer" },
+            signatures: { type: "array" }
+          }
         }
       ]
     },
@@ -1534,6 +1606,169 @@ var openpkg_schema_default3 = {
           minimum: 1
         }
       }
+    },
+    typeAliasKind: {
+      type: "string",
+      description: "Kind of type alias",
+      enum: ["alias", "conditional", "mapped", "template-literal", "infer"]
+    },
+    conditionalType: {
+      type: "object",
+      description: "Structural representation of a conditional type (T extends X ? Y : Z)",
+      required: ["checkType", "extendsType", "trueType", "falseType"],
+      properties: {
+        checkType: {
+          type: "string",
+          description: "The type being checked (T)"
+        },
+        extendsType: {
+          type: "string",
+          description: "The constraint type (X)"
+        },
+        trueType: {
+          type: "string",
+          description: "The type when condition is true (Y)"
+        },
+        falseType: {
+          type: "string",
+          description: "The type when condition is false (Z)"
+        }
+      },
+      additionalProperties: false
+    },
+    mappedType: {
+      type: "object",
+      description: "Structural representation of a mapped type ({ [K in keyof T]: ... })",
+      required: ["typeParameter"],
+      properties: {
+        typeParameter: {
+          type: "string",
+          description: "The type parameter clause (e.g., 'K in keyof T')"
+        },
+        nameType: {
+          type: "string",
+          description: "The 'as' clause for key remapping (TS 4.1+)"
+        },
+        valueType: {
+          type: "string",
+          description: "The mapped value type"
+        },
+        readonly: {
+          description: "Readonly modifier (+, -, or true for present)",
+          oneOf: [{ type: "boolean" }, { enum: ["+", "-"] }]
+        },
+        optional: {
+          description: "Optional modifier (+, -, or true for present)",
+          oneOf: [{ type: "boolean" }, { enum: ["+", "-"] }]
+        }
+      },
+      additionalProperties: false
+    },
+    decorator: {
+      type: "object",
+      description: "Decorator applied to a class, member, or parameter",
+      required: ["name"],
+      properties: {
+        name: {
+          type: "string",
+          description: "Decorator name (e.g., 'Injectable', 'Component')"
+        },
+        arguments: {
+          type: "array",
+          description: "Evaluated decorator arguments (if possible)"
+        },
+        argumentsText: {
+          type: "array",
+          description: "Raw text of decorator arguments",
+          items: { type: "string" }
+        }
+      },
+      additionalProperties: false
+    },
+    throwsInfo: {
+      type: "object",
+      description: "Information about an exception that can be thrown",
+      properties: {
+        type: {
+          type: "string",
+          description: "Exception type (e.g., 'ValidationError', 'Error')"
+        },
+        description: {
+          type: "string",
+          description: "When/why the exception is thrown"
+        }
+      },
+      additionalProperties: false
+    },
+    exampleLanguage: {
+      type: "string",
+      description: "Programming language for an example",
+      enum: ["ts", "js", "tsx", "jsx", "shell", "json"]
+    },
+    example: {
+      description: "Usage example - can be a simple string or structured object",
+      oneOf: [
+        { type: "string" },
+        {
+          type: "object",
+          required: ["code"],
+          properties: {
+            code: {
+              type: "string",
+              description: "The example code"
+            },
+            title: {
+              type: "string",
+              description: "Short title for the example"
+            },
+            description: {
+              type: "string",
+              description: "Longer description of what the example demonstrates"
+            },
+            language: {
+              $ref: "#/$defs/exampleLanguage"
+            },
+            runnable: {
+              type: "boolean",
+              description: "Whether this example can be run/tested automatically"
+            },
+            expectedOutput: {
+              type: "string",
+              description: "Expected output when the example is run"
+            },
+            tags: {
+              type: "array",
+              description: "Categorization tags (e.g., 'basic', 'advanced', 'error-handling')",
+              items: { type: "string" }
+            }
+          },
+          additionalProperties: false
+        }
+      ]
+    },
+    relationType: {
+      type: "string",
+      description: "Type of relationship between exports",
+      enum: ["uses", "returns", "implements", "extends", "see-also", "companion"]
+    },
+    relation: {
+      type: "object",
+      description: "Relationship to another export or type",
+      required: ["type", "target"],
+      properties: {
+        type: {
+          $ref: "#/$defs/relationType"
+        },
+        target: {
+          type: "string",
+          description: "Target export/type ID or reference"
+        },
+        description: {
+          type: "string",
+          description: "Optional description of the relationship"
+        }
+      },
+      additionalProperties: false
     }
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/spec",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Shared schema, validation, and diff utilities for OpenPkg specs",
   "keywords": [
     "openpkg",

package/schemas/v0.3.0/openpkg.schema.json

@@ -192,7 +192,7 @@
           "type": "array",
           "description": "Usage examples from documentation",
           "items": {
-            "type": "string"
+            "$ref": "#/$defs/example"
           }
         },
         "signatures": {
@@ -233,6 +233,38 @@
         "docs": {
           "$ref": "#/$defs/docsMetadata",
           "description": "Documentation coverage metadata for this export"
+        },
+        "typeAliasKind": {
+          "$ref": "#/$defs/typeAliasKind",
+          "description": "Kind of type alias (for type exports)"
+        },
+        "conditionalType": {
+          "$ref": "#/$defs/conditionalType",
+          "description": "Structural details for conditional types"
+        },
+        "mappedType": {
+          "$ref": "#/$defs/mappedType",
+          "description": "Structural details for mapped types"
+        },
+        "decorators": {
+          "type": "array",
+          "description": "Decorators applied to this export (class/function)",
+          "items": { "$ref": "#/$defs/decorator" }
+        },
+        "isAugmentation": {
+          "type": "boolean",
+          "description": "True if this is a module augmentation (declare module)"
+        },
+        "augmentedModule": {
+          "type": "string",
+          "description": "The module being augmented (e.g., 'express')"
+        },
+        "related": {
+          "type": "array",
+          "description": "Related exports/types (auto-detected + @see tags)",
+          "items": {
+            "$ref": "#/$defs/relation"
+          }
         }
       }
     },
@@ -307,6 +339,25 @@
         },
         "source": {
           "$ref": "#/$defs/sourceLocation"
+        },
+        "typeAliasKind": {
+          "$ref": "#/$defs/typeAliasKind",
+          "description": "Kind of type alias"
+        },
+        "conditionalType": {
+          "$ref": "#/$defs/conditionalType",
+          "description": "Structural details for conditional types"
+        },
+        "mappedType": {
+          "$ref": "#/$defs/mappedType",
+          "description": "Structural details for mapped types"
+        },
+        "related": {
+          "type": "array",
+          "description": "Related exports/types (auto-detected + @see tags)",
+          "items": {
+            "$ref": "#/$defs/relation"
+          }
         }
       }
     },
@@ -381,6 +432,11 @@
         "isImplementation": {
           "type": "boolean",
           "description": "True if this is the implementation signature (not user-callable)"
+        },
+        "throws": {
+          "type": "array",
+          "description": "Exceptions that can be thrown by this signature",
+          "items": { "$ref": "#/$defs/throwsInfo" }
         }
       }
     },
@@ -427,6 +483,11 @@
         "rest": {
           "type": "boolean",
           "description": "Whether this is a rest parameter (...args)"
+        },
+        "decorators": {
+          "type": "array",
+          "description": "Decorators applied to this parameter",
+          "items": { "$ref": "#/$defs/decorator" }
         }
       }
     },
@@ -443,28 +504,39 @@
       }
     },
     "schema": {
-      "anyOf": [
-        {
-          "type": "boolean"
-        },
+      "description": "Flexible JSON Schema for type representation",
+      "oneOf": [
+        { "type": "string" },
+        { "type": "boolean" },
         {
           "type": "object",
           "properties": {
-            "$ref": {
-              "type": "string",
-              "description": "Reference to another type",
-              "pattern": "^#/types/[A-Za-z0-9_.-]+$"
-            }
-          },
-          "required": ["$ref"],
-          "additionalProperties": false
-        },
-        {
-          "type": "object",
-          "not": {
-            "required": ["$ref"]
-          },
-          "additionalProperties": true
+            "type": { "type": "string" },
+            "format": { "type": "string" },
+            "enum": { "type": "array" },
+            "items": { "$ref": "#/$defs/schema" },
+            "properties": {
+              "type": "object",
+              "additionalProperties": { "$ref": "#/$defs/schema" }
+            },
+            "required": { "type": "array", "items": { "type": "string" } },
+            "additionalProperties": {
+              "oneOf": [{ "type": "boolean" }, { "$ref": "#/$defs/schema" }]
+            },
+            "anyOf": { "type": "array", "items": { "$ref": "#/$defs/schema" } },
+            "allOf": { "type": "array", "items": { "$ref": "#/$defs/schema" } },
+            "oneOf": { "type": "array", "items": { "$ref": "#/$defs/schema" } },
+            "$ref": { "type": "string" },
+            "discriminator": {
+              "type": "object",
+              "properties": { "propertyName": { "type": "string" } }
+            },
+            "tsType": { "type": "string" },
+            "description": { "type": "string" },
+            "minItems": { "type": "integer" },
+            "maxItems": { "type": "integer" },
+            "signatures": { "type": "array" }
+          }
         }
       ]
     },
@@ -482,6 +554,169 @@
           "minimum": 1
         }
       }
+    },
+    "typeAliasKind": {
+      "type": "string",
+      "description": "Kind of type alias",
+      "enum": ["alias", "conditional", "mapped", "template-literal", "infer"]
+    },
+    "conditionalType": {
+      "type": "object",
+      "description": "Structural representation of a conditional type (T extends X ? Y : Z)",
+      "required": ["checkType", "extendsType", "trueType", "falseType"],
+      "properties": {
+        "checkType": {
+          "type": "string",
+          "description": "The type being checked (T)"
+        },
+        "extendsType": {
+          "type": "string",
+          "description": "The constraint type (X)"
+        },
+        "trueType": {
+          "type": "string",
+          "description": "The type when condition is true (Y)"
+        },
+        "falseType": {
+          "type": "string",
+          "description": "The type when condition is false (Z)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "mappedType": {
+      "type": "object",
+      "description": "Structural representation of a mapped type ({ [K in keyof T]: ... })",
+      "required": ["typeParameter"],
+      "properties": {
+        "typeParameter": {
+          "type": "string",
+          "description": "The type parameter clause (e.g., 'K in keyof T')"
+        },
+        "nameType": {
+          "type": "string",
+          "description": "The 'as' clause for key remapping (TS 4.1+)"
+        },
+        "valueType": {
+          "type": "string",
+          "description": "The mapped value type"
+        },
+        "readonly": {
+          "description": "Readonly modifier (+, -, or true for present)",
+          "oneOf": [{ "type": "boolean" }, { "enum": ["+", "-"] }]
+        },
+        "optional": {
+          "description": "Optional modifier (+, -, or true for present)",
+          "oneOf": [{ "type": "boolean" }, { "enum": ["+", "-"] }]
+        }
+      },
+      "additionalProperties": false
+    },
+    "decorator": {
+      "type": "object",
+      "description": "Decorator applied to a class, member, or parameter",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Decorator name (e.g., 'Injectable', 'Component')"
+        },
+        "arguments": {
+          "type": "array",
+          "description": "Evaluated decorator arguments (if possible)"
+        },
+        "argumentsText": {
+          "type": "array",
+          "description": "Raw text of decorator arguments",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "throwsInfo": {
+      "type": "object",
+      "description": "Information about an exception that can be thrown",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Exception type (e.g., 'ValidationError', 'Error')"
+        },
+        "description": {
+          "type": "string",
+          "description": "When/why the exception is thrown"
+        }
+      },
+      "additionalProperties": false
+    },
+    "exampleLanguage": {
+      "type": "string",
+      "description": "Programming language for an example",
+      "enum": ["ts", "js", "tsx", "jsx", "shell", "json"]
+    },
+    "example": {
+      "description": "Usage example - can be a simple string or structured object",
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "required": ["code"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "description": "The example code"
+            },
+            "title": {
+              "type": "string",
+              "description": "Short title for the example"
+            },
+            "description": {
+              "type": "string",
+              "description": "Longer description of what the example demonstrates"
+            },
+            "language": {
+              "$ref": "#/$defs/exampleLanguage"
+            },
+            "runnable": {
+              "type": "boolean",
+              "description": "Whether this example can be run/tested automatically"
+            },
+            "expectedOutput": {
+              "type": "string",
+              "description": "Expected output when the example is run"
+            },
+            "tags": {
+              "type": "array",
+              "description": "Categorization tags (e.g., 'basic', 'advanced', 'error-handling')",
+              "items": { "type": "string" }
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "relationType": {
+      "type": "string",
+      "description": "Type of relationship between exports",
+      "enum": ["uses", "returns", "implements", "extends", "see-also", "companion"]
+    },
+    "relation": {
+      "type": "object",
+      "description": "Relationship to another export or type",
+      "required": ["type", "target"],
+      "properties": {
+        "type": {
+          "$ref": "#/$defs/relationType"
+        },
+        "target": {
+          "type": "string",
+          "description": "Target export/type ID or reference"
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional description of the relationship"
+        }
+      },
+      "additionalProperties": false
     }
   }
 }