@modernizehs/redocly-guidelines

v0.1.5

Published

5 months ago

A custom Redocly CLI plugin representing Modernize Home Services custom OpenAPI linting rules.

0High
0Medium
0Low

@modernizehs/redocly-guidelines

A custom Redocly CLI plugin that enforces Modernize Home Services API design guidelines and best practices for OpenAPI specifications.

Overview

This package provides custom linting rules for Redocly CLI to ensure OpenAPI specifications follow Modernize Home Services API standards. It helps maintain consistency across all API definitions by validating naming conventions, versioning, and URL structures.

Installation

Install the package along with Redocly CLI:

npm install --save-dev @modernizehs/redocly-guidelines @redocly/cli

Or with Yarn:

yarn add --dev @modernizehs/redocly-guidelines @redocly/cli

Configuration

Create a .redocly.yaml configuration file in your project root:

extends:
  - recommended
  # Use the dry-run ruleset (all rules as warnings)
  - modernize-guidelines/dry-run
  # Or use strict mode (all rules as errors)
  - modernize-guidelines/strict

plugins:
  - '@modernizehs/redocly-guidelines'

rules:
  # Or configure individual rules

  # Core rules
  # modernize-guidelines/semantic-versioning: error
  # modernize-guidelines/camelcase-path-segments: error
  # modernize-guidelines/camelcase-query-parameters: warn
  # modernize-guidelines/hostname-conventions: error

  # Data format rules
  # modernize-guidelines/standard-data-formats: error
  # modernize-guidelines/binary-data-encoding: error

  # JSON payload rules
  # modernize-guidelines/property-naming: error
  # modernize-guidelines/top-level-objects: error
  # modernize-guidelines/enum-values: error

  # Resource naming rules
  # modernize-guidelines/resource-naming: error
  # modernize-guidelines/url-friendly-identifiers: error
  # modernize-guidelines/sub-resource-levels: warn

Available Rules

Core Rules

`semantic-versioning`

Ensures the API version follows semantic versioning format (e.g., 1.0.0, 2.1.3).

`camelcase-path-segments`

Validates that all path segments use camelCase naming convention.

✅ Good: /api/v1/userProfiles/{userId}
❌ Bad: /api/v1/user_profiles/{user_id}

`camelcase-query-parameters`

Ensures query parameters follow camelCase naming convention.

✅ Good: ?firstName=John&lastName=Doe
❌ Bad: ?first_name=John&last_name=Doe

`hostname-conventions`

Validates that API server hostnames follow organizational naming standards.

Data Format Rules

`standard-data-formats`

Ensures that data types use standard formats for consistency and clarity.

Requirements:

Number and integer types must specify a format (int32, int64, bigint, float, double, decimal)
Date/time strings must use standard formats (date, date-time, time, duration, period)
String formats should be from the standard list (email, uri, uuid, etc.)

Examples:

# ✅ Good
properties:
  age:
    type: integer
    format: int32
  price:
    type: number
    format: decimal
  birthDate:
    type: string
    format: date
  email:
    type: string
    format: email

# ❌ Bad
properties:
  age:
    type: integer  # Missing format
  price:
    type: number   # Missing format
  birthDate:
    type: string   # Missing date format

`binary-data-encoding`

Validates that binary data uses proper encoding formats.

Requirements:

Binary data should use string type with binary or byte format
Properties suggesting binary content should specify proper encoding

Examples:

# ✅ Good
properties:
  profileImage:
    type: string
    format: binary
  fileData:
    type: string
    format: byte

# ❌ Bad
properties:
  profileImage:
    type: string  # Missing binary format
  fileData:
    type: string  # Missing byte format

JSON Payload Rules

`property-naming`

Ensures all JSON property names use camelCase convention.

Examples:

# ✅ Good
properties:
  firstName:
    type: string
  emailAddress:
    type: string
  phoneNumber:
    type: string

# ❌ Bad
properties:
  first_name:     # snake_case
    type: string
  email_address:  # snake_case
    type: string

`top-level-objects`

Requires response schemas to use objects as top-level structures instead of arrays.

Examples:

# ✅ Good
responses:
  '200':
    content:
      application/json:
        schema:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/User'
            total:
              type: integer

# ❌ Bad
responses:
  '200':
    content:
      application/json:
        schema:
          type: array  # Array as top-level structure
          items:
            $ref: '#/components/schemas/User'

`enum-values`

Ensures enum values use UPPER_SNAKE_CASE format.

Examples:

# ✅ Good
properties:
  status:
    type: string
    enum:
      - ACTIVE
      - INACTIVE
      - PENDING

# ❌ Bad
properties:
  status:
    type: string
    enum:
      - active    # lowercase
      - inactive  # lowercase
      - pending   # lowercase

Resource Naming Rules

`resource-naming`

Validates RESTful resource naming conventions.

Requirements:

Path segments should not contain verbs
Resource names should be pluralized
Warns about /api base paths

Examples:

# ✅ Good
paths:
  /users:           # Plural noun
    get: ...
  /users/{userId}/orders:  # Nested resources
    get: ...

# ❌ Bad
paths:
  /getUsers:        # Contains verb
    get: ...
  /user:            # Singular noun
    get: ...
  /api/users:       # /api base path (warning)
    get: ...

`url-friendly-identifiers`

Ensures resource identifiers use URL-friendly characters and avoid auto-incrementing patterns.

Requirements:

Identifiers should use alphanumeric characters, hyphens, or underscores
Avoid auto-incrementing numeric patterns in examples

Examples:

# ✅ Good
parameters:
  - name: userId
    schema:
      type: string
      format: uuid
      example: "550e8400-e29b-41d4-a716-446655440000"

# ❌ Bad
parameters:
  - name: userId
    schema:
      type: string
      example: "12345"  # Auto-incrementing pattern

`sub-resource-levels`

Warns when sub-resource nesting exceeds 2 levels to avoid complexity.

Examples:

# ✅ Good
paths:
  /users/{userId}/orders:           # 2 levels: users -> orders
    get: ...
  /users/{userId}/orders/{orderId}: # 2 levels with IDs
    get: ...

# ⚠️ Warning
paths:
  /users/{userId}/orders/{orderId}/items/{itemId}/details:  # 4 levels
    get: ...

Rulesets

Strict Mode

Use modernize-guidelines/strict to enforce all rules as errors:

extends:
  - modernize-guidelines/strict

Dry-Run Mode

Use modernize-guidelines/dry-run to enable all rules as warnings (useful during migration):

extends:
  - modernize-guidelines/dry-run

Usage

Once configured, run Redocly CLI to lint your OpenAPI specification:

# Lint a single file
npx redocly lint openapi.yaml

# Lint multiple files
npx redocly lint api/**/*.yaml

# Show only errors (no warnings)
npx redocly lint openapi.yaml --severity=error

Example OpenAPI Specification

Here's an example of a compliant OpenAPI specification:

openapi: 3.0.0
info:
  title: User API
  version: 1.2.3  # Follows semantic versioning
servers:
  - url: https://example.modernizehs.com/v1  # Compliant hostname
paths:
  /users:  # Plural resource name
    get:
      parameters:
        - name: pageSize  # camelCase query parameter
          in: query
          schema:
            type: integer
            format: int32  # Required format for integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersResponse'

  /users/{userId}:  # camelCase path segments
    get:
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid  # URL-friendly identifier
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'

components:
  schemas:
    UsersResponse:
      type: object  # Object as top-level structure
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'

    UserResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/User'

    User:
      type: object
      properties:
        userId:
          type: string
          format: uuid
        userName:  # camelCase property name
          type: string
        emailAddress:  # camelCase property name
          type: string
          format: email  # Standard string format
        age:
          type: integer
          format: int32  # Required format for integer
        birthDate:
          type: string
          format: date  # Standard date format
        profileImage:
          type: string
          format: binary  # Proper binary data encoding
        status:
          type: string
          enum:
            - ACTIVE    # UPPER_SNAKE_CASE enum values
            - INACTIVE
            - PENDING

    Pagination:
      type: object
      properties:
        currentPage:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32

Development

Prerequisites

Node.js >= 20.19.0 or >= 22.12.0
npm >= 10

Setup

# Install dependencies
npm install

# Run tests
npm test

