APIMatic Validation Report

Validation Summary

Introduction

This API definition validation report for SidneyAllen was compiled on March 05, 2025. It provides a summary of the validation results for all involved API definitions.

What is APIMatic?

APIMatic is a Developer Experience platform for Web APIs, offering auto-generated SDKs, usage examples, and interactive documentation. Our goal is to streamline API onboarding and adoption.

API Definition Validation

APIMatic ensures API specifications are syntactically and semantically correct to generate high-quality documentation and SDKs. This report details the validation results, highlighting any blockers that must be resolved. Visit our official documentation for more information.

Fixing Validation Issues

To resolve issues or re-validate API definitions, use our VS Code extension Fix My OpenAPI, which offers dedicated views and other features for improving API definitions.

Contact Us

For queries or concerns, reach out to us at support@apimatic.io .

Data Overview

This report analyzes an API named APIMATIC Calculator-test which is defined using the specification format OpenAPI v3.0 (JSON). The files involved are listed below:

#	File Path	File Specification Format
1	Apimatic-Calculator.json	OpenAPI v3.0 (JSON) (Main File)

Table of Contents

• Validation Summary
• Data Overview
• Validation Issues (0)
• Lint Issues (11)
  • Error Issue No. 1 - Operation id is invalid. (1)
  • Warn Issue No. 2 - Unsupported extension detected. (1)
  • Warn Issue No. 3 - No security mechanism applied to the API. (1)
  • Info Issue No. 4 - The root OpenAPI file name does not follow recommended conventions. (1)
  • Info Issue No. 5 - Schema object description is missing. (1)
  • Info Issue No. 6 - Schema object example/default value is missing. (3)
  • Info Issue No. 7 - Media type object example is missing. (1)
  • Info Issue No. 8 - Response object description is missing. (1)
  • Info Issue No. 9 - Parameter object example is missing. (3)
  • Info Issue No. 10 - Property `explode` will have no effect on parameter of this type. (2)
  • Info Issue No. 11 - Description is missing in tag object (1)

Validation Issues

No validation issues were found.

Lint Issues

A total no. of 11 lint issues were found which are listed below:

• Error Issue No. 1 - Operation id is invalid. (1)
• Warn Issue No. 2 - Unsupported extension detected. (1)
• Warn Issue No. 3 - No security mechanism applied to the API. (1)
• Info Issue No. 4 - The root OpenAPI file name does not follow recommended conventions. (1)
• Info Issue No. 5 - Schema object description is missing. (1)
• Info Issue No. 6 - Schema object example/default value is missing. (3)
• Info Issue No. 7 - Media type object example is missing. (1)
• Info Issue No. 8 - Response object description is missing. (1)
• Info Issue No. 9 - Parameter object example is missing. (3)
• Info Issue No. 10 - Property `explode` will have no effect on parameter of this type. (2)
• Info Issue No. 11 - Description is missing in tag object (1)

Error Issue No. 1 - Operation id is invalid. (1)

Rule Id	valid-operation-id
Ruleset Id	openapi-v3-codegen-syntax-linting
Type of Issue	Syntax
Broad Category of Issue	OpenAPI Operations
Possible Impact On Output Of	Code Generation , Developer Experience Portal

Description

The id of an Operation Object specified using the `operationId` property is a unique identifier of the operation in the complete API document. This id is used by the code generation engine to generate relevant components tied to an endpoint. Therefore, the id must be short and code-friendly. The id must only use letters, numbers, underscores and dashes. It must not contain any leading/trailing white-space characters. Names are often used for naming the files generated as part of the code generation process, so, any forbidden file name characters are not allowed either.

Tips

• Make sure that the id does not contain any forbidden characters.
• Use only letters, numbers, underscores and dashes.
• Remove any trailing/leading white-space characters, if present.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: Apimatic-Calculator.json , Line No: 25, Line Pos: 24 - Line No: 25, Line Pos: 39, Path: # > paths > /{operation} > get > operationId
   • Invalid Operation Id: Calculate@#$/

Warn Issue No. 2 - Unsupported extension detected. (1)

Rule Id	supported-vendor-extension
Ruleset Id	openapi-v3-apimatic-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Vendor Extensions
Possible Impact On Output Of	API Transformer , Code Generation, Developer Experience Portal

Description

