Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Suggestion: Improve type notation in structure tables #6

Open
Flutterish opened this issue Apr 10, 2022 · 0 comments
Open

Suggestion: Improve type notation in structure tables #6

Flutterish opened this issue Apr 10, 2022 · 0 comments
Assignees
Labels

Comments

@Flutterish
Copy link

Flutterish commented Apr 10, 2022

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

  1. type? means the value can be null or undefined. A lack of the ? means it will never be null or undefined.
  2. 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.
  3. 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.
  4. The type Date is a JSON date string in UTC.
  5. The type URL is a string.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants