Spliceforms API Rules

**Model description must be present and non-empty string.** - Each Model in your schema must include a `description` field. - The `description` field must be a non-empty string. #### Valid Example ```json "UserProfile": { "type": "object", "description": "Represents a user's profile information.", "properties": { "name": { "type": "string" } } } ``` #### Invalid Example ```json "UserProfile": { "type": "object", "properties": { "name": { "type": "string" } } } ```

**Operation Summary Rules:** - Must start with an uppercase letter - Must end with a period (dot) #### Valid Examples ```json { "summary": "Get user details." } ``` #### Invalid Examples ```json { "summary": "get user details" } ```

**Property description must be present and non-empty string.** - Each Property in your schema must include a `description` field. - The `description` field must be a non-empty string. #### Valid Example ```json "User": { "type": "object", "properties": { "username": { "type": "string", "description": "The username of the user." }, "age": { "type": "integer", "description": "The age of the user." } } } ``` #### Invalid Example ```json "User": { "type": "object", "properties": { "username": { "type": "string", }, "age": { "type": "integer", "description": "" } } } ```

**Definition names must be in Upper CamelCase:** - Examples of valid names: `Account`, `UserProfile`, `OrderDetails`, `ProductID` - Examples of invalid names: `account`, `userProfile`, `order_details`, `productid` #### Valid Json ```json "Account": { "type": "object", "properties": { "accountNumber": { "type": "string", "description": "Account number." }, } } ``` #### Invalid Json ```json "account": { "type": "object", "properties": { "accountNumber": { "type": "string", "description": "Account number." }, } } ```

**String properties must have an `example` field:** Every string property in your schema must include an `example` field to provide sample values. #### Json Example: ```json { "type": "object", "properties": { "username": { "type": "string", "example": "john_doe" }, "email": { "type": "string", "example": "john.doe@example.com" } } }

**HTTP Header Fields in request Must Be in Hyphenated-Upper-Camel-Case** HTTP header fields in request parameters should be formatted using Hyphenated-Upper-Camel-Case. This means each word starts with an uppercase letter and is separated by hyphens. #### Valid Examples ```json { "headers": { "X-Api-Key": "123456", "User-Agent": "MyApp/1.0" } } ``` #### Invalid Examples ```json { "headers": { "x-api-key": "123456", // should be "X-Api-Key" "user-agent": "MyApp/1.0" // should be "User-Agent" } } ``

**The 'Pattern' property must be present and non-empty for string properties** For string properties in your schema, the `Pattern` property must be specified and must not be an empty string. This ensures that the string values conform to the expected format. #### Valid Example ```json { "type": "object", "properties": { "username": { "type": "string", "pattern": "^[a-zA-Z0-9_]+$" } } } ``` #### Invalid Example ```json { "type": "object", "properties": { "username": { "type": "string", "pattern": "" } "email": { "type": "string" } } } ```

**Path segments (parameters) must be in lower camel case:** - Path parameters should be written in lower camel case format. This means the first letter should be lowercase, and subsequent words should start with an uppercase letter. - Examples of valid names: `userId`, `orderNumber`, `productCode` - Examples of invalid names: `UserID`, `order_number`, `PRODUCTCODE` #### Valid Example ```json "/users/{userId}": { "get": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ] } } ``` #### Invalid Example ```json "/products/{PRODUCTCODE}": { "get": { "parameters": [ { "name": "PRODUCTCODE", "in": "path", "required": true, "schema": { "type": "string" } } ] } } ```

**Property names must be in lower camel case:** - Examples of valid names: `userName`, `orderId`, `productCode` - Examples of invalid names: `UserName`, `order_id`, `ProductCode` #### Json Example: ```json { "userName": "JohnDoe", "orderId": "12345", "productCode": "XYZ789" } ```

**Query parameter names must be in lower camel case:** - Examples of valid names: `userId`, `orderNumber`, `productName` - Examples of invalid names: `UserId`, `order_number`, `ProductName` #### JSON Example: ```json { "parameters": [ { "name": "userId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "orderNumber", "in": "query", "required": true, "schema": { "type": "string" } } ] } ```

**HTTP Header Fields in Response Must Be in Hyphenated-Upper-Camel-Case** HTTP header fields in response parameters should be formatted using Hyphenated-Upper-Camel-Case. This means each word starts with an uppercase letter and is separated by hyphens. #### Valid Examples ```json { "headers": { "X-Api-Key": "123456" } } ``` #### Invalid Examples ```json { "headers": { "x-api-key": "123456" // should be "X-Api-Key" } } ``

**Model Definitions must have a type** All model definitions must include a `type` property to specify the type of the model. #### JSON Example: ```json "User": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } ```

**An integer property must include minimum and maximum constraints but must not have exclusiveMinimum or exclusiveMaximum constraints.** Every integer property in your schema must include the following constraints: - `minimum`: The minimum value the integer can take. - `maximum`: The maximum value the integer can take. #### Json Example: ```json { "type": "object", "properties": { "age": { "type": "integer", "minimum": 0, "maximum": 100, "exclusiveMinimum": false, "exclusiveMaximum": false }, "score": { "type": "integer", "minimum": 1, "maximum": 10, "exclusiveMinimum": false, "exclusiveMaximum": false } } }

**Integer properties must have a format and should be either `int32` or `int64`:** **Formats:** - `int32`: A 32-bit signed integer. - `int64`: A 64-bit signed integer. #### Valid Examples ```json { "exampleInt32": { "type": "integer", "format": "int32" }, "exampleInt64": { "type": "integer", "format": "int64" } } ``` #### Invalid Examples ```json { "exampleIntInvalid": { "type": "integer", "format": "int16" }, "anotherInvalidInt": { "type": "integer" } } ```

**Rule: The "Number" type of properties should not have a format attribute.** All numbers are considered in the `BigDecimal` format. #### Valid JSON ```json { "example": { "type": "number" // No format attribute present. } } ``` #### Invalid JSON ```json { "example": { "type": "number", "format": "float" // Invalid: Number properties should not have a format attribute. } } ```

**Property must have a type** - Every property in your schema must have a defined type. #### Valid Examples ```json { "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "required": ["name", "age"] } ``` #### Invalid Examples ```json { "type": "object", "properties": { "name": { "type": "string" }, "age": { } }, "required": ["name", "age"] } ```

**`minLength` and `maxLength` constraints must be present for string properties.** All string properties must have both `minLength` and `maxLength` constraints defined. This ensures that the length of the string values is appropriately restricted. #### Valid Examples ```json { "type": "object", "properties": { "username": { "type": "string", "minLength": 3, "maxLength": 20 }, "password": { "type": "string", "minLength": 8, "maxLength": 50 } } } ``` #### Invalid Examples ```json { "type": "object", "properties": { "username": { "type": "string", "maxLength": 20 }, "password": { "type": "string" } } } ```

**Model must not contain another model inline. `#Ref` property should be used instead.** In OpenAPI definitions, models should not contain other models directly inline. Instead, use the `$ref` property to reference other models. #### Json Example ```json { "components": { "schemas": { "User": { "type": "object", "properties": { "id": { "type": "string" }, "profile": { "$ref": "#/components/schemas/Profile" } } }, "Profile": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" } } } } } }

**Only local schema references must be used.** All schema references should be local to the current document. External schema references are not allowed. #### Valid Example ```json { "$ref": "#/components/schemas/User" } ``` #### Invalid Example ```json { "$ref": "https://example.com/schemas/User" } ```

**Number property must have an `example`:** Each number property in your JSON schema must include an `example` field to provide a sample value. This ensures better documentation and understanding of the expected data format. #### Json Example ```json { "type": "object", "properties": { "age": { "type": "number", "description": "The age of the person", "example": 30 }, "price": { "type": "number", "description": "The price of the item", "example": 99.99 } }, "required": ["age", "price"] }

**Integer property must have an `example`.** Each integer property in your API specification must include an `example` field to ensure clarity and consistency. #### Example JSON ```json { "type": "object", "properties": { "age": { "type": "integer", "example": 30 } } } ``` #### Valid Example ```json { "type": "integer", "example": 123 } ``` #### Invalid Example ```json { "type": "integer" } ```

This rule ensures that an object model in your OpenAPI specification has at least one required field. Additionally, the specified required fields must be present in the `properties` of the object model. #### Valid Json ```json { "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "required": ["name"] } ``` #### Valid Json ```json { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["age"] } ```

This rule ensures that all API responses with status codes in the 4XX or 5XX range (client and server errors) must return a ProblemJson model. #### Valid json ```json { "paths": { "/example": { "get": { "responses": { "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "required": ["type", "title", "status"], "properties": { "type": { "type": "string", "example": "https://example.com/error" }, "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "format": "int32", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred." }, "instance": { "type": "string", "example": "/example/123" } } } } } } } } } } } ``` #### Invalid json ```json { "paths": { "/example": { "get": { "responses": { "500": { "description": "Internal Server Error" // Missing content.application/json } } } } } } { "paths": { "/example": { "get": { "responses": { "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "required": ["type", "title", "status"], "properties": { "type": { "type": "string", "example": "https://example.com/error" }, "title": { "type": "integer", // Invalid type, should be string "example": 123 }, "status": { "type": "string", // Invalid type, should be integer "example": "500" } } } } } } } } } } } ```

This rule validates that if a string property with an `enum` in a schema specifies `pattern`, `minLength`, or `maxLength`, the `enum` values must conform to these constraints. #### Valid Example ```json { "components": { "schemas": { "ExampleSchema": { "type": "object", "properties": { "validStringProperty": { "type": "string", "enum": [ "ABC123", "DEF456" ], "pattern": "^[A-Z]{3}\\d{3}$", "minLength": 6, "maxLength": 6 } } } } } } ``` #### Invalid Example ```json { "components": { "schemas": { "ExampleSchema": { "type": "object", "properties": { "invalidStringPropertyMinLength": { "type": "string", "enum": [ "A1", "B2" ], "pattern": "^[A-Z]\\d$", "minLength": 3, "maxLength": 3 } } } } } } ```

This rule ensures that array items do not have an inline object definition. Instead, array items should refer to a defined object using `$ref`. #### Valid Json ```json { "components": { "schemas": { "MyArrayModel": { "type": "array", "items": { "$ref": "#/components/schemas/MyObjectModel" } }, "MyObjectModel": { "type": "object", "properties": { "id": { "type": "string" } } } } } } ``` #### Invalid Json ```json { "components": { "schemas": { "MyArrayModel": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } } } } } } } ```

This rule ensures that object model definitions include a properties field and that this field contains at least one property. #### Valid Json ```json { "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } } } ``` #### Invalid Json ```json { "type": "object" } ``` ```json { "type": "object", "properties": {} } ```

Ensure that response schemas do not return primitive types (array, string, integer, number) directly. Instead, these types should be wrapped inside an object. #### Valid Json ```json { "type": "object", "properties": { "data": { "type": "string" } } } ``` #### Invalid Json ```json { "type": "string" } ```

If a string property has a format of `date` or `date-time`, and `minLength` and `maxLength` are specified, they should correctly reflect the length of a valid date or date-time string. #### valid Json ```json { "type": "object", "properties": { "endDate": { "type": "string", "format": "date", "minLength": 10, "maxLength": 10, "example": "2023-08-18" } } } ``` #### Invalid Json ```json { "type": "object", "properties": { "endDate": { "type": "string", "format": "date", "minLength": 5, // Invalid, should match length of a valid date string "maxLength": 20, // Invalid, should match length of a valid date string "example": "2023-08-18" } } } ```

The ProblemJson model must exist within the OpenAPI specification and include the following required properties and json payload: - type - title - status #### Valid Json Example ```json "ProblemJson": { "title": "ProblemJson", "description": "This schema defines a structured problem details", "x-stoplight": { "id": "xmrewz8ybd807" }, "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "description": "A URI reference that identifies the problem type. This specification encourages that, when dereferenced, it provides human-readable documentation for the problem type.", "example": "https://example.com/probs/out-of-credit", "minLength": 10, "maxLength": 2048, "pattern": "^(https?|ftp):\\/\\/[^\\s/$.?#].[^\\s]*$" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.", "example": "Insufficient credit", "minLength": 1, "maxLength": 256, "pattern": "^[\\w\\s-]+$" }, "status": { "type": "integer", "format": "int32", "description": "The HTTP status code generated by the origin server for this occurrence of the problem.", "example": 400, "minimum": 400, "maximum": 599, "exclusiveMinimum": false, "exclusiveMaximum": false }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem.", "example": "Your account balance is too low to complete this transaction.", "minLength": 1, "maxLength": 1024, "pattern": "^[\\w\\s,.-]+$" }, "instance": { "type": "string", "format": "uri", "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", "example": "https://example.com/account/12345/transactions/abc", "minLength": 10, "maxLength": 2048, "pattern": "^(https?|ftp):\\/\\/[^\\s/$.?#].[^\\s]*$" } } } ```

Properties with $ref must also have a description field to provide context about the referenced schema's usage in this specific context.

The `contact` object should have a valid organization URL. **Valid Example** ```json lineNumbers { "contact": { ... , "url": "https://acme.com", ... }, ```

The `contact` object should have a valid email. **Valid Example** ```json lineNumbers { "contact": { ... , ... , "email": "support.contact@acme.com" }, ```

