fix(Schema): Fix missing id and description properties

Also removes redunant links to https://schema.org and
where possible places descritions on a single line.

schema/Article.schema.yaml

@@ -3,6 +3,7 @@ title: Article
 extends: CreativeWork
 role: primary
 status: unstable
+description: An article, including news and scholarly articles.
 properties:
   environment:
     '@id': stencila:environment

schema/AudioObject.schema.yaml

@@ -3,16 +3,13 @@ title: AudioObject
 extends: MediaObject
 role: secondary
 status: stable
-description: |
-  An audio file. https://schema.org/AudioObject
+description: An audio file
 properties:
   caption:
     '@id': schema:caption
-    description: |
-      The caption for this audio recording.
+    description: The caption for this audio recording.
     type: string
   transcript:
     '@id': schema:transcript
-    description: |
-      The transcript of this audio recording.
+    description: The transcript of this audio recording.
     type: string

schema/Brand.schema.yaml

@@ -4,20 +4,21 @@ extends: Thing
 role: tertiary
 status: unstable
 description: |
-  A brand is a name used by an organization or business person for labeling a product,
-  product group, or similar. https://schema.org/Brand.
+  A brand used by an organization or person for labeling a product,
+  product group, or similar.
 properties:
   logo:
-    description: |
-      A logo of of the brand. It can be either a URL of the image or image itself.
+    '@id': schema:logo
+    description: A logo associated with the brand.
     anyOf:
       - type: string
         format: uri
       - $ref: ImageObject
   reviews:
     '@id': schema:review
-    description: |
-      Short reviews of the brand and/or the products it represents.
+    description: Reviews of the brand.
     type: array
     items:
       type: string
+required:
+  - name

schema/CodeChunk.schema.yaml

@@ -3,13 +3,11 @@ title: CodeChunk
 extends: SoftwareSourceCode
 role: secondary
 status: unstable
-description: |
-  A executable chunk of code.
+description: A executable chunk of code.
 properties:
   outputs:
     '@id': stencila:outputs
-    description: |
-      Outputs from executing the chunk.
+    description: Outputs from executing the chunk.
     type: array
     items:
       $ref: Node

schema/CodeExpr.schema.yaml

@@ -3,9 +3,10 @@ title: CodeExpr
 extends: SoftwareSourceCode
 role: secondary
 status: unstable
-description: An expression.
+description: An expression defined in programming language source code.
 properties:
   value:
     '@id': schema:value
+    description: The value of the expression when it was last evaluated.
     allOf:
       - $ref: Node

schema/Collection.schema.yaml

@@ -3,8 +3,7 @@ title: Collection
 extends: CreativeWork
 role: secondary
 status: stable
-description: |
-  A created collection of CreativeWorks or other artefacts.
+description: A created collection of CreativeWorks or other artefacts.
 # The [schema.org defintion](https://schema.org/Collection) adds
 # `collectionSize` but has not been added here because that feels
 # redudant e.g. a developer could use `collection.parts.length` instead

schema/ContactPoint.schema.yaml

@@ -3,26 +3,25 @@ title: ContactPoint
 extends: Thing
 role: tertiary
 status: unstable
-description: A contact point—for example, a R&D department. https://schema.org/ContactPoint.
+description: A contact point—for example, a R&D department.
 properties:
   availableLanguages:
     '@id': schema:availableLanguage
     description: |
-      Languages (human not programming) in which it is possible to communicate with the organization/department etc.
+      Languages (human not programming) in which it is possible to communicate
+      with the organization/department etc.
     type: array
     items:
       type: string
   emails:
     '@id': schema:email
-    description: |
-      Email address for correspondence. It must be provided in a valid email format (eg. info@example.com ).
+    description: Email address for correspondence.
     type: array
     items:
       type: string
       format: email
   telephone:
     '@id': schema:telephone
-    description: |
-      "Phone contact number. Accepted formats: +44 123455, (02)12345, 006645667."
+    description: "The telephone number of the contact point. Accepted formats: +44 123455, (02)12345, 006645667."
     type: string
     pattern: '^[+#*\(\)\[\]]*([0-9][ ext+-pw#*\(\)\[\]]*){6,45}$'

