AEP-0004 Linter Rules

Rules for AEP-4: Resource Types

The aep-4 rules validate the structure of the x-aep-resource extension used to define resource types in OpenAPI specifications.

aep-0004-x-aep-resource-structure

aep-0004-x-aep-resource-structure

Rule: x-aep-resource must have correct structure with required fields (singular, plural, patterns)

This rule enforces that all x-aep-resource extensions have the required fields and proper format, as mandated in AEP-4.

Details

This rule looks at all schemas in components.schemas that have an x-aep-resource extension defined as an object (not a boolean). It validates that:

Required fields:

• singular - Must be in kebab-case (e.g., book, book-edition)
• plural - Must be in kebab-case (e.g., books, book-editions)
• patterns - Array of path patterns for the resource (minimum 1 pattern). Each pattern must follow the format: collection/{identifier} with optional nested resources

Optional fields:

• type - Resource type in format {API Name}/{Type Name} (e.g., library.example.com/book)
• parents - Array of parent resource identifiers
• singleton - Boolean indicating if resource is a singleton

Backward compatibility: The rule allows x-aep-resource: true (boolean marker) for backward compatibility with older specifications.

Examples

Incorrect code for this rule:

components:
  schemas:
    Book:
      type: object
      x-aep-resource:
        # Missing 'plural' field (required)
        singular: book

    Publisher:
      type: object
      x-aep-resource:
        # Missing 'singular' field (required)
        plural: publishers

    Author:
      type: object
      x-aep-resource:
        singular: Author # Should be lowercase kebab-case
        plural: authors
        patterns:
          - 'authors/{author_id}'

    Magazine:
      type: object
      x-aep-resource:
        singular: magazine
        plural: Magazines # Should be lowercase kebab-case
        patterns:
          - 'magazines/{magazine_id}'

    Library:
      type: object
      x-aep-resource:
        singular: library
        plural: libraries
        # Missing 'patterns' field (required)

    Article:
      type: object
      x-aep-resource:
        singular: article
        plural: articles
        patterns:
          - 'invalid-pattern' # Invalid - must include path parameter
          - 'Articles/{article_id}' # Invalid - should be lowercase

Correct code for this rule:

components:
  schemas:
    Book:
      type: object
      x-aep-resource:
        singular: book
        plural: books
        patterns:
          - 'books/{book_id}'

    BookEdition:
      type: object
      x-aep-resource:
        singular: book-edition
        plural: book-editions
        patterns:
          - 'publishers/{publisher_id}/books/{book_id}/editions/{edition_id}'
        parents:
          - book

    Publisher:
      type: object
      x-aep-resource:
        singular: publisher
        plural: publishers
        patterns:
          - 'publishers/{publisher_id}'

    # Backward compatibility: Boolean marker still works
    LegacyResource:
      type: object
      x-aep-resource: true

Disabling

If you need to violate this rule for a specific schema, add an “override” to the Spectral rule file for the specific file and fragment.

overrides:
  - files:
      - 'openapi.json#/components/schemas/Book/x-aep-resource'
    rules:
      aep-0004-x-aep-resource-structure: 'off'

If you need to violate this rule for an entire file, add an “override” to the Spectral rule file for the specific file without a fragment.

overrides:
  - files:
      - 'openapi.json'
    rules:
      aep-0004-x-aep-resource-structure: 'off'

Known Limitations

Known Limitations

Official AEP-4 Linter Rules: All 5 official AEP-4 linter rules are protobuf-specific and rely on google.api.resource annotations. This OpenAPI rule validates the equivalent x-aep-resource extension structure as defined in the AEP-4 specification.

Pattern Validation: This rule validates that the patterns field is required and that each pattern follows the correct format: collection/{identifier} with optional nested resources (e.g., publishers/{publisher_id}/books/{book_id}). Patterns must start with a lowercase letter, use kebab-case for collection names, and include path parameters in braces.

Pattern Uniqueness: This rule does not validate that patterns do not overlap in the set of resource paths they can match, as required in AEP-4 spec line 117. This is a runtime validation concern.