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 |
| email |
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. |
| ---- email |
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 be null or undefined. A lack of the ? means it will never be null or undefined.
type | value (for example string | "") indicates that the field is allowed to have a blank value such as the RHS of the pipe. A lack of the | value means the field will always have meaningful data which is not blank.
type[] means that the field is a list/array of type. The | value notation does not apply to this - lists are allowed to be empty ([]) by default.
- The type
Date is a JSON date string in UTC.
- The type
URL is a string.
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:
The following type notation is mostly typescript syntax:
Nullable types
Fields which are allowed to be
undefinedornullshould be described astype?. The only occurrence of this I could find isstatus.latest_update. Composite types should not include the?as a part of the link to its definition.Default values
Fields which have an ambiguous default value, such as ones which could be
nullor""by default, or even not expected to be empty in the first place should be described astype | value, for examplestring | ""orinteger | -1. The pipe symbol means "or".Examples of this are:
user_detail.user.emailandprofile_page.osu_usernamewhich have '(Can be blank and if it's blank this field will be "", not null)' in the description.Lists
Lists of a given type should be described as
type[], for examplestring[]. Composite types should not include the[]as a part of the link to its definition. If a field can benull, it would betype[]?; If the list can have null entries, it should betype?[]; If bothtype?[]?.You can use
(type | value)[]to indicate the items of the list can be blank, but not null. You should not usetype[] | [].Examples of such fields are
profile_page.tagsandprofile_page.created_rulesets.Dates and URLs
Date fields should not be
string, butDateand URLs should beURLand notstring.Nested data
user_detailuses- usernameand- email. I think it would be better if the amount of dashes matched the length of the parent: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: