webui: show error when JSON does not follow expected result document schema

[devs6186]

closes #2363

When a user loads a JSON file (from disk or URL) that is valid JSON but does not match the capa result document schema, the web explorer silently fails or shows a misleading error. This makes it hard to diagnose issues, especially with links from VirusTotal or other services that may return stale/incomplete data.

Changes

• Added validateRdocSchema() in useRdocLoader.js that checks for the required fields: meta, meta.version, meta.analysis, meta.analysis.layout, and rules.
• After JSON.parse, validation runs before any further processing.
• On failure, a clear toast error is shown. For URL sources (e.g. VirusTotal), the message also suggests reanalyzing and retrying.

Checklist

• No CHANGELOG update needed
• No new tests needed
• No documentation update needed
• This submission includes AI-generated code and I have provided details in the description.

[gemini-code-assist]

Summary of Changes

Hello @devs6186, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses an issue where the web UI would silently fail or show misleading errors when attempting to load JSON files that were syntactically valid but did not adhere to the expected capa result document schema. By introducing explicit schema validation and more informative error messages, the changes significantly improve the user experience by providing clearer feedback and actionable advice, especially for data loaded from external URL sources.

Highlights

• Schema Validation: Implemented a new validateRdocSchema() function to ensure loaded JSON data conforms to the expected capa result document schema, checking for critical fields like meta, meta.version, meta.analysis, meta.analysis.layout, and rules.
• Improved Error Handling: Enhanced error messaging for invalid result documents. If validation fails, a clear toast error is displayed. For URL sources (e.g., VirusTotal), the error message now includes a suggestion to reanalyze the file.
• Integration into Loader: Integrated the schema validation directly into the loadRdoc function within useRdocLoader.js, ensuring that validation occurs immediately after JSON parsing and before further processing.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• CHANGELOG.md
  • Added a changelog entry for the web UI update, detailing the new error handling for invalid result document schemas and the suggestion for VirusTotal URLs.
• web/explorer/src/composables/useRdocLoader.js
  • Introduced validateRdocSchema function to perform structural validation of result document JSON.
  • Modified loadRdoc to call validateRdocSchema after data processing.
  • Updated error handling in loadRdoc to display specific toast messages for schema validation failures and general JSON parsing errors, including a reanalysis suggestion for URL sources.

Activity

• The pull request addresses and closes issue webui: show error if JSON does not follow the expected schema #2363, which reported silent failures or misleading errors when loading malformed JSON result documents.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces schema validation for loaded JSON files, which is a great improvement for error handling. I've identified a potential bug in the validation logic where an array could be incorrectly treated as a valid object, and I've provided a suggestion to fix it. Additionally, I've suggested a refactoring to improve maintainability by removing a duplicated error message string. Overall, these are solid changes that enhance the tool's robustness and user experience.

[devs6186]

Thanks for the thorough review, @gemini-code-assist!

Both suggestions have been addressed in the latest commit (c31cfe71):

[High] Array validation bug in validateRdocSchema
Introduced a local isInvalidObject helper that adds the missing Array.isArray() guard:

const isInvalidObject = (v) => !v || typeof v !== "object" || Array.isArray(v);

All six object-field checks now use this helper, so a field that is an array (e.g. "meta": []) is correctly rejected.

[Medium] Duplicated VirusTotal suggestion string in loadRdoc
Extracted the repeated string into a single constant:

const VT_REANALYZE_SUGGESTION =
    " If this is a VirusTotal or similar link, the file may need to be reanalyzed. Try again later.";

Both branches now reference VT_REANALYZE_SUGGESTION, so any future wording change only needs to happen in one place.

ESLint and vitest both pass clean after the changes. Please take another look when you get a chance.

[gemini-code-assist]

Code Review

This pull request introduces schema validation for loaded JSON result documents, which is a great improvement for error handling and user experience. When a document doesn't match the expected schema, a clear error message is now displayed. The change also includes a helpful suggestion to reanalyze files from sources like VirusTotal in case of parsing or validation errors.

My review includes a suggestion to enhance the schema validation to cover another field that is used later in the application, which will prevent potential runtime errors. I've also included a minor suggestion to improve code organization by moving a constant to a more appropriate scope.

[devs6186]

Thanks for the review. I’ve applied both suggestions:

feature_counts validation – validateRdocSchema() now checks that meta.analysis.feature_counts exists and is an object, and that it has either a functions or processes array (for static vs dynamic docs). That way parseFunctionCapabilities and anything else that reads doc.meta.analysis.feature_counts won’t run on invalid or incomplete JSON, and we show a clear validation error instead of a runtime error later.

VT_REANALYZE_SUGGESTION – Moved to module scope at the top of useRdocLoader.js so it’s defined once instead of on every loadRdoc call.

Changes are pushed; happy to adjust wording or validation rules if you’d like.

[mike-hunhoff]

Hi @fariss , could I please get another set of eyes on these changes?

[fariss]

Hi @devs6186 thanks for the implementation and @mike-hunhoff for the review.

I've tested this locally by generating test files (for example, jq 'del(.meta.analysis.layout)' /tmp/rdoc.json > /tmp/rdoc_no_layout.json) and uploading them. It throws the same errors as shown in this PR.

[mike-hunhoff]

Hi @devs6186 thanks for the implementation and @mike-hunhoff for the review.

I've tested this locally by generating test files (for example, jq 'del(.meta.analysis.layout)' /tmp/rdoc.json > /tmp/rdoc_no_layout.json) and uploading them. It throws the same errors as shown in this PR.

You rock @fariss , thank you!