fix(*): Update status properties, add note on status to docs and publ…

…ish experimental schemas
stencila · May 11, 2021 · 7fe6693 · 7fe6693
1 parent a944fea
commit 7fe6693
Show file tree

Hide file tree

Showing 34 changed files with 59 additions and 42 deletions.
diff --git a/schema/Array.schema.yaml b/schema/Array.schema.yaml
@@ -1,5 +1,6 @@
 title: Array
 '@id': stencila:Array
 category: data
+status: stable
 description: A value comprised of several other values.
 type: array
diff --git a/schema/Article.schema.yaml b/schema/Article.schema.yaml
@@ -3,7 +3,7 @@ title: Article
 extends: CreativeWork
 category: works
 role: primary
-status: unstable
+status: stable
 description: An article, including news and scholarly articles.
 $comment: |
   This is an implementation, and extension, of schema.org [`Article`](https://schema.org/Article).

diff --git a/schema/BlockContent.schema.yaml b/schema/BlockContent.schema.yaml
@@ -1,5 +1,6 @@
 title: BlockContent
 category: text
+status: stable
 description: Union type for valid block content.
 anyOf:
   - $ref: Claim

diff --git a/schema/Boolean.schema.yaml b/schema/Boolean.schema.yaml
@@ -1,5 +1,6 @@
 title: Boolean
 '@id': schema:Boolean
 category: data
+status: stable
 description: A value that is either true or false
 type: boolean
diff --git a/schema/BooleanValidator.schema.yaml b/schema/BooleanValidator.schema.yaml
@@ -1,9 +1,9 @@
 title: BooleanValidator
 '@id': stencila:BooleanValidator
 extends: Validator
+category: data
 role: validation
 status: unstable
-category: data
 description: A schema specifying that a node must be a boolean value.
 $comment: |
   A node will be valid against this schema if it is either `true` or `false.

diff --git a/schema/Brand.schema.yaml b/schema/Brand.schema.yaml
@@ -2,7 +2,7 @@ title: Brand
 '@id': schema:Brand
 extends: Thing
 role: tertiary
-status: unstable
+status: stable
 category: other
 description: |
   A brand used by an organization or person for labeling a product,

diff --git a/schema/CitationIntentEnumeration.schema.yaml b/schema/CitationIntentEnumeration.schema.yaml
@@ -1,9 +1,9 @@
 title: CitationIntentEnumeration
 '@id': stencila:CitationIntentEnumeration
-status: unstable
+extends: Enumeration
 category: text
+status: unstable
 role: secondary
-extends: Enumeration
 description: The type or nature of a citation, both factually and rhetorically.
 $comment: |
   The members of this enumeration map directly on to the types in the [Citation Typing Ontology (CiTO)](http://www.sparontologies.net/ontologies/cito).

diff --git a/schema/CodeExpression.schema.yaml b/schema/CodeExpression.schema.yaml
@@ -2,7 +2,7 @@ title: CodeExpression
 '@id': stencila:CodeExpression
 extends: CodeFragment
 role: secondary
-status: stable
+status: unstable
 category: code
 description: An expression defined in programming language source code.
 properties:

diff --git a/schema/ContactPoint.schema.yaml b/schema/ContactPoint.schema.yaml
@@ -2,7 +2,7 @@ title: ContactPoint
 '@id': schema:ContactPoint
 extends: Thing
 role: tertiary
-status: unstable
+status: stable
 category: other
 description: A contact point, usually within an organization.
 $comment:

diff --git a/schema/Function.schema.yaml b/schema/Function.schema.yaml
@@ -2,7 +2,7 @@ title: Function
 '@id': stencila:Function
 extends: Entity
 role: secondary
-status: unstable
+status: experimental
 category: code
 description: A function with a name, which might take Parameters and return a value of a certain type.
 properties:

diff --git a/schema/Grant.schema.yaml b/schema/Grant.schema.yaml
@@ -2,7 +2,7 @@ title: Grant
 '@id': schema:Grant
 extends: Thing
 role: tertiary
-status: unstable
+status: stable
 category: other
 description: A grant, typically financial or otherwise quantifiable, of resources.
 properties:

diff --git a/schema/InlineContent.schema.yaml b/schema/InlineContent.schema.yaml
@@ -1,5 +1,6 @@
 title: InlineContent
 category: text
+status: stable
 description: Union type for valid inline content.
 $comment: |
   Note that this definition currently does not include

diff --git a/schema/List.schema.yaml b/schema/List.schema.yaml
@@ -3,7 +3,7 @@ title: List
 extends: Entity
 category: text
 role: secondary
-status: unstable
+status: stable
 description: A list of items.
 $comment: |
   This is an implementation, and renaming, of schema.org [`ItemList`](https://schema.org/ItemList).

diff --git a/schema/Math.schema.yaml b/schema/Math.schema.yaml
@@ -2,7 +2,7 @@ title: Math
 '@id': stencila:Math
 extends: Entity
 role: base
-status: unstable
+status: stable
 category: math
 description: A mathematical variable or equation.
 $comment: |

diff --git a/schema/MathBlock.schema.yaml b/schema/MathBlock.schema.yaml
@@ -2,7 +2,7 @@ title: MathBlock
 '@id': stencila:MathBlock
 extends: Math
 role: secondary
-status: unstable
+status: stable
 category: math
 description: A block of math, e.g an equation, to be treated as block content.
 properties:

diff --git a/schema/MathFragment.schema.yaml b/schema/MathFragment.schema.yaml
@@ -2,7 +2,7 @@ title: MathFragment
 '@id': stencila:MathFragment
 extends: Math
 role: secondary
-status: unstable
+status: stable
 category: math
 description: A fragment of math, e.g a variable name, to be treated as inline content.
 properties: {}
diff --git a/schema/MonetaryGrant.schema.yaml b/schema/MonetaryGrant.schema.yaml
@@ -2,7 +2,7 @@ title: MonetaryGrant
 '@id': schema:MonetaryGrant
 extends: Grant
 role: tertiary
-status: unstable
+status: stable
 category: other
 description: A monetary grant.
 properties:

diff --git a/schema/Node.schema.yaml b/schema/Node.schema.yaml
@@ -1,5 +1,6 @@
 title: Node
 category: other
+status: unstable
 description: Union type for all valid nodes.
 $comment: |
   The order of these types is important because it determines the

diff --git a/schema/Null.schema.yaml b/schema/Null.schema.yaml
@@ -1,5 +1,6 @@
 title: 'Null'
 '@id': stencila:Null
 category: data
+status: stable
 description: The null value
 type: 'null'
diff --git a/schema/Number.schema.yaml b/schema/Number.schema.yaml
@@ -1,5 +1,6 @@
 title: Number
 '@id': schema:Number
 category: data
+status: stable
 description: A value that is a number
 type: number
diff --git a/schema/Object.schema.yaml b/schema/Object.schema.yaml
@@ -1,5 +1,6 @@
 title: Object
 '@id': stencila:Object
 category: data
+status: stable
 description: A value comprised of keyed values.
 type: object
diff --git a/schema/Organization.schema.yaml b/schema/Organization.schema.yaml
@@ -2,7 +2,7 @@ title: Organization
 '@id': schema:Organization
 extends: Thing
 role: secondary
-status: unstable
+status: stable
 category: other
 description: An organization such as a school, NGO, corporation, club, etc.
 properties:

diff --git a/schema/Parameter.schema.yaml b/schema/Parameter.schema.yaml
@@ -2,7 +2,7 @@ title: Parameter
 '@id': stencila:Parameter
 extends: Variable
 role: secondary
-status: unstable
+status: experimental
 category: code
 description: A parameter that can be set and used in evaluated code.
 properties:

diff --git a/schema/PublicationIssue.schema.yaml b/schema/PublicationIssue.schema.yaml
@@ -3,7 +3,7 @@ title: PublicationIssue
 extends: CreativeWork
 category: works
 role: secondary
-status: unstable
+status: stable
 description: |
   A part of a successively published publication such as a periodical or publication
   volume, often numbered.

diff --git a/schema/PublicationVolume.schema.yaml b/schema/PublicationVolume.schema.yaml
@@ -3,7 +3,7 @@ title: PublicationVolume
 extends: CreativeWork
 category: works
 role: secondary
-status: unstable
+status: stable
 description: |
   A part of a successively published publication such as a periodical or multi-volume work.
 $comment: |

diff --git a/schema/SoftwareApplication.schema.yaml b/schema/SoftwareApplication.schema.yaml
@@ -3,7 +3,7 @@ title: SoftwareApplication
 extends: CreativeWork
 category: works
 role: primary
-status: unstable
+status: stable
 description: |
   A software application.
 $comment: |

diff --git a/schema/SoftwareEnvironment.schema.yaml b/schema/SoftwareEnvironment.schema.yaml
@@ -2,7 +2,7 @@ title: SoftwareEnvironment
 '@id': stencila:SoftwareEnvironment
 extends: Thing
 role: primary
-status: unstable
+status: experimental
 category: code
 description: A computational environment.
 properties:

diff --git a/schema/SoftwareSession.schema.yaml b/schema/SoftwareSession.schema.yaml
@@ -2,7 +2,7 @@ title: SoftwareSession
 '@id': stencila:SoftwareSession
 extends: Thing
 role: primary
-status: unstable
+status: experimental
 category: code
 description: |
   Definition of a compute session, including its software and compute resource

diff --git a/schema/SoftwareSourceCode.schema.yaml b/schema/SoftwareSourceCode.schema.yaml
@@ -3,7 +3,7 @@ title: SoftwareSourceCode
 extends: CreativeWork
 category: works
 role: primary
-status: unstable
+status: stable
 description: |
   Computer programming source code. Example: Full (compile ready) solutions, code snippet samples, scripts, templates.
 properties:

diff --git a/schema/String.schema.yaml b/schema/String.schema.yaml
@@ -1,5 +1,6 @@
 title: String
 '@id': schema:Text
 category: data
+status: stable
 description: A value comprised of a string of characters
 type: string
diff --git a/schema/Variable.schema.yaml b/schema/Variable.schema.yaml
@@ -2,7 +2,7 @@ title: Variable
 '@id': stencila:Variable
 extends: Entity
 role: secondary
-status: unstable
+status: experimental
 category: code
 description: A variable representing a name / value pair.
 properties:

diff --git a/schema/VolumeMount.schema.yaml b/schema/VolumeMount.schema.yaml
@@ -2,7 +2,7 @@ title: VolumeMount
 '@id': stencila:VolumeMount
 extends: Thing
 role: tertiary
-status: unstable
+status: experimental
 category: code
 description: |
   Describes a volume mount from a host to container.

diff --git a/ts/docs.ts b/ts/docs.ts
@@ -281,6 +281,7 @@ async function schema2Article(schema: JsonSchema): Promise<Article> {
     title = 'Untitled',
     '@id': id = '',
     anyOf = [],
+    status = 'experimental',
     description = '',
     properties = {},
     required = [],
@@ -310,6 +311,20 @@ async function schema2Article(schema: JsonSchema): Promise<Article> {
         ]
       : []
 
+  const statusNote =
+    status !== 'stable'
+      ? [
+          paragraph({
+            content: [
+              'This schema type is marked as ',
+              strong({ content: [status] }),
+              status === 'experimental' ? ' 🧪' : ' ⚠️',
+              ' and is subject to change.',
+            ],
+          }),
+        ]
+      : []
+
   let membersTable
   if (anyOf.length > 0) {
     const tableHeader = tableRow({
@@ -469,6 +484,8 @@ async function schema2Article(schema: JsonSchema): Promise<Article> {
 
       ...commentContent,
 
+      ...statusNote,
+
       ...(membersTable !== undefined
         ? [heading({ content: ['Members'], depth: 2 }), membersTable]
         : []),

diff --git a/ts/schema.ts b/ts/schema.ts
@@ -44,10 +44,6 @@ const recordGuard = (a: unknown): a is Record<string | number, unknown> =>
 
 /**
  * Generate `public/*.schema.json` files from `schema/*.schema.yaml` files.
- *
- * Does NOT write out `status: experimental` schemas, since
- * they are likely to cause more breaking changes than `stable`, or `unstable`
- * schemas.
  */
 export async function build(cleanup = true): Promise<void> {
   // Clean up old files
@@ -105,12 +101,6 @@ export async function build(cleanup = true): Promise<void> {
   await fs.ensureDir('public')
   await Promise.all(
     Array.from(schemas.entries()).map(async ([title, schema]) => {
-      if (schema.status === 'experimental') {
-        log.info(
-          `Schema "${title}" is marked as status experimental so will not be published`
-        )
-        return
-      }
       const destPath = path.join(SCHEMA_DEST_DIR, title + '.schema.json')
       await fs.writeJSON(destPath, schema, { spaces: 2 })
     })
@@ -150,7 +140,7 @@ const checkSchema = (
   allIds: { [key: string]: string }
 ): boolean => {
   let valid = true
-  const { title, extends: extends_, description, properties } = schema
+  const { title, extends: extends_, description, status, properties } = schema
 
   log.debug(`Checking type schema "${title}".`)
   if (title === undefined) return true
@@ -168,13 +158,18 @@ const checkSchema = (
     error(`${title} is not a valid JSON Schema:\n${ajv.errors}`)
   }
 
+  // Should have a valid description
   const maxDescriptionLength = 120
-
-  // All schemas should have a description
-  if (description === undefined) error(`${title} is missing description`)
+  if (description === undefined) error(`${title} schema is missing description`)
   else if (description.length > maxDescriptionLength)
     error(`${title}.description is too long`)
 
+  // Should have a valid status
+  const validStatuses = ['stable', 'unstable', 'experimental']
+  if (status === undefined) error(`${title} schema is missing status`)
+  else if (!validStatuses.includes(status))
+    error(`${title}.status should be in ${validStatuses}`)
+
   // Type schemas have necessary properties and extends is valid
   if (properties !== undefined) {
     const id = schema['@id']
@@ -377,10 +372,6 @@ const processSchema = (
         }
       }
 
-      // Do not affect parent or other ancestors if this
-      // schema is experimental
-      if (schema.status === 'experimental') return
-
       // Add to parent's children
       parent.children =
         parent.children === undefined