feat(cli): dirctl validate

[akijakya]

This PR adds validate command to dirctl to either validate a local json file, or the whole content of the directory with different settings. Latter is done in batches, a test I ran that validated 3214 records finished in 10:17 mins.

dirctl validate --help
Validate OASF record JSON against the OASF schema. The JSON can be provided
as a file path or piped from stdin (e.g., from dirctl pull).

You must specify either --url for API-based validation or --disable-api for
embedded schema validation.

Usage examples:

1. Validate a file using embedded schemas (no API calls):
   dirctl validate record.json --disable-api

2. Validate a file with API-based validation:
   dirctl validate record.json --url https://schema.oasf.outshift.com

3. Validate a file with non-strict mode (more permissive, only works with --url):
   dirctl validate record.json --url https://schema.oasf.outshift.com --disable-strict

4. Validate JSON piped from stdin:
   cat record.json | dirctl validate --disable-api

5. Validate a record pulled from directory:
   dirctl pull <cid> | dirctl validate --disable-api

Note: You must specify either --url (for API validation) or --disable-api
(for embedded schema validation).

Usage:
  dirctl validate [<file>] [flags]

Flags:
      --disable-api      Disable API-based validation (use embedded schemas instead, required if --url is not specified)
      --disable-strict   Disable strict validation mode (more permissive validation, only works with --url)
  -h, --help             help for validate
      --url string       OASF schema URL for API-based validation (required if --disable-api is not specified)

Closes #767

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf CI / verify-proto (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	⏩ skipped	✅ passed	Jan 9, 2026, 3:43 PM

[ramizpolic]

We should reconsider flag usage, for example:

• default case, no flags -> runs embedded schema validation
• --api -> runs api-based validation
• --strict -> runs api-based validation in strict mode

i think following default + enable approach is more intuitive than enforcing certain checks which need to be explicitly disabled

[ramizpolic]

i dont think we need to have -all to run validation agianst the server, this will quickly exhaust the API rate limiting. this should really be a local-only API (which can be fed by other commands)

[akijakya]

We should reconsider flag usage, for example:

• default case, no flags -> runs embedded schema validation
• --api -> runs api-based validation
• --strict -> runs api-based validation in strict mode

i think following default + enable approach is more intuitive than enforcing certain checks which need to be explicitly disabled

These flags are mirroring the available settings for the directory:
DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL
DIRECTORY_SERVER_OASF_API_VALIDATION_DISABLE
DIRECTORY_SERVER_OASF_API_VALIDATION_STRICT_MODE

And the default validation mode is the API validation, that is why if neither of these settings are provided, both dir and this command returns an error that it needs an OASF URL, or the API validator to be disabled.

[akijakya]

i dont think we need to have -all to run validation agianst the server, this will quickly exhaust the API rate limiting. this should really be a local-only API (which can be fed by other commands)

I agree that it has its limits if we are talking about a directory instance with hundreds of thousands of records... my goal with --all was to offer an easy way to validate a directory node in these early days when the OASF validator is also improving, so it might catch additional errors after an update, it might also be useful in other cases like before joining a node to the network, or accidentally changing the validation settings of a node and to make sure no invalid records were pushed in the meantime?

Another idea could be for the validate command to also accept a cid from the directory (not just a local file), which could then be scripted to check multiple cids from a directory instance if the user really wants to validate more than one record at a time, wdyt?

Or instead of a path, it could expect the json data directly, so it could be piped into it either from a local file, or the output of a dirctl pull command.

[akijakya]

@ramizpolic I removed the -all flag, but now the command can accept stdin as input so the result of a dirctl pull <cid> --output json can be piped into it. Also added tests with files for different validation scenarios.