From 42d9417471e0a4f97a2d2897a4c796b712dc99ea Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 29 Jul 2024 00:48:37 -0400 Subject: [PATCH 1/6] create json schema --- hayagriva.schema.json | 273 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 273 insertions(+) create mode 100644 hayagriva.schema.json diff --git a/hayagriva.schema.json b/hayagriva.schema.json new file mode 100644 index 00000000..d638db8e --- /dev/null +++ b/hayagriva.schema.json @@ -0,0 +1,273 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/typst/hayagriva/main/hayagriva.schema.json", + "title": "Hayagriva Bibliography Format", + "description": "A bibliography management format for the modern age.", + "type": "object", + "additionalProperties": false, + "patternProperties": { + "([A-Z]|[a-z]|[0-9]|)+": { + "id": "entry", + "$comment": "The key for a reference item can be series of alphanumeric characters that are uninterrupted by whitespace.", + "type": "object", + "description": "An entry in the bibliography. The citation key for the entry can be any alphanumeric character.", + "properties": { + "type": { + "type": "string", + "enum": [ + "article", + "chapter", + "entry", + "anthos", + "report", + "thesis", + "web", + "scene", + "artwork", + "patent", + "case", + "newspaper", + "legislation", + "manuscript", + "original", + "post", + "misc", + "performance", + "periodical", + "proceedings", + "book", + "blog", + "reference", + "conference", + "anthology", + "repository", + "thread", + "video", + "audio", + "exhibition" + ], + "description": "The media type of the item. Often determines the structure of references." + }, + "title": { + "type": "string", + "description": "The title of the item." + }, + "author": { + "type": [ + "array", + "string" + ], + "items": { + "type": [ + "string", + "object" + ], + "properties": { + "name": { + "type": "string" + }, + "given-name": { + "type": "string" + }, + "prefix": { + "type": "string" + }, + "suffix": { + "type": "string" + }, + "alias": { + "type": "string" + } + }, + "required": [ + "name" + ] + }, + "minItems": 1, + "uniqueItems": true, + "description": "The person or persons primarily responsible for the creation of the item." + }, + "date": { + "type": "string", + "description": "The date at which the item was published." + }, + "parent": { + "anyOf": [ + { + "$ref": "entry" + }, + { + "type": "array", + "items": { + "$ref": "entry" + }, + "minItems": 1, + "uniqueItems": true, + "description": "The item in which the item was published or to which it is strongly associated.", + "$comment": "^ This references the it's parent entry based on the `id`." + } + ] + }, + "editor": { + "type": [ + "array", + "string" + ], + "items": { + "type": "string" + }, + "minItems": 1, + "uniqueItems": true, + "description": "The person or persons responsible for selecting and revising the content of the item." + }, + "affiliated": { + "type": "array", + "description": "Persons involved with the item that do not fit `author` or `editor`.", + "items": { + "type": "object", + "properties": { + "role": { + "type": "string", + "enum": [ + "translator", + "afterword", + "foreword", + "introduction", + "annotator", + "commentator", + "holder", + "compiler", + "founder", + "collaborator", + "organizer", + "cast-member", + "composer", + "producer", + "executive-producer", + "writer", + "cinematography", + "director", + "illustrator", + "narrator" + ] + }, + "names": { + "type": [ + "string", + "array" + ], + "items": { + "type": "string" + }, + "uniqueItems": true + } + } + }, + "minItems": 1, + "uniqueItems": true + }, + "call-number": { + "type": "string", + "description": "The number of the item in a library, institution, or collection. Use with `archive`." + }, + "publisher": { + "type": "string", + "description": "Publisher of the item." + }, + "location": { + "type": "string", + "description": "The location at which the item was published or created." + }, + "organization": { + "type": "string", + "description": "The organization at or for which the item was produced." + }, + "issue": { + "type": [ + "number", + "string" + ], + "description": "For an item whose parent has multiple issues, indicates the position in the issue sequence. Also used to indicate the episode number for TV." + }, + "volume": { + "type": [ + "number", + "string" + ], + "description": "For an item whose parent has multiple volumes/parts/seasons ... of which this item is one." + }, + "volume-total": { + "type": "number", + "description": "Total number of volumes/parts/seasons this item consists of." + }, + "edition": { + "type": [ + "number", + "string" + ], + "description": "The published version of an item." + }, + "page-range": { + "type": [ + "number", + "string" + ], + "description": "The range of pages within the parent this item occupies." + }, + "page-total": { + "type": "number", + "description": "total number of pages the item has" + }, + "time-range": { + "type": "string", + "description": "The time range within the parent this item starts and ends at." + }, + "runtime": { + "type": "string", + "description": "The total runtime of the item." + }, + "url": { + "type": [ + "string", + "object" + ], + "description": "The canonical public URL of the item. Can have access date.", + "properties": { + "value": { + "type": "string" + }, + "date": { + "type": "string" + } + } + }, + "serial-number": { + "type": [ + "string", + "object" + ], + "description": "Any serial number, including article numbers. If you have serial numbers of well-known schemes like doi, you should put them into the serial number as a dictionary like in the second example. Hayagriva will recognize and specially treat `doi`, `isbn`, `issn`, `pmid`, `pmcid`, and `arxiv`. You can also include `serial` for the serial number when you provide other formats as well.", + "additionalProperties": { + "type": "string" + } + }, + "language": { + "type": "string", + "description": "The language of the item. Must be a Unicode language identifier." + }, + "archive": { + "type": "string", + "description": "The name of the institution or collection where the item is kept." + }, + "arhcive-location": { + "type": "string", + "description": "The location of the institution or collection where the item is kept." + }, + "note": { + "type": "string", + "description": "Any additional description to be appended after reference list entry." + } + } + } + } +} \ No newline at end of file From a5b7df1bf165c124c11f56b1e3b72d623bc33e58 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 29 Jul 2024 18:52:00 -0400 Subject: [PATCH 2/6] add examples from specification using the `examples` keyword --- hayagriva.schema.json | 185 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 162 insertions(+), 23 deletions(-) diff --git a/hayagriva.schema.json b/hayagriva.schema.json index d638db8e..c2fa3846 100644 --- a/hayagriva.schema.json +++ b/hayagriva.schema.json @@ -11,9 +11,34 @@ "$comment": "The key for a reference item can be series of alphanumeric characters that are uninterrupted by whitespace.", "type": "object", "description": "An entry in the bibliography. The citation key for the entry can be any alphanumeric character.", + "examples": [ + { + "plaque": { + "type": "Misc", + "title": "Informational plaque about Jacoby's 1967 photos", + "publisher": "Stiftung Reinbeckhallen", + "location": "Berlin, Germany", + "date": 2020, + "parent": { + "type": "Artwork", + "date": 1967, + "author": "Jacoby, Max", + "parent": { + "type": "Anthology", + "title": "Bleibtreustraße", + "archive": "Landesmuseum Koblenz", + "archive-location": "Koblenz, Germany" + } + } + } + } + ], "properties": { "type": { "type": "string", + "examples": [ + "video" + ], "enum": [ "article", "chapter", @@ -50,7 +75,10 @@ }, "title": { "type": "string", - "description": "The title of the item." + "description": "The title of the item.", + "examples": [ + "Rick Astley: How An Internet Joke Revived My Career" + ] }, "author": { "type": [ @@ -85,11 +113,21 @@ }, "minItems": 1, "uniqueItems": true, - "description": "The person or persons primarily responsible for the creation of the item." + "description": "The person or persons primarily responsible for the creation of the item.", + "examples": [ + [ + "Klocke, Iny", + "Wohlrath, Elmar" + ], + "Klocke, Iny" + ] }, "date": { "type": "string", - "description": "The date at which the item was published." + "description": "The date at which the item was published.", + "examples": [ + "1949-05" + ] }, "parent": { "anyOf": [ @@ -104,7 +142,17 @@ "minItems": 1, "uniqueItems": true, "description": "The item in which the item was published or to which it is strongly associated.", - "$comment": "^ This references the it's parent entry based on the `id`." + "$comment": "^ This references the it's parent entry based on the `id`.", + "examples": [ + { + "type": "Anthology", + "title": "Automata studies", + "editor": [ + "Shannon, C. E.", + "McCarthy, J." + ] + } + ] } ] }, @@ -118,11 +166,33 @@ }, "minItems": 1, "uniqueItems": true, - "description": "The person or persons responsible for selecting and revising the content of the item." + "description": "The person or persons responsible for selecting and revising the content of the item.", + "examples": [ + [ + "Stringer, Gary A.", + "Pebworth, Ted-Larry" + ] + ] }, "affiliated": { "type": "array", "description": "Persons involved with the item that do not fit `author` or `editor`.", + "examples": [ + [ + { + "role": "Director", + "names": "Cameron, James" + }, + { + "role": "CastMember", + "names": [ + "Schwarzenegger, Arnold", + "Hamilton, Linda", + "Patrick, Robert" + ] + } + ] + ], "items": { "type": "object", "properties": { @@ -168,63 +238,104 @@ }, "call-number": { "type": "string", - "description": "The number of the item in a library, institution, or collection. Use with `archive`." + "description": "The number of the item in a library, institution, or collection. Use with `archive`.", + "examples": [ + "F16 D14" + ] }, "publisher": { "type": "string", - "description": "Publisher of the item." + "description": "Publisher of the item.", + "examples": [ + "Penguin Books" + ] }, "location": { "type": "string", - "description": "The location at which the item was published or created." + "description": "The location at which the item was published or created.", + "examples": [ + "Lahore, Pakistan" + ] }, "organization": { "type": "string", - "description": "The organization at or for which the item was produced." + "description": "The organization at or for which the item was produced.", + "examples": [ + "Technische Universität Berlin" + ] }, "issue": { "type": [ "number", "string" ], - "description": "For an item whose parent has multiple issues, indicates the position in the issue sequence. Also used to indicate the episode number for TV." + "description": "For an item whose parent has multiple issues, indicates the position in the issue sequence. Also used to indicate the episode number for TV.", + "examples": [ + 5, + "5" + ] }, "volume": { "type": [ "number", "string" ], - "description": "For an item whose parent has multiple volumes/parts/seasons ... of which this item is one." + "description": "For an item whose parent has multiple volumes/parts/seasons ... of which this item is one.", + "examples": [ + "2-3", + 2 + ] }, "volume-total": { "type": "number", - "description": "Total number of volumes/parts/seasons this item consists of." + "description": "Total number of volumes/parts/seasons this item consists of.", + "examples": [ + 12 + ] }, "edition": { "type": [ "number", "string" ], - "description": "The published version of an item." + "description": "The published version of an item.", + "examples": [ + "expanded and revised edition", + "second", + 3 + ] }, "page-range": { "type": [ "number", "string" ], - "description": "The range of pages within the parent this item occupies." + "description": "The range of pages within the parent this item occupies.", + "examples": [ + "812 - 847", + 812 + ] }, "page-total": { "type": "number", - "description": "total number of pages the item has" + "description": "total number of pages the item has", + "examples": [ + 1103 + ] }, "time-range": { "type": "string", - "description": "The time range within the parent this item starts and ends at." + "description": "The time range within the parent this item starts and ends at.", + "examples": [ + "00:57-06:21" + ] }, "runtime": { "type": "string", - "description": "The total runtime of the item." + "description": "The total runtime of the item.", + "examples": [ + "01:42:21,802" + ] }, "url": { "type": [ @@ -239,7 +350,15 @@ "date": { "type": "string" } - } + }, + "examples": [ + { + "url": { + "value": "https://www.reddit.com/r/AccidentalRenaissance/comments/er1uxd/japanese_opposition_members_trying_to_block_the/", + "date": "2020-12-29" + } + } + ] }, "serial-number": { "type": [ @@ -249,23 +368,43 @@ "description": "Any serial number, including article numbers. If you have serial numbers of well-known schemes like doi, you should put them into the serial number as a dictionary like in the second example. Hayagriva will recognize and specially treat `doi`, `isbn`, `issn`, `pmid`, `pmcid`, and `arxiv`. You can also include `serial` for the serial number when you provide other formats as well.", "additionalProperties": { "type": "string" - } + }, + "examples": [ + "2003.13722", + { + "doi": "10.22541/au.148771883.35456290", + "arxiv": "1906.00356", + "serial": "8516" + } + ] }, "language": { "type": "string", - "description": "The language of the item. Must be a Unicode language identifier." + "description": "The language of the item. Must be a Unicode language identifier.", + "examples": [ + "zh-Hans" + ] }, "archive": { "type": "string", - "description": "The name of the institution or collection where the item is kept." + "description": "The name of the institution or collection where the item is kept.", + "examples": [ + "National Library of New Zealand" + ] }, "arhcive-location": { "type": "string", - "description": "The location of the institution or collection where the item is kept." + "description": "The location of the institution or collection where the item is kept.", + "examples": [ + "Wellington, New Zealand" + ] }, "note": { "type": "string", - "description": "Any additional description to be appended after reference list entry." + "description": "Any additional description to be appended after reference list entry.", + "examples": [ + "microfilm version" + ] } } } From 5b0a3a8e6d94bf91f7e1eb36f6894fb28d0284ad Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 29 Jul 2024 20:25:29 -0400 Subject: [PATCH 3/6] use `$dynamicAnchor` and `$dynamicRef` according to the JSON 2020-12 schema --- hayagriva.schema.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hayagriva.schema.json b/hayagriva.schema.json index c2fa3846..56a7f420 100644 --- a/hayagriva.schema.json +++ b/hayagriva.schema.json @@ -7,7 +7,7 @@ "additionalProperties": false, "patternProperties": { "([A-Z]|[a-z]|[0-9]|)+": { - "id": "entry", + "$dynamicAnchor": "entry", "$comment": "The key for a reference item can be series of alphanumeric characters that are uninterrupted by whitespace.", "type": "object", "description": "An entry in the bibliography. The citation key for the entry can be any alphanumeric character.", @@ -132,7 +132,7 @@ "parent": { "anyOf": [ { - "$ref": "entry" + "$dynamicRef": "#entry" }, { "type": "array", From ae1f3a2da34195d0fbfe93573a06d03928a16820 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 30 Jul 2024 16:33:19 -0400 Subject: [PATCH 4/6] update `parent` schema to correctly reference `#entry` if in an array, move description to root of `parent` schema --- hayagriva.schema.json | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/hayagriva.schema.json b/hayagriva.schema.json index 56a7f420..11bb9f19 100644 --- a/hayagriva.schema.json +++ b/hayagriva.schema.json @@ -130,28 +130,31 @@ ] }, "parent": { + "description": "The item in which the item was published or to which it is strongly associated.", "anyOf": [ { - "$dynamicRef": "#entry" + "$dynamicRef": "#entry", + "$comment": "^ This references the `entry` schema defined above by the `$dynamicAnchor` keyword." }, { "type": "array", "items": { - "$ref": "entry" + "$dynamicRef": "#entry", + "$comment": "^ This references the `entry` schema defined above by the `$dynamicAnchor` keyword." }, "minItems": 1, "uniqueItems": true, - "description": "The item in which the item was published or to which it is strongly associated.", - "$comment": "^ This references the it's parent entry based on the `id`.", "examples": [ - { - "type": "Anthology", - "title": "Automata studies", - "editor": [ - "Shannon, C. E.", - "McCarthy, J." - ] - } + [ + { + "type": "Anthology", + "title": "Automata studies", + "editor": [ + "Shannon, C. E.", + "McCarthy, J." + ] + } + ] ] } ] From e5ded8a7fa5b02c7a9032b33c6c7590604f3c290 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 1 Aug 2024 21:19:39 -0400 Subject: [PATCH 5/6] add `abstract`, `annote`, and `genre` to schema --- hayagriva.schema.json | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/hayagriva.schema.json b/hayagriva.schema.json index 11bb9f19..2aab0d55 100644 --- a/hayagriva.schema.json +++ b/hayagriva.schema.json @@ -159,6 +159,24 @@ } ] }, + "abstract": { + "type": "string", + "description": "Abstract of the item (e.g. the abstract of a journal article).", + "examples": [ + "The dominant sequence transduction models are based on complex..." + ] + }, + "annote": { + "type": "string", + "description": "Short markup, decoration, or annotation to the item (e.g., to indicate items included in a review); For descriptive text (e.g., in an annotated bibliography), use `note` instead." + }, + "genre": { + "type": "string", + "description": "Type, class, or subtype of the item (e.g. “Doctoral dissertation” for a PhD thesis; “NIH Publication” for an NIH technical report); Do not use for topical descriptions or categories (e.g. “adventure” for an adventure movie).", + "examples": [ + "Doctoral dissertation" + ] + }, "editor": { "type": [ "array", From 3bab47a7dd3cc0d23d19740e9ff697c9598b3ac1 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 26 Aug 2024 17:38:54 -0400 Subject: [PATCH 6/6] add `annote` example to JSON schema --- hayagriva.schema.json | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/hayagriva.schema.json b/hayagriva.schema.json index 2aab0d55..7442a307 100644 --- a/hayagriva.schema.json +++ b/hayagriva.schema.json @@ -168,7 +168,10 @@ }, "annote": { "type": "string", - "description": "Short markup, decoration, or annotation to the item (e.g., to indicate items included in a review); For descriptive text (e.g., in an annotated bibliography), use `note` instead." + "description": "Short markup, decoration, or annotation to the item (e.g., to indicate items included in a review); For descriptive text (e.g., in an annotated bibliography), use `note` instead.", + "examples": [ + "The researchers at NYU explore in this paper ..." + ] }, "genre": { "type": "string",