Skip to content

Commit e472cf4

Browse files
feat(0004): clarify resource names requirements (#397)
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 --------- Co-authored-by: Mike Kistler <[email protected]>
1 parent 6ddb33e commit e472cf4

File tree

1 file changed

+6
-23
lines changed

1 file changed

+6
-23
lines changed

aep/general/0004/aep.md.j2

Lines changed: 6 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ create, retrieve, and manipulate. APIs are allowed to name their resource types
55
as they see fit, and are only required to ensure uniqueness within that API.
66
This means that it is possible (and often desirable) for different APIs to use
77
the same type name. For example, a Memcache and Redis API would both want to
8-
use `Instance` as a type name.
8+
use `instance` as a type name.
99

1010
When mapping the relationships between APIs and their resources, however, it
1111
becomes important to have a single, globally-unique type name. Additionally,
@@ -24,7 +24,7 @@ indicated by it's namespacing within the API name.
2424

2525
The type name:
2626

27-
- **must** only contain ASCII alphanumeric characters.
27+
- **must** only contain ASCII alphanumeric characters and dashes (`-`).
2828
- **must** start with a lowercase letter.
2929
- **must** be of the singular form of the resource.
3030
- **must** use kebab case.
@@ -71,33 +71,16 @@ For OpenAPI 3.0, Resources must be defined in `#components/schemas` and use the
7171
[`x-aep-resource`](https://aep.dev/json-schema/extensions/x-aep-resource.json)
7272
extension:
7373

74-
```json
75-
{
76-
"components": {
77-
"schemas": {
78-
"UserEvent": {
79-
"type": "object",
80-
"x-aep-resource": {
81-
"type": "user.example.com/user-event",
82-
"singular": "user-event",
83-
"plural": "user-events",
84-
"patterns": [
85-
"projects/{project_id}/user-events/{user_event_id}",
86-
"folder/{folder_id}/user-events/{user_event_id}",
87-
"users/{user_id}/events/{user_event_id}"
88-
]
89-
}
90-
}
91-
}
92-
}
93-
}
94-
```
74+
{% sample '../example.oas.yaml', '$.components.schemas.book.x-aep-resource' %}
9575

9676
{% endtabs %}
9777

9878
- The `type` field **must** be the resource type `{API Name}/{Type Name}`
9979
- The `singular` field **must** be the kebab-case singular type name.
10080
- The `plural` field **must** be the kebab-case plural of the singular.
81+
- The `parent` field **must** be a list of all type names of parents of the
82+
resource.
83+
- If the resource has no parents, this field may be omitted.
10184

10285
The `pattern` field **must** match the `pattern` rule in the following grammar,
10386
expressed as [EBNF][EBNF]:

0 commit comments

Comments
 (0)