AEP-4 OAS Docs Improvement

[thegagne]

While reading AEP-4, I noticed that the Guidance and Examples sections describe general resource type naming and annotation rules, but they don’t seem directly relevant to OpenAPI (OAS) specifically.

Later in the document, there is a dedicated OpenAPI 3.0 tab/section that contains the OAS-specific guidance (e.g., #components/schemas, x-aep-resource extension, patterns, etc.).

This can cause some confusion:

• A reader looking only at the Guidance + Examples might think they must apply those directly in OAS schemas.
• The OAS-specific section already provides a clearer, scoped explanation, so it would make sense to separate general guidance from OAS-specific rules more explicitly.

Proposal:

• Update AEP-4 to make it clear which parts apply generally across APIs (Guidance, Examples) vs. which apply specifically to OAS definitions.
• Possibly separate the guidance and examples into separate tabs for OAS and Protobuf.

[toumorokoshi]

A reader looking only at the Guidance + Examples might think they must apply those directly in OAS schemas.

I think this is an oversight actually - since the protobuf has a specified field to put the resource type (aptly named type), I think we need to specify the same for OAS:

x-aep-resource:
    type: user.example.com/user-event

The OAS-specific section already provides a clearer, scoped explanation, so it would make sense to separate general guidance from OAS-specific rules more explicitly.

I'm not sure if I understand how this distinction would be helpful to someone - the general guidance would apply to all AEP APIs, which include OAS. If we do make updates to the OAS guidance to include the resource type (as proposed above), then the guidance above is no longer general.

But I think arguably, adding this must at the top is kind of confusing:

APIs must define a resource type for each resource in the API, according to the following pattern: {API Name}/{Type Name}. The type name:
     must Only contain ASCII alphanumeric characters.
     must Start with a lowercase letter.
     must Be of the singular form of the noun.
     must Use kebab case.

primarily because the usage of type isn't actionable until the examples. Maybe a better phrasing is to describe what a resource type is and how it's described, then put a must in each example to require it's existence in the annotation?