Our website uses cookies to enhance your browsing experience.
Accept
to the top
close form

Fill out the form in 2 simple steps below:

Your contact information:

Step 1
Congratulations! This is your promo code!

Desired license type:

Step 2
Team license
Enterprise license
** By clicking this button you agree to our Privacy Policy statement
close form
Request our prices
New License
License Renewal
--Select currency--
USD
EUR
* By clicking this button you agree to our Privacy Policy statement

close form
Free PVS‑Studio license for Microsoft MVP specialists
* By clicking this button you agree to our Privacy Policy statement

close form
To get the licence for your open-source project, please fill out this form
* By clicking this button you agree to our Privacy Policy statement

close form
I am interested to try it on the platforms:
* By clicking this button you agree to our Privacy Policy statement

close form
check circle
Message submitted.

Your message has been sent. We will email you at


If you do not see the email in your inbox, please check if it is filtered to one of the following folders:

  • Promotion
  • Updates
  • Spam

Webinar: Parsing C++ - 10.10

>
>
User annotation mechanism in JSON format
menu mobile close menu
Analyzer diagnostics
General Analysis (C++)
General Analysis (C#)
General Analysis (Java)
Micro-Optimizations (C++)
Diagnosis of 64-bit errors (Viva64, C++)
Customer specific requests (C++)
MISRA errors
AUTOSAR errors
OWASP errors (C#)
Problems related to code analyzer
Additional information
toggle menu Contents

User annotation mechanism in JSON format

Oct 02 2024

The JSON annotation mechanism is a way of marking up user-defined functions and types in JSON format files. The mechanism enables a user to provide the analyzer with additional information about their code. This information helps the analyzer to both find more errors and issue less false positives.

By using separate annotation files, you can resolve the following issues:

  • the markup (annotation) of third-party code, libraries, and components;
  • using different sets of annotations depending on the scenarios of the analyzer use.

If these cases are not relevant to you, and you would like to perform markup directly in the source code, please consult this documentation.

The mechanism currently supports the following languages:

  • C and C++ (starting with the 7.31 version);
  • C# (starting with the 7.33 version);

Follow these steps to use the mechanism:

  • create a JSON file;
  • write the necessary annotations according to the JSON schemas;
  • enable annotation files in the analysis via the way that suits you best.

Available features vary by language. After consulting the general documentation, please read the language-specific part as well:

How to enable annotation files

These are the ways to enable an already existing annotation file:

Option N1. Add a special comment to the source code or to the configuration file of diagnostic rules (.pvsconfig):

//V_PVS_ANNOTATIONS, language:%project_language%, path:%path/to/file.json%

Use one of the following values instead of the %project_language% placeholder:

  • c is for C;
  • cpp is for for C++;
  • csharp is for C#.

Instead of the %path/to/file.json% placeholder, use the path to the annotation file you want to enable. Both absolute and relative paths are supported. Relative paths are expanded relative to the file that contains the comment for enabling the annotation.

OptionN2 (C and C++ analyzer only) Specify the ‑‑annotation-file (-A) special flag when running pvs-studio-analyzer or CompilerCommandsAnalyzer:

pvs-studio-analyzer --annotation-file=%path/to/file.json%

Instead of the %path/to/file.json% wildcard character, use the path to the annotation file you want to enable. Both absolute and relative paths are supported. Relative paths are expanded relative to the current working directory (CWD).

Note 1. You can have multiple annotation files enabled. Specify a separate flag or comment for each file.

Note 2. Prior to version 7.33, for C and C++, you could enable annotations using a comment of the following type:

//V_PVS_ANNOTATIONS %path/to/file%

In this case, starting from version 7.33, you will get a message about using an outdated syntax and a suggestion to switch to a new one.

How to facilitate the annotation workflow

Ready-to-use examples

To help you understand how to work with the user annotation mechanism, we have prepared a list of examples for the most common scenarios:

  • How to annotate the nullable type (C++)?
  • How to mark a function as dangerous or deprecated (C++)?
  • How to mark a function as a source/sink of taint data (C, C++, C#)?

You can find more use cases in the language-specific documentation of the mechanism:

JSON schemas

A JSON schema with versioning support is created for each available language. These schemas help modern text editors and IDEs validate and suggest hints while editing.

When you create your own annotation file, add the $schema field to it and set the value for the required language. For example, the value for the C and C++ analyzer looks like this:

{

    "version": 1,

    "$schema": "https://files.pvs-studio.com/media/custom_annotations/v1/cpp-annotations.schema.json",

    "annotations": [

        { .... }

    ]

}

This enables Visual Studio Code to provide hints when creating annotations:

Custom_annotations_JSON/image1.png

JSON schemas are currently available for annotations in the following languages:

Analyzer warnings

Not all issues can be detected when validating the JSON schema. If an error occurs while working with a file that contains annotations, the analyzer issues the V019 warning. It helps understand what went wrong. For example, the annotation file is missing, a parsing error has occurred, an annotation has been skipped due to errors in it, etc.

Custom_annotations_JSON/image2.png