# Run linting
npm run eslint

# Check formatting
npm run prettier:check

# Build the package
npm run compile

Project Structure

src/
├── rules/              # Custom linting rules
│   ├── meta/          # Metadata-related rules (versioning, hostname)
│   ├── urls/          # URL and path-related rules
│   ├── data-formats/  # Data format validation rules
│   ├── json/          # JSON payload convention rules
│   └── resources/     # Resource naming and structure rules
├── config/            # Predefined rulesets
│   ├── dry-run.ts     # Warning-level ruleset
│   └── strict.ts      # Error-level ruleset
└── index.ts           # Main plugin export

Publishing New Versions

This package uses automated publishing via CircleCI when a new version tag is pushed.

Steps to Publish

Update the version in package.json (optional - the tag will override this):
```
npm version patch  # or minor/major
```

Create and push a version tag:

# For a patch release (1.0.0 -> 1.0.1)
git tag v1.0.1
git push origin v1.0.1

# For a minor release (1.0.0 -> 1.1.0)
git tag v1.1.0
git push origin v1.1.0

# For a major release (1.0.0 -> 2.0.0)
git tag v2.0.0
git push origin v2.0.0

CircleCI will automatically:
- Run all validation checks (prettier, lint, typecheck, tests)
- Build the TypeScript code
- Publish to npm registry

Version Tag Format

Version tags must follow semantic versioning:

Format: v<major>.<minor>.<patch> or <major>.<minor>.<patch>
Examples: v1.2.3, 2.0.0, v1.0.0-beta.1

Manual Publishing (if needed)

If you need to publish manually:

# Build the package
npm run compile

# Publish to npm
npm publish --access public

Note: Ensure you have the necessary npm publishing permissions and are logged in (npm login).

Changelog

v0.2.0 (Latest)

New Rules Added:

Data Format Rules:
- standard-data-formats: Validates number/integer formats and standard string formats
- binary-data-encoding: Ensures proper binary data encoding
JSON Payload Rules:
- property-naming: Enforces camelCase property names
- top-level-objects: Requires objects as top-level response structures
- enum-values: Validates UPPER_SNAKE_CASE enum values
Resource Naming Rules:
- resource-naming: Validates RESTful resource naming (no verbs, pluralization)
- url-friendly-identifiers: Ensures URL-friendly resource identifiers
- sub-resource-levels: Warns about excessive nesting levels

Improvements:

Enhanced utility functions for validation
Comprehensive test coverage for all rules
Updated documentation with examples
Better error messages with guideline links

v0.1.x

Initial release with core rules:
- semantic-versioning
- camelcase-path-segments
- camelcase-query-parameters
- hostname-conventions

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/new-rule)
Make your changes
Ensure all tests pass (npm test)
Ensure code follows style guidelines (npm run prettier:check && npm run eslint)
Commit your changes
Push to your fork
Create a Pull Request

Writing New Rules

To add a new rule:

Create a new file in src/rules/ under the appropriate category
Implement the rule following the Redocly rule structure
Add tests in the appropriate __tests__ directory
Export the rule in src/index.ts
Update the rulesets in src/config/ if needed

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@modernizehs/redocly-guidelines

Overview

Installation

Configuration

Available Rules

Core Rules

semantic-versioning

camelcase-path-segments

camelcase-query-parameters

hostname-conventions

Data Format Rules

standard-data-formats

binary-data-encoding

JSON Payload Rules

property-naming

top-level-objects

enum-values

Resource Naming Rules

resource-naming

url-friendly-identifiers

sub-resource-levels

Rulesets

Strict Mode

Dry-Run Mode

Usage

Example OpenAPI Specification

Development

Prerequisites

Setup

Project Structure

Publishing New Versions

Steps to Publish

Version Tag Format

Manual Publishing (if needed)

Changelog

v0.2.0 (Latest)

v0.1.x

Contributing

Writing New Rules

`semantic-versioning`

`camelcase-path-segments`

`camelcase-query-parameters`

`hostname-conventions`

`standard-data-formats`

`binary-data-encoding`

`property-naming`

`top-level-objects`

`enum-values`

`resource-naming`

`url-friendly-identifiers`

`sub-resource-levels`