The `info' object should include a `contact` object. **Valid Example** ```json lineNumbers { "info": { ... , ... , "contact": { "name": "ACME Corporation", "url": "https://acme.com", "email": "support.contact@acme.com" } } } ```

The `info` object should have a `description` object. **Valid Example** ```json lineNumbers { "info": { ... , ... , "description": "This describes my API.", ... } } } ```

The `info` object should have a `license` object. **Valid Example** ```json lineNumbers { "info": { ... , ... , "license": { "name": "Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)", "url": "https://creativecommons.org/licenses/by-sa/4.0/" } } } ```

The `license` object should include a valid url. **Valid Example** ```json lineNumbers { "license": { "name": "Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)", "url": "https://creativecommons.org/licenses/by-sa/4.0/" } } ```

Markdown descriptions should not contain [`eval()` functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval), which pose a security risk. **Invalid Example** ```json lineNumbers { "info": { ... , ... , "description": "API for users. eval()"

Markdown descriptions should not contain `script` tags, which pose a security risk. **Invalid Example** ```json lineNumbers { "info": { ... , ... , "description": "API for users. '," ```

Global tags specified at the root OpenAPI Document level should be in alphabetical order based on the `name` property. **Invalid Example** ```json lineNumbers { "tags":[ { "name":"Z Global Tag" }, { "name":"A Global Tag" } ] } ``` **Valid Example** ```json lineNumbers { "tags":[ { "name":"A Global Tag" }, { "name":"Z Global Tag" } ] } ```

At least one global tag should be specified at the root OpenAPI Document level. **Valid Example** ```json lineNumbers { "tags":[ { "name":"Global Tag #1" }, { "name":"Global Tag #2" } ] } ```

Each operation should have a description. **Valid Example** ```json lineNumbers { "get": { ... , "description": "Get a list of users.", ... , ... , } } ```

All operations should have an `operationId`. **Valid Example** ```json lineNumbers { "get": { "summary": "Get users", ... , "operationId": "get-users" } } ```

Operation IDs must not contain characters that are invalid for URLs. **Invalid Example** The `operationId` in this example includes a pipe and space, which are invalid for URLs. ```json lineNumbers { "/users": { "get": { ... , "operationId": "invalid|operationID ", ... , } } } ``` **Valid Example** This `operationId` is valid for URLs. ```json lineNumbers { "/users": { "get": { ... , "operationId": "this-must-be-unique", ... , } } } ```

Operation should not have more than a single tag.

At least one tag should be defined for each operation. **Valid Example** ```json lineNumbers { "get": { ... , ... , "tags": [ "Users" ], } }

Path parameter declarations must not be empty. **Invalid Example** `/users/{}` **Valid Example** `/users/{userId}`

The `contact` object should have an organization name. **Valid Example** ```json lineNumbers { "contact": { "name": "ACME Corporation", ... , ... }, ```

Path keys should not end in forward slashes. This is a best practice for working with web tooling, such as mock servers, code generators, application frameworks, and more). **Invalid Example** ```json { "/users/": { ``` **Valid Example** ```json { "/users": { ```

Paths should not include `query` string items. Instead, add them as parameters with `in: query`. **Invalid Example** ```json { "/users/{?id}": { ``` **Valid Example** ```json lineNumbers { "parameters": [ { "schema": { "type": "string" }, "name": "id", "in": "path", "required": true, "description": "User's ID" } ] } ```

Tags defined at the global level should have a description. **Valid Example** ```json lineNumbers { "tags": [ { "name":"Users", "description":"End-user information" } ] } ```

A server should be defined at the root document level. This can be localhost, a development server, or a production server. **Valid OpenAPI V3 Example** ```json { "servers": [ { "url": "https://staging.myprodserver.com/v1", "description": "Staging server" }, { "url": "https://myprodserver.com/v1", "description": "Production server" } ] } ``` **Valid OpenAPI V2 Example** ```json { "host": "myprodserver.com", "basePath": "/v2", "schemes": [ "https" ] } ```

Server URLs should not end in forward slashes. This is a best practice for working with web tooling, such as mock servers, code generators, application frameworks, and more). **Invalid Example** ```json lineNumbers { "servers": [ { ... , "url": "https://api.openweathermap.org/data/2.5/" } ] } ``` **Valid Example** ```json lineNumbers { "servers": [ { ... , "url": "https://api.openweathermap.org/data/2.5" } ] } ```

Operations should have at least one "2xx" or "3xx" response defined. **Invalid Example** ```json lineNumbers { "get": { ... , "responses": {}, } } ``` **Valid Example** ```json lineNumbers { "get": { ... , "responses": { "200": { "description": "OK" } }, } } ```

Path parameters must be defined and valid in either the `path-parameters` or the `operation-parameters` object. Likewise, defined `path-parameters` or `operation-parameters` must be used in the `paths` string. **Valid Example** For this path: `/users/{id}/{location}` The following path parameters must be defined. ```json lineNumbers "parameters": [ { "schema": { "type": "string" }, "name": "id", "in": "path", "required": true, "description": "This is the user's ID" }, { "schema": { "type": "string" }, "name": "location", "in": "path", "required": true, "description": "This is the user's location" } ] } }, ```

Operation parameters should be unique and non-repeating: * `name` and `in` must be unique For OAS2: * Operations should not have `in: body` and `in: formData` parameters. * Operations should have only one `in: body` parameter. **Invalid Example** In this example, the query paramater `"name": "last name"` is repeated. ```json lineNumbers { "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "last name", "description": "User's last name" }, { "schema": { "type": "string" }, "in": "query", "name": "last name", "description": "User's last name" } ], } ``` **Valid Example** In this example, query parameters are unique. ```json lineNumbers { "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "first name", "description": "User's first name" }, { "schema": { "type": "string" }, "in": "query", "name": "last name", "description": "User's last name" } ], } ```

All `enum' values should respect the specified type. **Invalid Example** In this example, the `enum` type is `integer`, but the values are strings. ```json lineNumbers { "schema": { "type": "integer", "enum": [ "standard", "metric", "imperial" ] }, ``` **Valid Example** In this example, the `enum` type is `string` and the values are strings. ```json lineNumbers { "schema": { "type": "string", "enum": [ "standard", "metric", "imperial" ] },

This Stoplight core rule validates the structure of OpenAPI v2 specification. This rule should never be disabled.

This Stoplight core rule validates the structure of OpenAPI v3.x specification. This rule should never be disabled.

A potentially shareable component is not being used. This may be expected, but you should review sharable components to avoid duplicate entry.

Every operation in a single document must have a unique `operationID`. **Valid Example** In this example, the `operationId` is `get-users`. This `operationId` must be unique in an API document. ```json lineNumbers { "get": { "summary": "Get users", ... , "operationId": "get-users" } } ```

Operations with an `in: formData` parameter must include a `consumes` property with one of these values: `application/x-www-form-urlencoded` `multipart/form-data` **Valid Example** In this example, the `consumes` property correctly includes the `multipart/form-data` value. ```json lineNumbers { "post":{ "summary":"Uploads a file", "consumes":[ "multipart/form-data" ], "parameters":[ { "name":"name", "in":"formData", "description":"Upload a file", "required":false, "type":"string" } ] } }

Tags defined at the operation level should also be defined at the global level. **Operation-level Example** ```json lineNumbers { "get": { ... , ... , "tags": [ "Users" ], } } ``` **Global-level Example** ```json lineNumbers { "tags": [ { "name": "Users", ... , } ], } ```

Property must not be placed among $ref.

Operation `security` values must match a scheme defined in the global `securityDefinitions` object. Empty `security` values for operations are ignored if authentication is not explicity required or is optional. **Valid Example** For this global security scheme: ```json lineNumbers { "securityDefinitions": { "API Key": { "name": "API Key", "type": "apiKey", "in": "query" } } } ``` This is a valid operation security value: ```json lineNumbers { "operationId": "get-users-userId", "security": [ { "API Key": [] } ] } ``` **Invalid Example** For the same global security scheme, this is an invalid operation security value: ```json lineNumbers { "operationId": "get-users-userId", "security": [ { "oath2": [] } ] } ```

Operation `security` values must match a scheme defined in the global `components.security.Schemes` object. **Valid Example** For this global security scheme: ```json lineNumbers { "components": { "security": [ { "app-id": [] } ] } } ``` `app-id` is a valid operation `security` value: ```json lineNumbers { "get": { "security": [ { "app-id": [] } ] } } ``` **Invalid Example** For the same global security scheme, `oath2` is an invalid operation `security` value: ```json lineNumbers { "get": { "security": [ { "oath2": [] } ] } } ```

All enum values should be unique. **Invalid Example** There are two `json` enum values. ```json lineNumbers { "schema":{ "type":"string", "enum":[ "json", "json", "html" ] } } ``` **Valid Example** All enum values are unique. ```json lineNumbers { "schema":{ "type":"string", "enum":[ "json", "xml", "html" ] } } ```

OpenAPI 2 host `schemes` reflect the transfer protocol of the API. Host schemes must be present and an array with one or more of these values: `http`, `https`, `ws`, or `wss`. **Valid Example** This example shows that host schemes are `http` and `https`. ```json { "schemes":[ "http", "https" ] } ```

Discriminator property must be defined and required

Server URLs must not direct to example.com. This helps ensure URLs are valid before you distribute your API document. **Invalid Example** ```json lineNumbers { "servers": [ { ... , "url": "https://example.com" } ] } ``` **Valid Example** ```json lineNumbers { "servers": [ { ... , "url": "https://api.openweathermap.org/data/2.5" } ] } ```

All `parameter` objects should have a description. **Valid Example** ```json lineNumbers { "parameters": [ { "schema": { "type": "integer" }, ... , ... , "description": "The number of days to include in the response." } } ```

The `anyOf` keyword is not supported in OAS2. Only `allOf` is supported. **Invalid Example** ```json lineNumbers { "schema": { "anyOf": [ { "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" } } }, {} ], } } ``` **Valid Example** ```json lineNumbers { "schema": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" } }, } } ```

The `oneOf` keyword is not supported in OAS2. Only `allOf` is supported. **Invalid Example** ```json lineNumbers { "schema": { "oneOf": [ { "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" } } }, {} ], } } ``` **Valid Example** ```json lineNumbers { "schema": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" } }, } } ```

The `examples` object should include a `value` or `externalValue` field, but cannot include both. **Invalid Example** This example includes both a `value` field and an `externalValue` field. ```json lineNumbers { "examples": { "example-1": { "value": { "id": "string", "name": "string" }, "externalValue": { "id": "string", "name": "string" } } } } ``` **Valid Example** This example includes only a `value` field. ```json lineNumbers { "examples": { "example-1": { "value": { "id": "string", "name": "string" } } } }

Examples must be valid against their defined schema. **Valid Example** The following schema includes the `name` and `petType` properties. ```json lineNumbers { "Pet":{ "type":"object", "properties":{ "name":{ "type":"string" }, "petType":{ "type":"string" } } } } ``` When referenced in a response example, the property names on line 6 and 7 must match those in the schema (`petName` and `petType`). ```json lineNumbers { "responses":{ "200":{ "content":{ "application/json":{ "examples":{ "Pet Example":{ "petName":"Bubbles", "petType":"Dog" } }, "schema":{ "$ref":"#/definitions/Pet" } } } } } } ```

Examples must be valid against their defined schema. **Valid Example** The following schema includes the `name` and `petType` properties. ```json lineNumbers { "Pet":{ "type":"object", "properties":{ "name":{ "type":"string" }, "petType":{ "type":"string" } } } } ``` When referenced in a response example, the property names on line 6 and 7 must match those in the schema (`petName` and `petType`). ```json lineNumbers { "responses":{ "200":{ "content":{ "application/json":{ "examples":{ "Pet Example":{ "petName":"Bubbles", "petType":"Dog" } }, "schema":{ "$ref":"#/definitions/Pet" } } } } } } ```

Examples must be valid against their defined schema. Common reasons you may see errors if: * The value used for property examples is not the same type indicated in the schema (string vs. integer, for example). * Examples contain properties not included in the schema. **Valid Example** The following schema indicates that the `id` property is a `string` type. ```json lineNumbers "User":{ "title":"User", "type":"object", "properties":{ "id":{ "type":"string" } } } ``` When the example is referenced in a response, the `id` property must be `string`. ```json lineNumbers { "responses":{ "200":{ "description":"User Found", "schema":{ "$ref":"#/definitions/User" }, "examples":{ "Get User Alice Smith":{ "id": "smith, alice", } } }, ```

The following schema includes the `name` and `petType` properties. **Valid Example** ```json lineNumbers { "Pet":{ "type":"object", "properties":{ "name":{ "type":"string" }, "petType":{ "type":"string" } } } } ``` When referenced in a response example, the property names on line 6 and 7 must match those in the schema (`petName` and `petType`). ```json lineNumbers { "responses":{ "200":{ "content":{ "application/json":{ "examples":{ "Pet Example":{ "petName":"Bubbles", "petType":"Dog" } }, "schema":{ "$ref":"#/definitions/Pet" } } } } } } ```

This rule ensures that server variables defined in OpenAPI Specification 3 (OAS3) and 3.1 are valid, not unused, and result in a valid URL. Properly defining and using server variables is crucial for the accurate representation of API endpoints and preventing potential misconfigurations or security issues. **Recommended**: Yes **Bad Examples** 1. **Missing definition for a URL variable**: ```yaml servers: - url: "https://api.{region}.example.com/v1" variables: version: default: "v1" ``` In this example, the variable **`{region}`** in the URL is not defined within the **`variables`** object. 2. **Unused URL variable:** ```yaml servers: - url: "https://api.example.com/v1" variables: region: default: "us-west" ``` Here, the variable **`region`** is defined but not used in the server URL. 3. **Invalid default value for an allowed value variable**: ```yaml servers: - url: "https://api.{region}.example.com/v1" variables: region: default: "us-south" enum: - "us-west" - "us-east" ``` The default value 'us-south' isn't one of the allowed values in the **`enum`**. 4. **Invalid resultant URL**: ```yaml servers: - url: "https://api.example.com:{port}/v1" variables: port: default: "8o80" ``` Substituting the default value of **`{port}`** results in an invalid URL. **Good Example** ```yaml servers: - url: "https://api.{region}.example.com/{version}" variables: region: default: "us-west" enum: - "us-west" - "us-east" version: default: "v1" ``` In this example, both **`{region}`** and **`{version}`** variables are properly defined and used in the server URL. Also, the default value for **`region`** is within the allowed values.

Schemas with `type: array`, require a sibling `items` field. **Recommended:** Yes **Good Example** ```yaml TheGoodModel: type: object properties: favoriteColorSets: type: array items: type: array items: {} ``` **Bad Example** ```yaml TheBadModel: type: object properties: favoriteColorSets: type: array items: type: array ```