AEP-0122 Linter Rules

Rules for AEP-122- Resource Paths

# Rules for AEP-122: Resource Paths

The aep-122 rules check that resources follow the resource path conventions defined in AEP-122, including proper path field definitions, collection identifier formatting, and field naming conventions.

Known Limitations

Path Separator Runtime Validation: AEP-122 requires resource paths use / separator (spec line 34). This is a runtime requirement that cannot be enforced via OpenAPI schema validation. The official AEP linter for protobuf enforces this through the google.api.resource.pattern annotation; OpenAPI has no equivalent mechanism. Ensure your API implementation generates correct path values with forward slash separators.

aep-122-resource-path-field

Rule: Resources must have a ‘path’ field of type string.

This rule enforces that all AEP resources (schemas with x-aep-resource extension) must include a path property of type string.

Details

This rule looks for schemas marked with the x-aep-resource extension and complains if the path property is missing or is not of type string.

Examples

Incorrect code for this rule:

components:
  schemas:
    Book:
      x-aep-resource: true
      type: object
      properties:
        name:
          type: string
        # Missing 'path' field

Correct code for this rule:

components:
  schemas:
    Book:
      x-aep-resource: true
      type: object
      properties:
        path:
          type: string
          description: 'The resource path of the book'
        name:
          type: string

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.yaml#/components/schemas/Book'
    rules:
      aep-122-resource-path-field: 'off'

aep-122-collection-identifier-format

Rule: Collection identifiers must begin with a lowercase letter and contain only lowercase letters, numbers, and hyphens.

This rule enforces that collection identifiers match the pattern /[a-z][a-z0-9-]*/.

Details

This rule examines all path patterns and complains if collection identifiers don’t start with a lowercase letter or contain invalid characters.

Examples

Incorrect code for this rule:

paths:
  # Starts with number - incorrect
  '/1books/{book}':
    get:
      operationId: GetBook

  # Starts with hyphen - incorrect
  '/-books/{book}':
    get:
      operationId: GetBook

  # Contains uppercase - incorrect
  '/Books/{book}':
    get:
      operationId: GetBook

Correct code for this rule:

paths:
  '/books/{book}':
    get:
      operationId: GetBook

  '/books2/{book}':
    get:
      operationId: GetBook

  '/electronic-books/{book}':
    get:
      operationId: GetElectronicBook

Disabling

overrides:
  - files:
      - 'openapi.yaml#/paths/~1Books~1{book}'
    rules:
      aep-122-collection-identifier-format: 'off'

aep-122-parent-field-type

Rule: Parent fields in request parameters must be of type string.

This rule enforces that parameters named parent must be of type string.

Details

This rule looks for parameters named parent in path operations and complains if they are not of type string.

Examples

Incorrect code for this rule:

paths:
  '/books':
    get:
      operationId: ListBooks
      parameters:
        - name: parent
          in: query
          schema:
            type: integer # Incorrect - must be string

paths:
  '/books':
    get:
      operationId: ListBooks
      parameters:
        - name: parent
          in: query
          schema:
            # Missing 'type' field - must specify type: string
            description: 'The parent resource'

Correct code for this rule:

paths:
  '/books':
    get:
      operationId: ListBooks
      parameters:
        - name: parent
          in: query
          schema:
            type: string
          description: 'The parent resource. Format: publishers/{publisher}'

Disabling

overrides:
  - files:
      - 'openapi.yaml#/paths/~1books/get/parameters/0'
    rules:
      aep-122-parent-field-type: 'off'

aep-122-resource-id-type

Rule: All resource ID fields must be of type string.

This rule enforces that fields ending in _id or named id must be of type string.

Details

This rule looks for properties in AEP resources (schemas with x-aep-resource extension) that are named id or end with _id, and complains if they are not of type string.

Examples

Incorrect code for this rule:

components:
  schemas:
    Book:
      x-aep-resource: true
      type: object
      properties:
        path:
          type: string
        id:
          type: integer # Incorrect - must be string
        publisher_id:
          type: number # Incorrect - must be string

Correct code for this rule:

components:
  schemas:
    Book:
      x-aep-resource: true
      type: object
      properties:
        path:
          type: string
        id:
          type: string
        publisher_id:
          type: string
        author_id:
          type: string

Disabling

overrides:
  - files:
      - 'openapi.yaml#/components/schemas/Book/properties/id'
    rules:
      aep-122-resource-id-type: 'off'

aep-122-no-path-suffix

Rule: Field names should not use the ‘_path’ suffix unless necessary for disambiguation.

This rule warns when field names in AEP resources use the _path suffix, as AEP-122 recommends using the resource name directly (e.g., book instead of book_path).

Details

This rule examines property names in schemas marked with x-aep-resource and warns if they end with _path. The _path suffix should only be used when necessary for disambiguation (e.g., file_path or crypto_key_path). Non-AEP resources are not checked by this rule.

Examples

Incorrect code for this rule:

components:
  schemas:
    Book:
      x-aep-resource: true
      type: object
      properties:
        path:
          type: string
        author_path: # Should be 'author'
          type: string
        publisher_path: # Should be 'publisher'
          type: string
      required:
        - path

Correct code for this rule:

components:
  schemas:
    Book:
      x-aep-resource: true
      type: object
      properties:
        path:
          type: string
        author:
          type: string
          description: 'The author resource path'
        publisher:
          type: string
          description: 'The publisher resource path'
      required:
        - path
    # Non-AEP resources can use _path suffix without warnings
    FileInfo:
      type: object
      properties:
        file_path:
          type: string
        directory_path:
          type: string

Disabling

overrides:
  - files:
      - 'openapi.yaml#/components/schemas/Book/properties/author_path'
    rules:
      aep-122-no-path-suffix: 'off'

aep-122-no-self-links

Rule: Resources must not have a ‘self_link’ field.

This rule enforces that resource schemas do not contain a self_link field, as mandated in AEP-122. Resources should use the path field for resource identification instead.

Details

This rule looks for schemas marked with the x-aep-resource extension and complains if they contain a property named self_link. According to AEP-122, resources must not expose tuples, self-links, or other forms of resource identification beyond the canonical path field.

Examples

Incorrect code for this rule:

components:
  schemas:
    Book:
      x-aep-resource: true
      type: object
      properties:
        path:
          type: string
          description: 'The resource path of the book'
        name:
          type: string
        self_link: # Incorrect - resources must not have self_link
          type: string
          description: 'Self link to the resource'

Correct code for this rule:

components:
  schemas:
    Book:
      x-aep-resource: true
      type: object
      properties:
        path:
          type: string
          description: 'The resource path of the book'
        name:
          type: string
        # No self_link field - use path instead

Disabling

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

overrides:
  - files:
      - 'openapi.yaml#/components/schemas/Book/properties/self_link'
    rules:
      aep-122-no-self-links: 'off'