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

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

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)

Optional fields:

patterns - Array of path patterns for the resource
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

    Magazine:
      type: object
      x-aep-resource:
        singular: magazine
        plural: Magazines # Should be lowercase kebab-case

Correct code for this rule:

components:
  schemas:
    Book:
      type: object
      x-aep-resource:
        singular: book
        plural: books

    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

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 the presence and type of the patterns field but does not validate the pattern format (e.g., alternating collection/id segments). Pattern format validation may be added in a future release.

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.