Validation & Conformance

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/validate.sh
• CLAUDE.md
• stackone_ai/types.py
• tests/test_models.py
• tests/test_fetch_tools.py
• tests/test_tool_calling.py
• pyproject.toml

Validation and conformance ensure the StackOne AI SDK maintains a stable wire contract with the StackOne API and correctly serves tool schemas to AI models. The system verifies that no schema information is lost during conversion between the Model Context Protocol (MCP) server and various AI framework adapters.

The project uses a dedicated validation script and a conformance suite to prevent regressions in tool discovery, argument parsing, and security headers. This ensures that the SDK strictly follows the served catalog without inventing or losing metadata.

Sources: CLAUDE.md:12-14, scripts/validate.sh:1-20

Validation Architecture

The validation system consists of static checks, unit tests, and integration tests against mock servers. It targets five primary areas: examples, wire conformance, core SDK logic, Pydantic AI integration, and Google ADK plugin compatibility.

The diagram shows the hierarchy of validation targets triggered by the validate.sh script, interacting with mock environments.

Sources: scripts/validate.sh:42-130, CLAUDE.md:36-43

Wire Conformance & Schema Integrity

The SDK must pass tool schemas to models verbatim. The Conformance Suite uses a --strict-schema gate to fail if any schema keyword is dropped between the server response and the model interface. This prevents silent loss of nested fields, enums, or constraints.

Schema Validation Rules

• Internal Markers: The SDK uses an internal nullable marker to track required fields. This is stripped during conversion to standard JSON Schema for models.
• Verbatim Pass-through: Keywords like minimum, maximum, pattern, and custom vendor hints must reach the model intact.
• Composition: Logic for oneOf, anyOf, and nested required arrays must be preserved.

Sources: tests/test_models.py:440-492, CLAUDE.md:121-128

Key Validation Functions

Function	Purpose	Location
validate_method	Ensures HTTP methods are supported (GET, POST, PUT, DELETE, PATCH).	stackone_ai/types.py:100
is_json_content_type	Determines if a response body should be parsed as JSON or treated as a binary file.	stackone_ai/types.py:111
_safe_basename	Sanitizes server-supplied filenames to prevent arbitrary-file-write attacks.	stackone_ai/types.py:126
filename_from_content_disposition	Extracts and decodes filenames from headers following RFC 5987.	stackone_ai/types.py:145

Sources: stackone_ai/types.py:100-170

Security Header Validation

The SDK enforces strict header sanitization to prevent lateral movement and credential smuggling. Model-supplied headers are filtered against an allowlist derived from the served schema.

The sequence diagram illustrates how the SDK intercepts and cleanses headers before they reach the API.

Sources: tests/test_tool_calling.py:276-320, CLAUDE.md:113-118

Header Restrictions

1. Authorization: Any model-supplied Authorization header is stripped to prevent token theft.
2. Account Scoping: The x-account-id header is managed by the SDK. Attempts by a model to override this are ignored to prevent cross-account access.
3. Allowlist Only: Only headers explicitly declared in the tool's headers_* properties are passed to the API.

Sources: tests/test_tool_calling.py:295-310, tests/test_tool_calling.py:535-565

Execution & Argument Validation

The SDK validates argument shapes based on the calling surface used. Mixing argument shapes results in silent drops or execution failures.

Argument Shape Requirements

Calling Surface	Argument Shape	Requirement
toolset.execute()	Nested	Envelope must match: {"body": {"variables": {...}}}
tool.execute()	Flat-Prefixed	Keys must include location: body_variables, path_id

Sources: CLAUDE.md:27-32, tests/test_tool_calling.py:455-485

JSON Validation Logic

• Arguments passed as strings must be valid JSON objects.
• Non-dictionary JSON (arrays, primitives) is rejected with a ValueError.
• The SDK validates that parameters targeted for PATH, QUERY, or BODY are correctly routed based on the ExecuteConfig.

Sources: tests/test_models.py:284-335, stackone_ai/types.py:173-182

Conformance Testing Procedures

Developers must run the validation suite before pushing changes. The suite ensures that the SDK behaves identically to the real API by using a strict mock server.

1. Static Analysis: Ruff and Ty verify code style and type safety.
2. Example Probe: The system imports all files in examples/ to ensure imports resolve and type-checks them against the current SDK version.
3. Mock Server Tests: Integration tests in tests/test_fetch_tools.py run against an MCP mock server (tests/mocks/mcp-server.ts) to verify account discovery and catalog caching.
4. Error Hierarchy: All errors must derive from StackOneError. The suite verifies that StackOneAPIError and ToolsetError are correctly caught by base exception handlers.

Sources: scripts/validate.sh:42-69, tests/test_fetch_tools.py:650-660, CLAUDE.md:106-111