feat(validate): add --path option to target sub-schema via JSON Pointer

[Vaibhav701161]

Description

This PR adds support for a --path option to the validate command. It allows validating a specific sub-schema inside a larger JSON document using a JSON Pointer.

Reference #218

---

Motivation

In practice, most schemas are not standalone. They are often embedded inside larger documents such as OpenAPI specs. Right now, validating those requires manually extracting the schema first, which is inconvenient.

This change makes that workflow much simpler. You can directly point to the part of the document you want to validate.

Example:

jsonschema validate openapi.json instance.json \
  --path /components/schemas/User

This also fits with the direction discussed in #80, where the goal is to make it easier to work with embedded schemas without needing full OpenAPI parsing.

---

What this does

• Adds a new --path <pointer> option to validate
• Uses existing utilities (to_pointer, try_get) to resolve the JSON Pointer
• Extracts the target sub-schema before running validation, so the rest of the pipeline stays unchanged
• Adds a check to prevent using --path together with --template
• Updates the CLI help text

---

Error handling

• If the pointer does not resolve, validation fails using existing schema error handling
• If the resolved value is not a valid schema, existing validation checks handle it
• Invalid pointer syntax behaves the same way as other pointer-based options such as --entrypoint

No new error types are introduced. Existing ones are reused to stay consistent with current CLI behavior.

---

Tests

Added a small set of tests following existing patterns:

• pass_path_openapi checks validating a schema inside an OpenAPI document
• fail_path_not_found checks when the pointer does not resolve
• fail_path_not_schema checks when the resolved value is not a schema
• fail_path_with_template checks the CLI option conflict

Tests focus on exit codes and stable output to avoid fragile assertions.

---

Notes

This change is intentionally scoped to validate as a first step. It keeps the implementation simple and consistent with existing patterns.

It also provides a practical way to work with embedded schemas today, while leaving room for broader OpenAPI support in the future.

[Vaibhav701161]

Hi @jviotti, could you take a look when you have time? Would love your thoughts, especially if there are any edge cases I missed.

[Copilot]

Pull request overview

Adds a --path option to the validate CLI command so users can target and validate a sub-schema inside a larger JSON/YAML document via JSON Pointer (e.g., OpenAPI documents).

Changes:

• Adds --path <pointer> to the validate command and documents it in CLI help.
• Extracts the pointed sub-schema before running the existing validation pipeline and blocks --path + --template together.
• Adds new validate CLI tests for success and failure cases involving --path.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/command_validate.cc	Implements --path extraction logic and adds --path/--template conflict handling.
src/main.cc	Registers the new validate option and updates CLI help text.
test/CMakeLists.txt	Adds the new validate --path shell tests to the test suite.
test/validate/pass_path_openapi.sh	Validates extracting a schema embedded in an OpenAPI-like document.
test/validate/fail_path_not_found.sh	Asserts failure when the pointer doesn’t resolve.
test/validate/fail_path_not_schema.sh	Asserts failure when the pointed value isn’t a schema.
test/validate/fail_path_with_template.sh	Asserts CLI argument conflict handling for --path with --template.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[augmentcode]

🤖 Augment PR Summary

Summary: This PR adds a --path option to the validate command so users can validate a sub-schema embedded inside a larger JSON/YAML document via JSON Pointer.

Changes:

• Added CLI parsing and help text for jsonschema validate ... --path <pointer>.
• Implemented pointer resolution in command_validate.cc using to_pointer + try_get, then validates/bundles the extracted sub-schema.
• Added an explicit option conflict: --path cannot be combined with --template.
• Kept existing validation/bundling pipeline unchanged by performing extraction before schema checks and bundling.
• Added Unix shell tests covering: success on OpenAPI-like documents, pointer not found, target not a schema, and conflict with --template.

Technical Notes: The implementation copies the pointed-to sub-schema before reassigning to avoid aliasing/use-after-free when the pointer references the same underlying JSON storage.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[cubic-dev-ai]

1 issue found across 7 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="test/CMakeLists.txt">

<violation number="1" location="test/CMakeLists.txt:232">
P2: New `--path` failure tests are registered without JSON-error assertions for two failure modes, leaving structured error output untested.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

2 issues found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="test/validate/fail_path_ref_outside_subtree.sh">

<violation number="1" location="test/validate/fail_path_ref_outside_subtree.sh:32">
P2: New failure test lacks a companion `--json` assertion, so structured error output for this scenario is not covered.</violation>

<violation number="2" location="test/validate/fail_path_ref_outside_subtree.sh:36">
P2: Failure test is too broad: it suppresses output and only checks for any non-zero exit code, so unrelated errors can falsely pass.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}