Skip to content

Commit

Permalink
feat: Add Cite and CiteGroup types
Browse files Browse the repository at this point in the history
  • Loading branch information
@beneboy
beneboy committed Aug 1, 2019
1 parent a278948 commit e222035
Show file tree
Hide file tree
Showing 7 changed files with 259 additions and 2 deletions.
108 changes: 108 additions & 0 deletions schema/Cite.md
View file
Original file line number Diff line number Diff line change
@@ -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<date>` \| `string<date-time>` | Date/time of creation. | [CreativeWork](./CreativeWork.html) |
| dateModified | `string<date>` \| `string<date-time>` | Date/time of most recent modification. | [CreativeWork](./CreativeWork.html) |
| datePublished | `string<date>` \| `string<date-time>` | 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<uri>` \| [`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<uri>` | 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.
```
47 changes: 47 additions & 0 deletions schema/Cite.schema.yaml
View file
Original file line number Diff line number Diff line change
@@ -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
83 changes: 83 additions & 0 deletions schema/CiteGroup.md
View file
Original file line number Diff line number Diff line change
@@ -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"
}
]
}
```
16 changes: 16 additions & 0 deletions schema/CiteGroup.schema.yaml
View file
Original file line number Diff line number Diff line change
@@ -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
4 changes: 2 additions & 2 deletions schema/CreativeWork.schema.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions schema/InlineContent.schema.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,4 @@ anyOf:
- $ref: Strong
- $ref: Subscript
- $ref: Superscript
- $ref: CiteGroup
2 changes: 2 additions & 0 deletions ts/util/type-maps.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ export type InlineNodesWithType = Exclude<
>

export const inlineContentTypes: TypeMap<InlineNodesWithType> = {
CiteGroup: 'CiteGroup',
Code: 'Code',
CodeBlock: 'CodeBlock',
CodeExpr: 'CodeExpr',
Expand All @@ -61,6 +62,7 @@ export const blockContentTypes: TypeMap<BlockContent> = {
}

export const creativeWorkTypes: TypeMap<CreativeWork> = {
Cite: 'Cite',
CreativeWork: 'CreativeWork',
Article: 'Article',
AudioObject: 'AudioObject',
Expand Down

0 comments on commit e222035

Please sign in to comment.