schema/CreativeWork.schema.yaml

@@ -4,12 +4,11 @@ extends: Thing
 role: base
 status: stable
 description: |
-  The most generic kind of creative work, including books, movies, photographs,
-  software programs, etc. https://schema.org/CreativeWork
+  A creative work, including books, movies, photographs, software programs, etc.
 properties:
   authors:
     '@id': schema:author
-    description: The authors of this this creative work.
+    description: The authors of this creative work.
     type: array
     items:
       anyOf:
@@ -123,11 +122,13 @@ properties:
     # The name "title" is more appropriate to our context than schema.org's "headline".
     # We provide the latter as an alias.
     '@id': schema:headline
+    description: The title of the creative work.
     aliases:
       - headline
     type: string
   version:
     '@id': schema:version
+    description: The version of the creative work.
     anyOf:
       - type: string
       - type: number

schema/Datatable.schema.yaml

@@ -6,7 +6,8 @@ status: experimental
 description: A table of data.
 properties:
   columns:
-    description: TODO
+    '@id': stencila:columns
+    description: The columns of data.
     type: array
     items:
       $ref: DatatableColumn

schema/DatatableColumn.schema.yaml

@@ -3,13 +3,16 @@ title: DatatableColumn
 extends: Thing
 role: secondary
 status: experimental
+description: A column of data within a Datatable.
 properties:
   schema:
+    '@id': stencila:schema
     description: The schema to use to validate data in the column.
     allOf:
       - $ref: DatatableColumnSchema
   values:
-    description: The values of the column.
+    '@id': stencila:values
+    description: The data values of the column.
     type: array
 required:
   - name

schema/DatatableColumnSchema.schema.yaml

@@ -2,12 +2,17 @@ title: DatatableColumnSchema
 '@id': stencila:DatatableColumnSchema
 extends: Entity
 role: tertiary
-status: experimental
+status: unstable
+description: |
+  A schema specifying the data values that are valid within a Datatable column.
 properties:
   items:
+    '@id': stencila:items
+    description: An object representing the JSON Schema `items` keyword.
     type: object
   uniqueItems:
+    '@id': stencila:uniqueItems
+    description: A flag to indicate that each value in the column should be unique.
     type: boolean
-    default: false
 required:
   - items

schema/Entity.schema.yaml

@@ -9,13 +9,15 @@ properties:
     # and so should not have a `@id` since it is not a property.
     # It is extended with the titles of all descendant types during
     # the generation of schema.json files.
+    '@id': schema:type
     description: The name of the type and all descendant types.
     type: string
     enum: [Entity]
     default: Entity
   id:
     # This is a special property analogous to JSON-LD's `@id` keyword
     # and so should not have a `@id` since it is not a property.
+    '@id': schema:id
     description: The identifier for this item.
     type: string
   meta:

schema/Environment.schema.yaml

@@ -23,11 +23,11 @@ properties:
     type: array
     items:
       $ref: SoftwareSourceCode
-  environmentSource:
+  source:
     '@id': stencila:environmentSource
     description: |
-      Source of environment definition. For example, a URL to a Dockerfile, a path to Singularity recipe file,
-      or a path to a filesystem folder.,
+      Source of environment definition. e.g. a URL to a Dockerfile,
+      or a path to a filesystem folder.
     type: string
 required:
   - name

schema/Heading.schema.yaml

@@ -6,10 +6,13 @@ status: experimental
 description: Heading
 properties:
   depth:
+    '@id': stencila:depth
+    description: The depth of the heading.
     type: number
     minimum: 1
     maximum: 6
   content:
+    '@id': stencila:content
     description: Content of the heading.
     type: array
     items:

schema/ImageObject.schema.yaml

@@ -3,17 +3,14 @@ title: ImageObject
 extends: MediaObject
 role: secondary
 status: stable
-description: |
-  An image file. https://schema.org/ImageObject
+description: An image file.
 properties:
   caption:
     '@id': schema:caption
-    description: |
-      The caption for this image.
+    description: The caption for this image.
     type: string
   thumbnail:
     '@id': schema:thumbnail
-    description: |
-      Thumbnail image of this image.
+    description: Thumbnail image of this image.
     allOf:
       - $ref: ImageObject

schema/Include.schema.yaml

@@ -7,15 +7,19 @@ status: experimental
 extends: Entity
 properties:
   source:
+    '@id': stencila:source
     description: The source of the content.
     type: string
   mediaType:
+    '@id': stencila:mediaType
     description: The media type of the source content.
     type: string
   hash:
+    '@id': stencila:hash
     description: A SHA256 hash of the source content and media type the last time that the source was decoded.
     type: string
   content:
+    '@id': stencila:content
     description: The content to be included.
     type: array
     items:

schema/Link.schema.yaml

@@ -7,11 +7,13 @@ description: A hyperlink to other pages, sections within the same document, reso
 properties:
   content:
     '@id': stencila:content
+    description: The textual content of the link.
     type: array
     items:
       $ref: InlineContent
   target:
     '@id': stencila:target
+    description: The target of the link.
     type: string
     format: uri
   title:

schema/ListItem.schema.yaml

@@ -7,11 +7,13 @@ description: A single item in a list.
 properties:
   content:
     '@id': stencila:content
+    description: The content of the list item.
     type: array
     items:
       $ref: Node
   checked:
     '@id': stencila:checked
+    description: A flag to indicate if this list item is checked.
     type: boolean
     default: false
 required:

schema/Mark.schema.yaml

@@ -4,12 +4,12 @@ extends: Entity
 role: base
 status: stable
 description: |
-  A base class for nodes that mark some other inline content (e.g. `string` or other `InlineContent` nodes) in some way (e.g. as being emphasised, or quoted).
+  A base class for nodes that mark some other inline content
+  in some way (e.g. as being emphasised, or quoted).
 properties:
   content:
     '@id': 'stencila:content'
-    description: |
-      The content that is marked.
+    description: The content that is marked.
     type: array
     items:
       $ref: InlineContent

schema/MediaObject.schema.yaml

@@ -5,7 +5,7 @@ role: base
 status: stable
 description: |
   A media object, such as an image, video, or audio object embedded in a web page or a
-  downloadable dataset. https://schema.org/MediaObject
+  downloadable dataset.
 properties:
   bitrate:
     '@id': schema:bitrate

schema/Organization.schema.yaml

@@ -3,7 +3,7 @@ title: Organization
 extends: Thing
 role: secondary
 status: unstable
-description: An organization such as a school, NGO, corporation, club, etc. https://schema.org/Organization.
+description: An organization such as a school, NGO, corporation, club, etc.
 properties:
   address:
     '@id': schema:address

schema/Paragraph.schema.yaml

@@ -6,6 +6,8 @@ status: experimental
 description: Paragraph
 properties:
   content:
+    '@id': 'stencila:content'
+    description: The contents of the paragraph.
     type: array
     items:
       $ref: InlineContent

schema/Person.schema.yaml

@@ -3,7 +3,7 @@ title: Person
 extends: Thing
 role: secondary
 status: stable
-description: A person (alive, dead, undead, or fictional). https://schema.org/Person.
+description: A person (alive, dead, undead, or fictional).
 codec: person
 properties:
   address:
@@ -31,9 +31,8 @@ properties:
       - surnames
       - lastName
       - lastNames
-    description: |
-      Family name. In the U.S., the last name of an Person.
-      This can be used along with givenName instead of the name property.
+    description: Family name. In the U.S., the last name of a person.
+    $comment: This can be used along with givenName instead of the name property.
     allOf:
       - codec: ssv
       - type: array
@@ -56,9 +55,8 @@ properties:
       - firstNames
       # It is necessary to specify this alias because of use of allOf
       - givenName
-    description: |
-      Given name. In the U.S., the first name of a Person.
-      This can be used along with familyName instead of the name property.
+    description: Given name. In the U.S., the first name of a person.
+    $comment: This can be used along with familyName instead of the name property.
     allOf:
       - codec: ssv
       - type: array