Skip to content

Schema artifacts for LLM/tooling contracts (encodings, react settings, url params) via optional dev-only models #1326

Closed

Description

@lmeyerov

Summary: Add first-class JSON Schema artifacts for three public contract surfaces used by LLM/tooling integrations: (1) simple+complex encodings, (2) react settings including apply_encodings keys, (3) url params. Goal is better OSS-discoverable signatures and less downstream drift while keeping runtime behavior unchanged.\n\nConstraints: Do NOT add pydantic as a hard runtime dependency. Keep existing runtime TypedDict + validator flows canonical for execution behavior.\n\nProposal: (1) Add optional dev-only schema models (pydantic v2 behind an extra/dev group). (2) Add schema export script to write committed artifacts: schemas/encodings.schema.json, schemas/react-settings.schema.json, schemas/url-params.schema.json. (3) Add CI drift guard that regenerates and fails on diff. (4) Keep semantic validation in existing validators (JSON Schema is structural; validators keep deeper semantic checks).\n\nSuggested file layout: graphistry/devschemas/encodings.py, graphistry/devschemas/react_settings.py, graphistry/devschemas/url_params.py, graphistry/devschemas/export.py, schemas/*.schema.json committed artifacts.\n\nSource-of-truth mapping today: encodings shape in graphistry/io/types.py; encodings semantics in graphistry/validate/validate_encodings.py; react settings in graphistry/models/surfaces/graphistry_frontend/react_settings.py; url params in graphistry/models/surfaces/graphistry_frontend/url_params.py.\n\nNon-goals: replacing runtime validators with JSON Schema; breaking existing payload compatibility; coupling io metadata wire types directly to GFQL call param types.\n\nAcceptance criteria: optional install path for schema tooling only; committed schemas for the three surfaces above; CI drift check in place; no runtime behavior change for existing APIs/payloads; docs note that schema files are structural contracts while semantic constraints remain in validators.

Activity

  1. lmeyerov commented on May 20, 2026

    @lmeyerov
    ContributorAuthor

    Closeout receipt for #1326:

    • Implemented in PR feat(schemas): export tooling contract artifacts #1590: feat(schemas): export tooling contract artifacts #1590
    • Squash-merged at 7900ae3fa1ab7287daff03b7a718f5bc0088dc70.
    • Added committed structural JSON Schema artifacts for encodings, React settings, and URL params under schemas/.
    • Added stdlib exporter/checker at graphistry.devschemas.export plus CI schema-artifacts drift guard.
    • Added docs/changelog and included schemas/*.schema.json in MANIFEST.in for sdists.
    • Compiler-plan surface touched: no.
    • DGX/cuDF: skipped; no runtime, DataFrame, cuDF, or GPU path touched.

    Validation receipts:

    • Focused tests: python3 -m pytest -q graphistry/tests/test_schema_artifacts.py graphistry/tests/test_viz_settings.py graphistry/tests/test_validate_settings.py -> 28 passed.
    • Local changed-line coverage reproduction -> 57/57 changed executable lines covered.
    • python3 -m graphistry.devschemas.export --check -> passed.
    • ./bin/ruff.sh graphistry/devschemas graphistry/tests/test_schema_artifacts.py -> passed.
    • ./bin/typecheck.sh graphistry/devschemas graphistry/tests/test_schema_artifacts.py -> passed.
    • git diff --check -> passed.
    • Review skill converged: waves 2/3 clean; wave 4 after the CI coverage fix clean.
    • Full PR CI green; ReadTheDocs green.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions