Define & Validate APIsValidation Rulesets
API Blueprint Rulesets
The ruleset APIMatic uses to validate API Blueprint documents.
APIMatic validates API Blueprint documents against the ruleset below. These include rules defined by the standard as well as additional checks APIMatic enforces for better output.
API Blueprint Validation
Validation checks performed on an API Blueprint or API Elements file.
| Property | Value |
|---|---|
| Ruleset ID | api-blueprint-validation |
| Code prefix | APIBLUEPRINT_V |
| Type | Validation |
| Default severity | Error |
| Rule system | Semantic |
| Rules | 10 |
Basic Structure
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIBLUEPRINT_V001 | no-tab-indentation | Blocking | An API Blueprint file must not use tab(s) \t to indent sections. Only spaces are currently supported in the Apiary platform. |
APIBLUEPRINT_V002 | required-metadata-format | Blocking | An API Blueprint file is identified and distinguished from a normal Markdown file using the FORMAT key-value pair. It is usually placed in the first line of the metadata section. This keyword must be present and its value must be set as 1A. |
APIBLUEPRINT_V003 | valid-metadata-format | Blocking | An API Blueprint file is identified and distinguished from a normal Markdown file using the FORMAT key-value pair. This keyword must have its value set as 1A. |
APIBLUEPRINT_V004 | no-large-payload | Blocking | The input API Blueprint/Elements file provided must not be very large. Keep the size optimal to avoid any issues. |
APIBLUEPRINT_V005 | valid-apiary-file | Blocking | If you intend to use the API Blueprint file inside Apiary, it must be valid for it i.e. it must not contain any syntax/semantic issues. |
APIBLUEPRINT_V006 | valid-entity-type | Error | Each element in an API Blueprint/Elements file must have a correct type assigned to it as per the standards. |
API Resources
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIBLUEPRINT_V100 | no-request-body-in-resource-get-method | Warning | A resource in an API Blueprint/Elements file must not define an Attributes or a Payload section for the request when the actions use the GET HTTP method. This is because such methods do not expect a body and, therefore, all related information will be automatically ignored during import/transformations in APIMatic. |
APIBLUEPRINT_V101 | supported-response-code | Warning | If multiple responses are disabled via import settings provided in the APIMatic Metadata file, only response definitions belonging to status code ranges 200-208 and 400-599 will be imported. Those outside the supported range will be ignored automatically during import/transformations in APIMatic. |
Data Structures
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIBLUEPRINT_V300 | required-data-structure-property-name | Error | A data structure that defines an object must specify a non-empty name for each property which is part of the object. Properties with missing name will be ignored automatically when importing/transforming the document in APIMatic. |
APIBLUEPRINT_V301 | valid-json-schema | Error | If a JSON schema is embedded in an API Blueprint/Elements file to provide a data definition, it must be valid as per standards. |