From c0d4580cd08541655483e7637426b322dd96203b Mon Sep 17 00:00:00 2001 From: Nilesh Date: Sun, 1 Jan 2023 03:13:33 +0000 Subject: [PATCH] Fix db/README --- db/README.md | 43 ++++++++++++++++++++++++++++++------------- db/items.json | 2 +- db/schema.sql | 2 +- 3 files changed, 32 insertions(+), 15 deletions(-) diff --git a/db/README.md b/db/README.md index 4de63c0..921786b 100644 --- a/db/README.md +++ b/db/README.md @@ -1,38 +1,55 @@ # JSON format +These JSON files are now not the master data but will be generated from a PostgreSQL database whose schema is defined in `schema.sql`. + ## topics.json `name` is used as primary key and therefore, must be unique and avoid uppercase and special characters other than hyphen and slash. Here are some examples: `physics`, `linear-algebra`, `nations/india`, `programming-languages/objective-c`. -`display_name` is used as human-readable name and can preserve uppercase. For eg: `ADHD`. +`hname` is used as human-readable name and can preserve uppercase. For eg: `ADHD`. -`parent_id` should be the name of the parent topic. This makes it possible to show a hierarchical view. If a topic does not have `parent_id`, it would be at the top-level but if it doesn't have children topics of its own, it will be clubbed under a dummy top-level topic called `Misc`. +`parent_name` should be the name of the parent topic. This makes it possible to show a hierarchical view. If a topic does not have `parent_name`, it would be at the top-level but if it doesn't have children topics of its own, it will be clubbed under a dummy top-level topic called `Misc`. `sort_index` is an integer that's used for controlling the ordering in which topics are displayed. +## creators.json + +A top-level table that lists well-known experts and their metadata like occupation, links etc. These are references from items and their reviews. ## items.json -`iid` should be a unique UUID. It is needed because `reviews.js` needs to refer to items and there is no other natural primary key. Later, if we'd want to build collections of items, the same `iid` key would be helpful. +`id` should be a unique UUID. It is needed because there is no other natural primary key. This might also be useful later for defining collections of items. `description` can contain markdown with multiple lines. -`links` is an array value separated by `;`. Each item in this array is `format`, `url` and optional identifiers separated by `|`. For eg, `links` can have a value like this: `summary|https://sivers.org/book/Decisive|ipfs:bafykbzaceaejt6z54qnwnl3ccvw2lsdfksbeuwuh4sv77ixj4c3ldeof2c5so?filename=Daniel%20Higginbotham%20-%20Clojure%20for%20the%20Brave%20and%20True-No%20Starch%20Press%20%282015%29.pdf;book|https://www.goodreads.com/book/show/15798078-decisive;summary|https://fourminutebooks.com/decisive-summary/|doi:https://doi.org/10.2307/2687687`. +`links` is an array of strings. Each item in this array is `format`, `url` and optional identifiers separated by `|`. For eg, one of the strings in `links` might: `summary|https://sivers.org/book/Decisive|ipfs:bafykbzaceaejt6z54qnwnl3ccvw2lsdfksbeuwuh4sv77ixj4c3ldeof2c5so?filename=Daniel%20Higginbotham%20-%20Clojure%20for%20the%20Brave%20and%20True-No%20Starch%20Press%20%282015%29.pdf`. -Currently `ipfs:` and `doi:` identifiers are supported. In future, ISBN can also be supported using the `isbn:` or `isbn13:` schemes. +The use-case for optional identifiers are things like `ipfs:`, `doi:`, `isbn:` or `isbn13:`. -`topics` is a array value of topic names separated by `;`. These should exactly match `topics` table's `name` column. +`topics` is a array of topic names. These should exactly match `topics` table's `name` column. -`creators` is arbitrary string for now. For eg: `Charles Darwin`. In future, this might become a full record on its own including fields like `name`,`website`,`twitter`,`email`. In that case, we will have to somehow figure out unique key for each creator that could serve the role of primary key and foreign key. +`creators` is an array of strings which are references to the `creators` table's `name` column. For eg: `charles_darwin`. -`difficulty` must be empty or one of these: `childlike`, `beginner`, `intermediate`, `advanced`, `research`. +`difficulty` must be either `null` or one of these: `childlike`, `beginner`, `intermediate`, `advanced`, `research`. -`rating` is on a 5.0 point scale with up to two decimal places allowed. This is a curated value and should not be simply copied from external sources. +`rating` is an integer on 0-100 point scale. This is a curated value and should not be simply copied from external sources. `tags` can describe quality: `visual`, `entertaining`, `challenging`, `inspirational`, `interactive`, `oer`. `oer` stands for "Open Educational Resource" and can be used if the linked content does not require payment or user login. -## reviews.json +`reviews` is an array of JSON objects that must match this schema as you can see in `schema.sql`: -`item_id` is a foreign key to `items.js`. -`by` is the name of the person or item. -`blurb` is small description in markdown format. \ No newline at end of file +``` +{ + "type": "array", + "items": { + "type": "object", + "properties": { + "by_item": {"type": ["string", "null"]}, + "by_creator": {"type": ["string", "null"]}, + "rating": {"type": ["integer", "null"], "minimum": 0, "maximum": 100}, + "blurb": {"type": ["string", "null"]}, + "url": {"type": ["string", "null"]} + } + } +} +``` diff --git a/db/items.json b/db/items.json index 312f456..5eec782 100644 --- a/db/items.json +++ b/db/items.json @@ -142094,7 +142094,7 @@ ], "links": [ "book|https://www.goodreads.com/book/show/31498845-without-words", - "book|http://www.jamestanton.com/?p=1605" + "website|http://www.jamestanton.com/?p=1605" ], "topics": [ "mathematics" diff --git a/db/schema.sql b/db/schema.sql index f435d0d..1ef404d 100644 --- a/db/schema.sql +++ b/db/schema.sql @@ -23,7 +23,7 @@ CREATE TABLE creators ( CREATE TABLE items ( id uuid DEFAULT gen_random_uuid() PRIMARY KEY, - hname VARCHAR(1024) NOT NULL, + name VARCHAR(1024) NOT NULL, description TEXT, -- in markdown image VARCHAR(1024), tags TEXT[] NOT NULL, -- eg: oer, nsfw, free/paid etc