From c1ea26078e2ace4aee372f3ed38482eed7d70ead Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Thu, 11 Dec 2025 21:32:54 -0800 Subject: [PATCH 1/3] feat(0004): clarify resource names requirements A requirement stated that only alphanumerics were allowed, conflicting with a line later that also allowed kebab-cased dashes. Clarifying that dashes are indeed allowed. fixes #396 --- aep/general/0004/aep.md.j2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aep/general/0004/aep.md.j2 b/aep/general/0004/aep.md.j2 index 54c7b369..12341efe 100644 --- a/aep/general/0004/aep.md.j2 +++ b/aep/general/0004/aep.md.j2 @@ -24,7 +24,7 @@ indicated by it's namespacing within the API name. The type name: -- **must** only contain ASCII alphanumeric characters. +- **must** only contain ASCII alphanumeric characters and dashes (`-`). - **must** start with a lowercase letter. - **must** be of the singular form of the resource. - **must** use kebab case. From b6d8fb77037223ffbcfc76134a7f0e189b017321 Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Fri, 12 Dec 2025 08:42:45 -0800 Subject: [PATCH 2/3] Update aep/general/0004/aep.md.j2 Co-authored-by: Mike Kistler --- aep/general/0004/aep.md.j2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aep/general/0004/aep.md.j2 b/aep/general/0004/aep.md.j2 index 12341efe..1365b453 100644 --- a/aep/general/0004/aep.md.j2 +++ b/aep/general/0004/aep.md.j2 @@ -5,7 +5,7 @@ create, retrieve, and manipulate. APIs are allowed to name their resource types as they see fit, and are only required to ensure uniqueness within that API. This means that it is possible (and often desirable) for different APIs to use the same type name. For example, a Memcache and Redis API would both want to -use `Instance` as a type name. +use `instance` as a type name. When mapping the relationships between APIs and their resources, however, it becomes important to have a single, globally-unique type name. Additionally, From 2922d1176ad11f6a0c20f7b46e883c3f925191d8 Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Fri, 12 Dec 2025 08:50:59 -0800 Subject: [PATCH 3/3] address feedback --- aep/general/0004/aep.md.j2 | 25 ++++--------------------- 1 file changed, 4 insertions(+), 21 deletions(-) diff --git a/aep/general/0004/aep.md.j2 b/aep/general/0004/aep.md.j2 index 1365b453..87c9ef39 100644 --- a/aep/general/0004/aep.md.j2 +++ b/aep/general/0004/aep.md.j2 @@ -71,33 +71,16 @@ For OpenAPI 3.0, Resources must be defined in `#components/schemas` and use the [`x-aep-resource`](https://aep.dev/json-schema/extensions/x-aep-resource.json) extension: -```json -{ - "components": { - "schemas": { - "UserEvent": { - "type": "object", - "x-aep-resource": { - "type": "user.example.com/user-event", - "singular": "user-event", - "plural": "user-events", - "patterns": [ - "projects/{project_id}/user-events/{user_event_id}", - "folder/{folder_id}/user-events/{user_event_id}", - "users/{user_id}/events/{user_event_id}" - ] - } - } - } - } -} -``` +{% sample '../example.oas.yaml', '$.components.schemas.book.x-aep-resource' %} {% endtabs %} - The `type` field **must** be the resource type `{API Name}/{Type Name}` - The `singular` field **must** be the kebab-case singular type name. - The `plural` field **must** be the kebab-case plural of the singular. +- The `parent` field **must** be a list of all type names of parents of the + resource. + - If the resource has no parents, this field may be omitted. The `pattern` field **must** match the `pattern` rule in the following grammar, expressed as [EBNF][EBNF]: