Package beta.5 without _schemas causes schema validation to skip

[bokelley]

Summary

adcp==6.3.0b5 installs without the adcp/_schemas/ package-data directory, so schema-driven validation skips instead of validating against the bundled AdCP schemas.

This matters for the supported_macros fix from adcontextprotocol/adcp#5099: the beta.5 source tree has the fixed schemas/cache/3.1.0-beta.7/core/format.json (supported_macros.items.anyOf), but the distributed Python package does not include _schemas, so the runtime validator cannot exercise that fixed schema.

Repro

Fresh package install:

uv venv /tmp/adcp-beta5-pypi-venv
uv pip install --python /tmp/adcp-beta5-pypi-venv/bin/python 'adcp==6.3.0b5'
/tmp/adcp-beta5-pypi-venv/bin/python - <<'PY'
from pathlib import Path
import adcp
from adcp._version import _read_packaged_version
from adcp.validation.schema_validator import validate_response

root = Path(adcp.__file__).resolve().parent
print('adcp', adcp.__version__)
print('ADCP_VERSION', _read_packaged_version())
print('_schemas exists', (root / '_schemas').is_dir())

payload = {
    'formats': [{
        'format_id': {'agent_url': 'https://creative.adcontextprotocol.org', 'id': 'display_macro_test'},
        'name': 'Display Macro Test',
        'assets': [{'item_type': 'individual', 'asset_id': 'primary', 'asset_type': 'image', 'required': True}],
        'supported_macros': ['MEDIA_BUY_ID', 'CREATIVE_ID', 'CACHEBUSTER', 'CLICK_URL'],
    }],
}
for version in (None, '3.1-beta.7', '3.0'):
    outcome = validate_response('list_creative_formats', payload, version=version)
    print(version, outcome.valid, outcome.variant, len(outcome.issues))
PY

Observed output:

adcp 6.3.0b5
ADCP_VERSION 3.1.0-beta.7
_schemas exists False
None True skipped 0
3.1-beta.7 True skipped 0
3.0 True skipped 0

Source-tree comparison

Using the beta.5 source tree directly (PYTHONPATH=src from a clone of tag v6.3.0-beta.5), the dev-checkout fallback does find schemas/cache/ and validates as expected:

ADCP_VERSION 3.1.0-beta.7 bundle 3.1.0-beta.7
supported ('3.0', '3.1-beta.7')
version= None valid= True variant= sync issues= 0
version= 3.1-beta.7 valid= True variant= sync issues= 0
version= 3.0 valid= False variant= sync issues= 4
/formats/0/supported_macros/0 oneOf composition failed; ...

That confirms:

• the 3.1 beta.7 schema cache in the source tree contains the supported_macros anyOf fix;
• the older 3.0 cache still has the oneOf behavior;
• the installed package is not validating either path because _schemas is absent.

Expected behavior

The wheel/sdist for adcp==6.3.0b5 should include adcp/_schemas/<bundle-key>/... so adcp.validation.schema_loader can load bundled schemas in installed environments.

Likely fix

Run scripts/bundle_schemas.py as part of the release build, or otherwise ensure src/adcp/_schemas/**/*.json exists before building the package. pyproject.toml and MANIFEST.in already appear to include _schemas/**/*.json as package data, but the directory is absent in the installed artifact.

[bokelley]

Triage

Classification: Bug
Bucket(s): validation (no validation label in repo — gap noted)
Status: ready-to-implement

What the experts said:

• code-reviewer: Option A (setup.py hook) fails at PEP 517 build isolation — scripts/ relative paths don't survive the isolated build tree. Option C (commit 3469 schema files) violates the .gitignore design intent. Option B (workflow step) is the only sound fix. Also: schema_loader.py miss path emits logger.debug, should be logger.warning.
• dx-expert: Silent valid=True, variant='skipped' is trust-breaking when adopters have strict validation configured; no stdlib-visible signal in production logs. Both the workflow step and the log-level upgrade are needed.

My take: Root cause is .github/workflows/release-please.yml line 87: python -m build runs without first calling scripts/bundle_schemas.py, which mirrors the committed schemas/cache/ tree into src/adcp/_schemas/. The Makefile build target does this correctly; the workflow bypasses it.

Implementation scope:

• .github/workflows/release-please.yml — Insert a step between "Install build dependencies" and "Build package" (same if: condition as both adjacent steps):

  - name: Bundle schemas
    if: ${{ steps.release.outputs.release_created == 'true' || (github.event_name == 'workflow_dispatch' && inputs.publish == true) }}
    run: python scripts/bundle_schemas.py

  schemas/cache/ is present in the checkout (3469 committed JSON files); no sync_schemas.py needed. Apply to sdist too (same path — MANIFEST.in already lists src/adcp/_schemas).

• src/adcp/validation/schema_loader.py — Upgrade logger.debug → logger.warning on the SDK-pin schema-miss path (~line 191) so broken installs surface in production logs rather than silently degrading.

• Required checks: pytest tests/ on validation subset, mypy src/, ruff check .

• Non-breaking rationale: Additive — installed wheel gains schemas it was always supposed to ship; behavior changes from undocumented silent skip to documented validation. No public API changes.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01Xsjgyq7eiRRSEY63w3D4YG

---

Generated by Claude Code