APIMatic supports certain vendor extensions which are loaded at the time of importing API description files containing these extensions. These include APIMatic specific extensions as well that are used for configuring products like Code Generation, Transformer, etc. All other extensions will be ignored or may not work as expected.

Tips

• Remove unsupported vendor extensions from your API description file.
• Contact APIMatic team to know more about whether a specific vendor extension is supported or not. In some cases, we may decide to support the vendor extension if its importance is established.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions
• https://docs.apimatic.io/specification-extensions/spec-extensions-overview/
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: Apimatic-Calculator.json , Line No: 8, Line Pos: 5 - Line No: 8, Line Pos: 20, Path: # > info
   • Unsupported Extension: x-extension-1

Warn Issue No. 3 - No security mechanism applied to the API. (1)

Rule Id	at-least-one-security-mechanism-applied
Ruleset Id	openapi-v3-apimatic-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Security Requirements
Possible Impact On Output Of	API Transformer , Code Generation, Developer Experience Portal

Description

APIs that require some form of authentication must define the security schemes used, in the global Components Object using the `securitySchemes` property and apply these security schemes to the endpoints that require authentication. This will ensure that the requests that require authentication are authenticated properly.

Tips

• Remove any Authorization header definitions from the operations and instead define the authentication mechanism using the OpenAPI's global security schemes. Then apply those schemes to operations as required.
• When defining a security scheme globally assign a short but unique name for it.
• Choose the appropriate security scheme type when defining a security scheme.
• If your API does not require authentication, you can ignore this lint check or disable it.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#components-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-scheme-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: Apimatic-Calculator.json , Line No: 79, Line Pos: 17 - Line No: 79, Line Pos: 18, Path: # > components

Info Issue No. 4 - The root OpenAPI file name does not follow recommended conventions. (1)

Rule Id	valid-openapi-file-naming-conventions
Ruleset Id	openapi-v3-standards-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Root Information
Possible Impact On Output Of	API Transformer , Code Generation, Developer Experience Portal

Description

The root OpenAPI document is recommended to be named as either `openapi.json` or `openapi.yaml` depending upon the data format used in the file.

Tips

• Main or root OpenAPI file is one which contains the OpenAPI version, paths and other information.
• Standardized naming of files helps improve their discoverability for your users.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#document-structure
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#document-structure
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: Apimatic-Calculator.json , Line No: 1, Line Pos: 1 - Line No: 1, Line Pos: 2, Path: #
   • Current File Name: Apimatic-Calculator.json

Info Issue No. 5 - Schema object description is missing. (1)

Rule Id	schema-description-exists
Ruleset Id	openapi-v3-docsgen-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Schemas
Possible Impact On Output Of	Developer Experience Portal

Description

The Schema Object must specify details about the schema or the type of data it represents, using the `description` property. The value of the description must be non-null and non-empty.

Tips

• Ensure that the Schema Object contains the `description` property.
• Ensure that Schema Object description value is not null or empty.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: Apimatic-Calculator.json , Line No: 67, Line Pos: 27 - Line No: 67, Line Pos: 28, Path: # > paths > /{operation} > get > responses > 200 > content > text/plain > schema

Info Issue No. 6 - Schema object example/default value is missing. (3)

Rule Id	schema-example-or-default-value-exists
Ruleset Id	openapi-v3-docsgen-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Schemas
Possible Impact On Output Of	Developer Experience Portal

Description

Schema Object must specify a non-null, non-empty example value using the `example` property or a default value using the `default` property if applicable.

Tips

• If the schema definition has a default value, it must be specified using the `default` value.
• If the schema has no default value, ensure that the `example` property is present in the Schema Object.
• Ensure that the schema example or default value is not empty or null.
• The example or default value specified must be valid in accordance with the schema type definition.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (3)

1. File: Apimatic-Calculator.json , Line No: 43, Line Pos: 23 - Line No: 43, Line Pos: 24, Path: # > paths > /{operation} > get > parameters > 1 > schema
2. File: Apimatic-Calculator.json , Line No: 55, Line Pos: 23 - Line No: 55, Line Pos: 24, Path: # > paths > /{operation} > get > parameters > 2 > schema
3. File: Apimatic-Calculator.json , Line No: 67, Line Pos: 27 - Line No: 67, Line Pos: 28, Path: # > paths > /{operation} > get > responses > 200 > content > text/plain > schema

Info Issue No. 7 - Media type object example is missing. (1)

Rule Id	mediaType-example-or-examples-exist
Ruleset Id	openapi-v3-docsgen-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Media Types
Possible Impact On Output Of	Developer Experience Portal

Description

Media Type Object must specify a non-null, non-empty example value using either the `example` or `examples` property.

Tips

• Ensure that either `example` or `examples` property is present in the Media Type Object.
• `example` and `examples` are mutually exclusive properties.
• When using the `examples` list, make sure that the list is not empty.
• Ensure that the media type example value is not empty or null.
• The example value specified must be valid in accordance with the media type schema definition.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#media-type-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: Apimatic-Calculator.json , Line No: 66, Line Pos: 29 - Line No: 66, Line Pos: 30, Path: # > paths > /{operation} > get > responses > 200 > content > text/plain

Info Issue No. 8 - Response object description is missing. (1)

Rule Id	response-description-exists
Ruleset Id	openapi-v3-docsgen-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Responses
Possible Impact On Output Of	Developer Experience Portal

Description

The Response Object must specify details about the response using the `description` property. The value of the description must be non-null and non-empty.

Tips

• Ensure that the Response Object contains the `description` property.
• Ensure that Response Object description value is not null or empty.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#response-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: Apimatic-Calculator.json , Line No: 63, Line Pos: 13 - Line No: 63, Line Pos: 26, Path: # > paths > /{operation} > get > responses > 200

Info Issue No. 9 - Parameter object example is missing. (3)

Rule Id	parameter-example-or-examples-exist
Ruleset Id	openapi-v3-docsgen-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Parameters
Possible Impact On Output Of	Developer Experience Portal

Description

Parameter Object must specify a non-null, non-empty example value using either the `example` or `examples` property.

Tips

• Ensure that either `example` or `examples` property is present in the Parameter Object.
• `example` and `examples` are mutually exclusive properties.
• When using the `examples` list, make sure that the list is not empty.
• Ensure that the parameter example value is not empty or null.
• The example value specified must be valid in accordance with the parameter schema definition.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterObject
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (3)

1. File: Apimatic-Calculator.json , Line No: 27, Line Pos: 11 - Line No: 27, Line Pos: 12, Path: # > paths > /{operation} > get > parameters > 0
   • Parameter Name: operation
2. File: Apimatic-Calculator.json , Line No: 36, Line Pos: 11 - Line No: 36, Line Pos: 12, Path: # > paths > /{operation} > get > parameters > 1
   • Parameter Name: x
3. File: Apimatic-Calculator.json , Line No: 48, Line Pos: 11 - Line No: 48, Line Pos: 12, Path: # > paths > /{operation} > get > parameters > 2
   • Parameter Name: y

Info Issue No. 10 - Property `explode` will have no effect on parameter of this type. (2)

Rule Id	parameter-explode-only-for-array-or-object-types
Ruleset Id	openapi-v3-standards-linting
Type of Issue	Semantic
Broad Category of Issue	Parameters
Possible Impact On Output Of	API Transformer , Code Generation, Developer Experience Portal

Description

When parameter explode is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect.

Tips

• Remove property `explode` from the current Parameter Object.
• Change the parameter type to `array` or `object` if you still intend to use the `explode` option.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameter-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (2)

1. File: Apimatic-Calculator.json , Line No: 42, Line Pos: 13 - Line No: 42, Line Pos: 22, Path: # > paths > /{operation} > get > parameters > 1
   • Current Parameter Type: number
2. File: Apimatic-Calculator.json , Line No: 54, Line Pos: 13 - Line No: 54, Line Pos: 22, Path: # > paths > /{operation} > get > parameters > 2
   • Current Parameter Type: number

Info Issue No. 11 - Description is missing in tag object (1)

Rule Id	tag-description-exists
Ruleset Id	openapi-v3-docsgen-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Tags
Possible Impact On Output Of	Developer Experience Portal

Description

Tag Object must have a non-null non-empty description.

Tips

• Add a user-friendly description of the tag object.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#tag-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: Apimatic-Calculator.json , Line No: 99, Line Pos: 5 - Line No: 99, Line Pos: 6, Path: # > tags > 0