diff --git a/schema/Cite.md b/schema/Cite.md new file mode 100644 index 0000000000..aa6e00ceef --- /dev/null +++ b/schema/Cite.md @@ -0,0 +1,108 @@ +--- +title: Cite +authors: [] +--- + +include: ../built/Cite.schema.md +::: +A reference to a CreativeWork that is cited in another CreativeWork. + +## Properties + +| **type _(required)_** | `enum<`​`Cite`​`>` | The name of the type and all descendant types. | [Entity](./Entity.html) | +| --------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | +| alternateNames | `array<`​`string`​`>` | Alternate names (aliases) for the item. | [Thing](./Thing.html) | +| authors | `array<`​[`Person`](./Person.html) \| [`Organization`](./Organization.html)​`>` | The authors of this creative work. | [CreativeWork](./CreativeWork.html) | +| citationMode | `enum<`​`normal` \| `suppressAuthor`​`>` | How the cite is rendered in the surrounding text. | [Cite](./Cite.html) | +| citations | `array<`​`string` \| [`CreativeWorkTypes`](./CreativeWorkTypes.html)​`>` | Citations or references to other creative works, such as another publication, web page, scholarly article, etc. | [CreativeWork](./CreativeWork.html) | +| content | `array<`​[`Node`](./Node.html)​`>` | The structured content of this creative work c.f. property \`text\`. | [CreativeWork](./CreativeWork.html) | +| dateCreated | `string` \| `string` | Date/time of creation. | [CreativeWork](./CreativeWork.html) | +| dateModified | `string` \| `string` | Date/time of most recent modification. | [CreativeWork](./CreativeWork.html) | +| datePublished | `string` \| `string` | Date of first publication. | [CreativeWork](./CreativeWork.html) | +| description | `string` | A description of the item. | [Thing](./Thing.html) | +| editors | `array<`​[`Person`](./Person.html)​`>` | Persons who edited the CreativeWork. | [CreativeWork](./CreativeWork.html) | +| funders | `array<`​[`Person`](./Person.html) \| [`Organization`](./Organization.html)​`>` | Person or organisation that funded the CreativeWork. | [CreativeWork](./CreativeWork.html) | +| id | `string` | The identifier for this item. | [Entity](./Entity.html) | +| isPartOf | [`CreativeWorkTypes`](./CreativeWorkTypes.html) | An item or other CreativeWork that this CreativeWork is a part of. | [CreativeWork](./CreativeWork.html) | +| licenses | `array<`​`string` \| [`CreativeWorkTypes`](./CreativeWorkTypes.html)​`>` | License documents that applies to this content, typically indicated by URL. | [CreativeWork](./CreativeWork.html) | +| meta | `object` | Metadata associated with this item. | [Entity](./Entity.html) | +| name | `string` | The name of the item. | [Thing](./Thing.html) | +| pageEnd | `string` \| `integer` | The page on which the work ends; for example "138" or "xvi". | [Cite](./Cite.html) | +| pageStart | `string` \| `integer` | The page on which the work starts; for example "135" or "xiii". | [Cite](./Cite.html) | +| pagination | `string` | Any description of pages that is not separated into pageStart and pageEnd; for example, "1-6, 9, 55". | [Cite](./Cite.html) | +| parts | `array<`​[`CreativeWorkTypes`](./CreativeWorkTypes.html)​`>` | Elements of the collection which can be a variety of different elements, such as Articles, Datatables, Tables and more. | [CreativeWork](./CreativeWork.html) | +| prefix | `string` | A prefix to show before the citation. | [Cite](./Cite.html) | +| publisher | [`Person`](./Person.html) \| [`Organization`](./Organization.html) | A publisher of the CreativeWork. | [CreativeWork](./CreativeWork.html) | +| suffix | `string` | A suffix to show after the citation. | [Cite](./Cite.html) | +| target | `string` | The target of the citation (URL or reference ID). | [Cite](./Cite.html) | +| text | `string` | The textual content of this creative work. | [CreativeWork](./CreativeWork.html) | +| title | `string` | The title of the creative work. | [CreativeWork](./CreativeWork.html) | +| url | `string` | The URL of the item. | [Thing](./Thing.html) | +| version | `string` \| `number` | The version of the creative work. | [CreativeWork](./CreativeWork.html) | + +::: + +A `Cite` node is used within a [`CreativeWork`](./CreativeWork.html), usually an [`Article`](./Article.html), to refer to an other `CreativeWork`. Often a `Cite` will be associated with other citations, in a [`CiteGroup`](../CiteGroup.html). + +# Examples + +The following example a (very) short article, shows how a `Cite` is used to refer to another `Article` in the article's `references`. + +```json import=ex1 +{ + "type": "Article", + "title": "An example of using the Cite node type", + "authors": [ + { + "type": "Person", + "givenNames": ["Joe"], + "familyNames": ["Bloggs"] + } + ], + "content": [ + { + "type": "Paragraph", + "content": [ + "A citation of ", + { + "type": "Cite", + "target": "some-one-else-1991" + }, + "." + ] + } + ], + "references": [ + { + "type": "Article", + "id": "some-one-else-1991", + "title": "Another article by someone else", + "authors": [ + { + "type": "Person", + "givenNames": ["Some", "One"], + "familyNames": ["Else"] + } + ], + "datePublished": "1991" + } + ] +} +``` + +# Encodings + +```md +--- +title: An example of using the Cite node type +authors: + - type: Person + #... +references: + - type: Article + id: some-one-else-1991 + #... +--- + +A citation of @some-one-else-1991. +``` diff --git a/schema/Cite.schema.yaml b/schema/Cite.schema.yaml new file mode 100644 index 0000000000..8ca216b6ac --- /dev/null +++ b/schema/Cite.schema.yaml @@ -0,0 +1,47 @@ +title: Cite +'@id': stencila:Cite +extends: CreativeWork +role: secondary +status: unstable +description: | + A reference to a CreativeWork that is cited in another CreativeWork. +properties: + citationMode: + '@id': stencila:citationMode + description: How the cite is rendered in the surrounding text. + type: string + enum: + - normal + - suppressAuthor + pageStart: + '@id': schema:pageStart + description: The page on which the work starts; for example "135" or "xiii". + anyOf: + - type: string + - type: integer + pageEnd: + '@id': schema:pageEnd + description: The page on which the work ends; for example "138" or "xvi". + anyOf: + - type: string + - type: integer + pagination: + '@id': schema:pagination + description: | + Any description of pages that is not separated into pageStart and pageEnd; + for example, "1-6, 9, 55". + type: string + prefix: + '@id': stencila:citationPrefix + description: A prefix to show before the citation. + type: string + suffix: + '@id': stencila:citationSuffix + description: A suffix to show after the citation. + type: string + target: + '@id': stencila:target + description: The target of the citation (URL or reference ID). + type: string +required: + - target diff --git a/schema/CiteGroup.md b/schema/CiteGroup.md new file mode 100644 index 0000000000..920c4646a5 --- /dev/null +++ b/schema/CiteGroup.md @@ -0,0 +1,83 @@ +--- +title: Cite Group +authors: [] +--- + +include: ../built/CiteGroup.schema.md +::: +A group of `Cite` nodes + +## Properties + +| **items _(required)_** | `array<`​[`Cite`](./Cite.html)​`>` | One or more Cites to be referenced in the same surrounding text. | [CiteGroup](./CiteGroup.html) | +| ---------------------- | ---------------------------------- | ---------------------------------------------------------------- | ----------------------------- | +| **type _(required)_** | `enum<`​`CiteGroup`​`>` | The name of the type and all descendant types. | [Entity](./Entity.html) | +| id | `string` | The identifier for this item. | [Entity](./Entity.html) | +| meta | `object` | Metadata associated with this item. | [Entity](./Entity.html) | + +::: + +When some content in a [`Creative Work`](./CreativeWork.html) cites more than one reference for a particular piece of +text, use a `CiteGroup` to encapsulate multiple [`Cite`](./Cite.html) nodes. + +# Examples + +The following example is a very short article that groups multiple citations together. + +```json +{ + "type": "Article", + "title": "An example of using the CiteGroup node type", + "authors": [ + { + "type": "Person", + "givenNames": ["Joe"], + "familyNames": ["Bloggs"] + } + ], + "content": [ + { + "type": "Paragraph", + "content": [ + "Citing two articles ", + { + "type": "CiteGroup", + "items": [ + { "type": "Cite", "target": "some-one-else-1991" }, + { "type": "Cite", "target": "updated-works-2009" } + ] + }, + "." + ] + } + ], + "references": [ + { + "type": "Article", + "id": "some-one-else-1991", + "title": "Another article by someone else", + "authors": [ + { + "type": "Person", + "givenNames": ["Some", "One"], + "familyNames": ["Else"] + } + ], + "datePublished": "1991" + }, + { + "type": "Article", + "id": "update-works-2009", + "title": "A Better Updated Work", + "authors": [ + { + "type": "Person", + "givenNames": ["Some", "Better"], + "familyNames": ["Person"] + } + ], + "datePublished": "2009" + } + ] +} +``` diff --git a/schema/CiteGroup.schema.yaml b/schema/CiteGroup.schema.yaml new file mode 100644 index 0000000000..d95d1bbba0 --- /dev/null +++ b/schema/CiteGroup.schema.yaml @@ -0,0 +1,16 @@ +title: CiteGroup +'@id': stencila:CiteGroup +extends: Entity +role: secondary +status: unstable +description: | + A group of `Cite` nodes +properties: + items: + '@id': stencila:items + type: array + description: One or more `Cite`s to be referenced in the same surrounding text. + items: + $ref: Cite +required: + - items diff --git a/schema/CreativeWork.schema.yaml b/schema/CreativeWork.schema.yaml index 5edefb51d1..bf08962f65 100644 --- a/schema/CreativeWork.schema.yaml +++ b/schema/CreativeWork.schema.yaml @@ -14,10 +14,10 @@ properties: anyOf: - $ref: Person - $ref: Organization - citations: + references: '@id': schema:citation description: | - Citations or references to other creative works, such as another publication, + References to other creative works, such as another publication, web page, scholarly article, etc. type: array items: diff --git a/schema/InlineContent.schema.yaml b/schema/InlineContent.schema.yaml index 7f3014937e..aa81f69ac2 100644 --- a/schema/InlineContent.schema.yaml +++ b/schema/InlineContent.schema.yaml @@ -20,3 +20,4 @@ anyOf: - $ref: Strong - $ref: Subscript - $ref: Superscript + - $ref: CiteGroup diff --git a/ts/util/type-maps.ts b/ts/util/type-maps.ts index 4af33c4b3c..e042990eed 100644 --- a/ts/util/type-maps.ts +++ b/ts/util/type-maps.ts @@ -35,6 +35,7 @@ export type InlineNodesWithType = Exclude< > export const inlineContentTypes: TypeMap = { + CiteGroup: 'CiteGroup', Code: 'Code', CodeBlock: 'CodeBlock', CodeExpr: 'CodeExpr', @@ -61,6 +62,7 @@ export const blockContentTypes: TypeMap = { } export const creativeWorkTypes: TypeMap = { + Cite: 'Cite', CreativeWork: 'CreativeWork', Article: 'Article', AudioObject: 'AudioObject',