-
Notifications
You must be signed in to change notification settings - Fork 0
Description
Type definitions
Composite data types
Composite data types (user_detail, status, ruleset, tag) should be linked in the "Type" column, rather than the description. This will have the benefit of being able to quickly identify a non-primitive type at a glance as well as easier access (ie. not having to find it either in the description or the index)
Example:
| Name | Type | Description |
|---|---|---|
| id | integer | lorem |
| name | string | ipsum |
| status | status | dalor, status sid amet |
The following type notation is mostly typescript syntax:
Nullable types
Fields which are allowed to be undefined or null should be described as type?. The only occurrence of this I could find is status.latest_update. Composite types should not include the ? as a part of the link to its definition.
| Name | Type | Description |
|---|---|---|
| latest_update | string? | The time on ruleset's latest update in JSON time format. |
Default values
Fields which have an ambiguous default value, such as ones which could be null or "" by default, or even not expected to be empty in the first place should be described as type | value, for example string | "" or integer | -1. The pipe symbol means "or".
Examples of this are: user_detail.user.email and profile_page.osu_username which have '(Can be blank and if it's blank this field will be "", not null)' in the description.
| Name | Type | Description |
|---|---|---|
| string | "" | Email of request user. |
Lists
Lists of a given type should be described as type[], for example string[]. Composite types should not include the [] as a part of the link to its definition. If a field can be null, it would be type[]?; If the list can have null entries, it should be type?[]; If both type?[]?.
You can use (type | value)[] to indicate the items of the list can be blank, but not null. You should not use type[] | [].
Examples of such fields are profile_page.tags and profile_page.created_rulesets.
| Name | Type | Description |
|---|---|---|
| tags | tag[] | List of tag that user has. |
| created_rulesets | ruleset[] | List of ruleset that user created. |
Dates and URLs
Date fields should not be string, but Date and URLs should be URL and not string.
| Name | Type | Description |
|---|---|---|
| cover | URL | URL of the user's cover picture in website's default theme (Dark theme). |
| created_at | Date | The UTC time that the wiki page has create in JSON time format. |
Nested data
user_detail uses - username and - email. I think it would be better if the amount of dashes matched the length of the parent:
| Name | Type | Description |
|---|---|---|
| id | integer | The ID of the user in Rūrusetto database. |
| user | ||
| ---- username | string | Username of request user. |
| string | "" | Email of request user. | |
| image | URL | The URL of the user's profile image. |
Header
A short summary of these definitions should be included somewhere above all of its usages, I propose right next to the "Timezones" section, or even replacing it. This header could look like this:
Type notation
type?means the value can benullorundefined. A lack of the?means it will never benullorundefined.type | value(for examplestring | "") indicates that the field is allowed to have a blank value such as the RHS of the pipe. A lack of the| valuemeans the field will always have meaningful data which is not blank.type[]means that the field is a list/array oftype. The| valuenotation does not apply to this - lists are allowed to be empty ([]) by default.- The type
Dateis a JSON date string in UTC.- The type
URLis a string.