{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://stella-ops.org/schemas/sdk-generator-samples.schema.json", "title": "StellaOps SDK Generator Samples Schema", "description": "Schema for SDK generator output samples, snippet packs, and language bindings. Unblocks DEVPORT-63-002, DOCS-SDK-62-001 (2+ tasks).", "type": "object", "definitions": { "SdkLanguage": { "type": "string", "enum": ["typescript", "python", "go", "java", "csharp", "ruby", "php", "rust"], "description": "Supported SDK target languages" }, "SdkSample": { "type": "object", "description": "Individual SDK code sample", "required": ["sample_id", "language", "operation", "code"], "properties": { "sample_id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "Unique sample identifier" }, "language": { "$ref": "#/definitions/SdkLanguage" }, "operation": { "type": "string", "description": "API operation this sample demonstrates" }, "title": { "type": "string", "description": "Human-readable title" }, "description": { "type": "string", "description": "Explanation of what the sample demonstrates" }, "code": { "type": "string", "description": "The actual code sample" }, "imports": { "type": "array", "items": { "type": "string" }, "description": "Required imports/dependencies" }, "prerequisites": { "type": "array", "items": { "type": "string" }, "description": "Setup steps before running" }, "expected_output": { "type": "string", "description": "Expected console output or result" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Categorization tags (auth, scanning, vex, etc.)" }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$", "description": "SHA-256 hash of code content for verification" } } }, "SnippetPack": { "type": "object", "description": "Collection of SDK samples for a specific language", "required": ["pack_id", "language", "version", "samples"], "properties": { "pack_id": { "type": "string", "description": "Unique pack identifier" }, "language": { "$ref": "#/definitions/SdkLanguage" }, "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$", "description": "Pack version (semver)" }, "sdk_version": { "type": "string", "description": "Target SDK version these samples work with" }, "api_version": { "type": "string", "description": "API version (e.g., v1, v2)" }, "generated_at": { "type": "string", "format": "date-time" }, "samples": { "type": "array", "items": { "$ref": "#/definitions/SdkSample" } }, "aggregate_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$", "description": "Hash of all sample digests combined" }, "package_info": { "$ref": "#/definitions/PackageInfo" } } }, "PackageInfo": { "type": "object", "description": "Language-specific package information", "properties": { "package_name": { "type": "string", "description": "Package name (e.g., @stellaops/sdk, stellaops-sdk)" }, "registry_url": { "type": "string", "format": "uri", "description": "Package registry URL" }, "install_command": { "type": "string", "description": "Command to install the SDK" }, "min_runtime_version": { "type": "string", "description": "Minimum runtime version required" }, "dependencies": { "type": "array", "items": { "$ref": "#/definitions/Dependency" } } } }, "Dependency": { "type": "object", "description": "SDK dependency", "required": ["name", "version"], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "optional": { "type": "boolean", "default": false } } }, "SdkGeneratorConfig": { "type": "object", "description": "SDK generator configuration", "required": ["generator_id", "openapi_source"], "properties": { "generator_id": { "type": "string" }, "openapi_source": { "type": "string", "format": "uri", "description": "OpenAPI spec URL or path" }, "target_languages": { "type": "array", "items": { "$ref": "#/definitions/SdkLanguage" } }, "output_dir": { "type": "string" }, "templates": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom templates per language" }, "options": { "$ref": "#/definitions/GeneratorOptions" } } }, "GeneratorOptions": { "type": "object", "description": "SDK generation options", "properties": { "include_samples": { "type": "boolean", "default": true, "description": "Generate usage samples" }, "include_tests": { "type": "boolean", "default": true, "description": "Generate test stubs" }, "include_docs": { "type": "boolean", "default": true, "description": "Generate API documentation" }, "async_style": { "type": "string", "enum": ["async_await", "promises", "callbacks", "sync"], "default": "async_await" }, "error_handling": { "type": "string", "enum": ["exceptions", "result_types", "error_codes"], "default": "exceptions" }, "naming_convention": { "type": "string", "enum": ["camelCase", "snake_case", "PascalCase"], "description": "Override default for language" } } }, "SdkGeneratorOutput": { "type": "object", "description": "Output from SDK generation", "required": ["output_id", "generator_id", "generated_at", "files"], "properties": { "output_id": { "type": "string", "format": "uuid" }, "generator_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "language": { "$ref": "#/definitions/SdkLanguage" }, "sdk_version": { "type": "string" }, "api_version": { "type": "string" }, "files": { "type": "array", "items": { "$ref": "#/definitions/GeneratedFile" } }, "stats": { "$ref": "#/definitions/GenerationStats" }, "manifest_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" } } }, "GeneratedFile": { "type": "object", "description": "Generated SDK file", "required": ["path", "digest"], "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": ["source", "test", "sample", "docs", "config"] }, "size_bytes": { "type": "integer" }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" } } }, "GenerationStats": { "type": "object", "description": "SDK generation statistics", "properties": { "total_files": { "type": "integer" }, "source_files": { "type": "integer" }, "test_files": { "type": "integer" }, "sample_files": { "type": "integer" }, "total_lines": { "type": "integer" }, "endpoints_covered": { "type": "integer" }, "models_generated": { "type": "integer" } } }, "SampleCategory": { "type": "object", "description": "Category grouping for samples", "required": ["category_id", "name"], "properties": { "category_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "samples": { "type": "array", "items": { "type": "string" }, "description": "Sample IDs in this category" }, "order": { "type": "integer", "description": "Display order" } } }, "SdkDocumentation": { "type": "object", "description": "SDK documentation structure", "properties": { "overview": { "type": "string", "description": "SDK overview markdown" }, "quickstart": { "type": "string", "description": "Quickstart guide markdown" }, "authentication": { "type": "string", "description": "Authentication guide" }, "error_handling": { "type": "string", "description": "Error handling guide" }, "changelog": { "type": "string", "description": "SDK changelog" }, "api_reference_url": { "type": "string", "format": "uri" } } } }, "properties": { "snippet_packs": { "type": "array", "items": { "$ref": "#/definitions/SnippetPack" } }, "categories": { "type": "array", "items": { "$ref": "#/definitions/SampleCategory" } }, "generator_outputs": { "type": "array", "items": { "$ref": "#/definitions/SdkGeneratorOutput" } } }, "examples": [ { "snippet_packs": [ { "pack_id": "stellaops-typescript-samples", "language": "typescript", "version": "1.0.0", "sdk_version": "2025.10.0", "api_version": "v1", "generated_at": "2025-12-06T10:00:00Z", "samples": [ { "sample_id": "auth-token-exchange", "language": "typescript", "operation": "POST /oauth/token", "title": "Token Exchange", "description": "Exchange client credentials for an access token", "code": "import { StellaOpsClient } from '@stellaops/sdk';\n\nconst client = new StellaOpsClient({\n clientId: process.env.STELLAOPS_CLIENT_ID,\n clientSecret: process.env.STELLAOPS_CLIENT_SECRET,\n});\n\nconst token = await client.auth.getToken();\nconsole.log('Token expires at:', token.expiresAt);", "imports": ["@stellaops/sdk"], "prerequisites": [ "Set STELLAOPS_CLIENT_ID environment variable", "Set STELLAOPS_CLIENT_SECRET environment variable" ], "expected_output": "Token expires at: 2025-12-06T11:00:00Z", "tags": ["authentication", "oauth"], "digest": "sha256:abc123def456789012345678901234567890123456789012345678901234abcd" }, { "sample_id": "scan-container-image", "language": "typescript", "operation": "POST /api/v1/scanner/scan", "title": "Scan Container Image", "description": "Scan a container image for vulnerabilities", "code": "import { StellaOpsClient } from '@stellaops/sdk';\n\nconst client = new StellaOpsClient();\nconst result = await client.scanner.scanImage({\n image: 'nginx:1.25',\n generateSbom: true,\n format: 'cyclonedx',\n});\n\nconsole.log(`Found ${result.vulnerabilities.length} vulnerabilities`);", "imports": ["@stellaops/sdk"], "tags": ["scanning", "sbom", "vulnerabilities"], "digest": "sha256:def456abc789012345678901234567890123456789012345678901234defabc" } ], "aggregate_digest": "sha256:agg123def456789012345678901234567890123456789012345678901234agg", "package_info": { "package_name": "@stellaops/sdk", "registry_url": "https://registry.npmjs.org", "install_command": "npm install @stellaops/sdk", "min_runtime_version": "18.0.0", "dependencies": [ { "name": "axios", "version": "^1.6.0" }, { "name": "jose", "version": "^5.0.0" } ] } }, { "pack_id": "stellaops-python-samples", "language": "python", "version": "1.0.0", "sdk_version": "2025.10.0", "api_version": "v1", "generated_at": "2025-12-06T10:00:00Z", "samples": [ { "sample_id": "auth-token-exchange-py", "language": "python", "operation": "POST /oauth/token", "title": "Token Exchange", "description": "Exchange client credentials for an access token", "code": "from stellaops import StellaOpsClient\nimport os\n\nclient = StellaOpsClient(\n client_id=os.environ['STELLAOPS_CLIENT_ID'],\n client_secret=os.environ['STELLAOPS_CLIENT_SECRET'],\n)\n\ntoken = client.auth.get_token()\nprint(f'Token expires at: {token.expires_at}')", "imports": ["stellaops"], "tags": ["authentication", "oauth"], "digest": "sha256:py123def456789012345678901234567890123456789012345678901234pyth" } ], "package_info": { "package_name": "stellaops-sdk", "registry_url": "https://pypi.org/project/stellaops-sdk/", "install_command": "pip install stellaops-sdk", "min_runtime_version": "3.10" } } ], "categories": [ { "category_id": "authentication", "name": "Authentication", "description": "Token exchange and authentication samples", "samples": ["auth-token-exchange", "auth-token-exchange-py"], "order": 1 }, { "category_id": "scanning", "name": "Container Scanning", "description": "Container image scanning and SBOM generation", "samples": ["scan-container-image"], "order": 2 } ] } ] }