fix(Schema): Move Entity back to top of Node list

Emphasize more in comments why this is important.
stencila · Feb 17, 2022 · 67080da · 67080da
1 parent 67a2800
commit 67080da
Show file tree

Hide file tree

Showing 7 changed files with 16 additions and 12 deletions.
diff --git a/python/stencila/schema/types.py b/python/stencila/schema/types.py
@@ -4521,7 +4521,7 @@ class CitationIntentEnumeration(Enum):
 Union type for all types of nodes in this schema, including primitives and
     entities
 """
-Node = Union["ArrayValidator", "Article", "AudioObject", "BooleanValidator", "Brand", "CitationIntentEnumeration", "Cite", "CiteGroup", "Claim", "Code", "CodeBlock", "CodeChunk", "CodeError", "CodeExecutable", "CodeExpression", "CodeFragment", "Collection", "Comment", "ConstantValidator", "ContactPoint", "CreativeWork", "Datatable", "DatatableColumn", "Date", "DefinedTerm", "Delete", "Emphasis", "EnumValidator", "Enumeration", "Figure", "Function", "Grant", "Heading", "ImageObject", "Include", "IntegerValidator", "Link", "List", "ListItem", "Mark", "Math", "MathBlock", "MathFragment", "MediaObject", "MonetaryGrant", "NontextualAnnotation", "Note", "NumberValidator", "Organization", "Paragraph", "Parameter", "Periodical", "Person", "PostalAddress", "Product", "PropertyValue", "PublicationIssue", "PublicationVolume", "Quote", "QuoteBlock", "Review", "SoftwareApplication", "SoftwareEnvironment", "SoftwareSession", "SoftwareSourceCode", "StringValidator", "Strong", "Subscript", "Superscript", "Table", "TableCell", "TableRow", "ThematicBreak", "Thing", "TupleValidator", "Validator", "Variable", "VideoObject", "VolumeMount", "Entity", None, "Boolean", "Integer", "Number", "String", "Object", "Array"]
+Node = Union["Entity", "ArrayValidator", "Article", "AudioObject", "BooleanValidator", "Brand", "CitationIntentEnumeration", "Cite", "CiteGroup", "Claim", "Code", "CodeBlock", "CodeChunk", "CodeError", "CodeExecutable", "CodeExpression", "CodeFragment", "Collection", "Comment", "ConstantValidator", "ContactPoint", "CreativeWork", "Datatable", "DatatableColumn", "Date", "DefinedTerm", "Delete", "Emphasis", "EnumValidator", "Enumeration", "Figure", "Function", "Grant", "Heading", "ImageObject", "Include", "IntegerValidator", "Link", "List", "ListItem", "Mark", "Math", "MathBlock", "MathFragment", "MediaObject", "MonetaryGrant", "NontextualAnnotation", "Note", "NumberValidator", "Organization", "Paragraph", "Parameter", "Periodical", "Person", "PostalAddress", "Product", "PropertyValue", "PublicationIssue", "PublicationVolume", "Quote", "QuoteBlock", "Review", "SoftwareApplication", "SoftwareEnvironment", "SoftwareSession", "SoftwareSourceCode", "StringValidator", "Strong", "Subscript", "Superscript", "Table", "TableCell", "TableRow", "ThematicBreak", "Thing", "TupleValidator", "Validator", "Variable", "VideoObject", "VolumeMount", None, "Boolean", "Integer", "Number", "String", "Object", "Array"]
 
 
 """

diff --git a/r/R/types.R b/r/R/types.R
@@ -4600,7 +4600,7 @@ MediaObjectTypes <- Union(MediaObject, AudioObject, ImageObject, VideoObject)
 #'
 #' @return A `list` of class `Union` describing valid subtypes of this type
 #' @export
-Node <- Union(ArrayValidator, Article, AudioObject, BooleanValidator, Brand, CitationIntentEnumeration, Cite, CiteGroup, Claim, Code, CodeBlock, CodeChunk, CodeError, CodeExecutable, CodeExpression, CodeFragment, Collection, Comment, ConstantValidator, ContactPoint, CreativeWork, Datatable, DatatableColumn, Date, DefinedTerm, Delete, Emphasis, EnumValidator, Enumeration, Figure, Function, Grant, Heading, ImageObject, Include, IntegerValidator, Link, List, ListItem, Mark, Math, MathBlock, MathFragment, MediaObject, MonetaryGrant, NontextualAnnotation, Note, NumberValidator, Organization, Paragraph, Parameter, Periodical, Person, PostalAddress, Product, PropertyValue, PublicationIssue, PublicationVolume, Quote, QuoteBlock, Review, SoftwareApplication, SoftwareEnvironment, SoftwareSession, SoftwareSourceCode, StringValidator, Strong, Subscript, Superscript, Table, TableCell, TableRow, ThematicBreak, Thing, TupleValidator, Validator, Variable, VideoObject, VolumeMount, Entity, "NULL", "logical", "numeric", "character", "list", Array(Any()))
+Node <- Union(Entity, ArrayValidator, Article, AudioObject, BooleanValidator, Brand, CitationIntentEnumeration, Cite, CiteGroup, Claim, Code, CodeBlock, CodeChunk, CodeError, CodeExecutable, CodeExpression, CodeFragment, Collection, Comment, ConstantValidator, ContactPoint, CreativeWork, Datatable, DatatableColumn, Date, DefinedTerm, Delete, Emphasis, EnumValidator, Enumeration, Figure, Function, Grant, Heading, ImageObject, Include, IntegerValidator, Link, List, ListItem, Mark, Math, MathBlock, MathFragment, MediaObject, MonetaryGrant, NontextualAnnotation, Note, NumberValidator, Organization, Paragraph, Parameter, Periodical, Person, PostalAddress, Product, PropertyValue, PublicationIssue, PublicationVolume, Quote, QuoteBlock, Review, SoftwareApplication, SoftwareEnvironment, SoftwareSession, SoftwareSourceCode, StringValidator, Strong, Subscript, Superscript, Table, TableCell, TableRow, ThematicBreak, Thing, TupleValidator, Validator, Variable, VideoObject, VolumeMount, "NULL", "logical", "numeric", "character", "list", Array(Any()))
 
 
 #' Union type for all primitives values

diff --git a/rust/kernel-micro/src/lib.rs b/rust/kernel-micro/src/lib.rs
@@ -719,9 +719,11 @@ async fn receive_results<R1: AsyncBufRead + Unpin, R2: AsyncBufRead + Unpin>(
         .into_iter()
         .map(|output| -> Node {
             match serde_json::from_str(&output) {
+                // A plain JSON object (ie.. not matching matching any of the entity types)
+                // will be deserialized to a plain `Entity` (with all properties get dropped)
+                // by `serde`. However, we want it to be an `Object` (wil properties retained)
+                // so catch that case.
                 Ok(Node::Entity(..)) => {
-                    // An `Entity` will get matched before an `Object` but is less useful (all
-                    // the properties get dropped) so catch this and parse as an object.
                     let object =
                         serde_json::from_str::<Object>(&output).unwrap_or_else(|_| Object::new());
                     Node::Object(object)

diff --git a/rust/schema/src/schemas.rs b/rust/schema/src/schemas.rs
@@ -61,7 +61,7 @@ pub const SCHEMAS: &[(&str, &str)] = &[
     ("MediaObject", r#"{"title":"MediaObject","required":["type","contentUrl"],"examples":[{"type":"MediaObject","bitrate":"44","contentSize":"2","contentUrl":"http://www.example.com/file.mp3","encodingFormat":"audio/mpeg3","embedUrl":"http://www.example.com/full_size/file.mp3"}],"type":"object","propertyAliases":{"alternateName":"alternateNames","identifier":"identifiers","image":"images","author":"authors","comment":"comments","date":"datePublished","editor":"editors","funder":"funders","keyword":"keywords","license":"licenses","maintainer":"maintainers","hasParts":"parts","part":"parts","citations":"references","reference":"references","headline":"title","encodingFormat":"mediaType"},"additionalProperties":false,"properties":{"id":{"type":"string"},"alternateNames":{"type":"array","items":{"type":"string"},"aliases":["alternateName"]},"description":{"anyOf":[{"type":"array","items":{"$ref":"BlockContent.schema.json"}},{"type":"array","items":{"$ref":"InlineContent.schema.json"},"minItems":2},{"type":"string"}]},"identifiers":{"type":"array","items":{"anyOf":[{"$ref":"PropertyValue.schema.json"},{"type":"string"}]},"aliases":["identifier"]},"images":{"type":"array","items":{"anyOf":[{"$ref":"ImageObject.schema.json"},{"type":"string","format":"uri"}]},"aliases":["image"]},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"about":{"type":"array","items":{"$ref":"ThingTypes.schema.json"}},"authors":{"allOf":[{"parser":"scsi"},{"type":"array","items":{"anyOf":[{"$ref":"Person.schema.json"},{"$ref":"Organization.schema.json"}]}}],"aliases":["author"]},"comments":{"type":"array","items":{"$ref":"Comment.schema.json"},"aliases":["comment"]},"content":{"anyOf":[{"type":"array","items":{"$ref":"Node.schema.json"}},{"type":"string"}]},"dateCreated":{"allOf":[{"$ref":"Date.schema.json"}]},"dateReceived":{"allOf":[{"$ref":"Date.schema.json"}]},"dateAccepted":{"allOf":[{"$ref":"Date.schema.json"}]},"dateModified":{"allOf":[{"$ref":"Date.schema.json"}]},"datePublished":{"aliases":["date"],"allOf":[{"$ref":"Date.schema.json"}]},"editors":{"type":"array","items":{"$ref":"Person.schema.json"},"aliases":["editor"]},"funders":{"type":"array","items":{"anyOf":[{"$ref":"Person.schema.json"},{"$ref":"Organization.schema.json"}]},"aliases":["funder"]},"fundedBy":{"type":"array","items":{"anyOf":[{"$ref":"Grant.schema.json"},{"$ref":"MonetaryGrant.schema.json"}]}},"genre":{"allOf":[{"parser":"csi"},{"type":"array","items":{"type":"string"}}]},"keywords":{"allOf":[{"parser":"csi"},{"type":"array","items":{"type":"string"}}],"aliases":["keyword"]},"isPartOf":{"$ref":"CreativeWorkTypes.schema.json"},"licenses":{"type":"array","items":{"anyOf":[{"$ref":"CreativeWorkTypes.schema.json"},{"type":"string","format":"uri"}]},"aliases":["license"]},"maintainers":{"type":"array","items":{"anyOf":[{"$ref":"Person.schema.json"},{"$ref":"Organization.schema.json"}]},"aliases":["maintainer"]},"parts":{"aliases":["hasParts","part"],"type":"array","items":{"$ref":"CreativeWorkTypes.schema.json"}},"publisher":{"anyOf":[{"$ref":"Person.schema.json"},{"$ref":"Organization.schema.json"}]},"references":{"aliases":["citations","reference"],"type":"array","items":{"anyOf":[{"$ref":"CreativeWorkTypes.schema.json"},{"type":"string"}]}},"text":{"type":"string"},"title":{"aliases":["headline"],"anyOf":[{"type":"array","items":{"$ref":"InlineContent.schema.json"},"minItems":2},{"type":"string"}]},"version":{"anyOf":[{"type":"string"},{"type":"number"}]},"bitrate":{"type":"number"},"contentSize":{"type":"number"},"contentUrl":{"type":"string"},"embedUrl":{"type":"string"},"mediaType":{"aliases":["encodingFormat"],"type":"string","pattern":"^\\w+/[-+.\\w]+$"}}}"#),
     ("MediaObjectTypes", r#"{"title":"MediaObjectTypes","anyOf":[{"$ref":"MediaObject.schema.json"},{"$ref":"AudioObject.schema.json"},{"$ref":"ImageObject.schema.json"},{"$ref":"VideoObject.schema.json"}]}"#),
     ("MonetaryGrant", r#"{"title":"MonetaryGrant","type":"object","propertyAliases":{"alternateName":"alternateNames","identifier":"identifiers","image":"images","fundedItem":"fundedItems","sponsor":"sponsors","funder":"funders"},"additionalProperties":false,"required":["type"],"properties":{"id":{"type":"string"},"alternateNames":{"type":"array","items":{"type":"string"},"aliases":["alternateName"]},"description":{"anyOf":[{"type":"array","items":{"$ref":"BlockContent.schema.json"}},{"type":"array","items":{"$ref":"InlineContent.schema.json"},"minItems":2},{"type":"string"}]},"identifiers":{"type":"array","items":{"anyOf":[{"$ref":"PropertyValue.schema.json"},{"type":"string"}]},"aliases":["identifier"]},"images":{"type":"array","items":{"anyOf":[{"$ref":"ImageObject.schema.json"},{"type":"string","format":"uri"}]},"aliases":["image"]},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"fundedItems":{"type":"array","items":{"$ref":"Thing.schema.json"},"aliases":["fundedItem"]},"sponsors":{"type":"array","items":{"anyOf":[{"$ref":"Person.schema.json"},{"$ref":"Organization.schema.json"}]},"aliases":["sponsor"]},"amounts":{"type":"number"},"funders":{"type":"array","items":{"anyOf":[{"$ref":"Person.schema.json"},{"$ref":"Organization.schema.json"}]},"aliases":["funder"]}}}"#),
-    ("Node", r#"{"title":"Node","anyOf":[{"$ref":"ArrayValidator.schema.json"},{"$ref":"Article.schema.json"},{"$ref":"AudioObject.schema.json"},{"$ref":"BooleanValidator.schema.json"},{"$ref":"Brand.schema.json"},{"$ref":"CitationIntentEnumeration.schema.json"},{"$ref":"Cite.schema.json"},{"$ref":"CiteGroup.schema.json"},{"$ref":"Claim.schema.json"},{"$ref":"Code.schema.json"},{"$ref":"CodeBlock.schema.json"},{"$ref":"CodeChunk.schema.json"},{"$ref":"CodeError.schema.json"},{"$ref":"CodeExecutable.schema.json"},{"$ref":"CodeExpression.schema.json"},{"$ref":"CodeFragment.schema.json"},{"$ref":"Collection.schema.json"},{"$ref":"Comment.schema.json"},{"$ref":"ConstantValidator.schema.json"},{"$ref":"ContactPoint.schema.json"},{"$ref":"CreativeWork.schema.json"},{"$ref":"Datatable.schema.json"},{"$ref":"DatatableColumn.schema.json"},{"$ref":"Date.schema.json"},{"$ref":"DefinedTerm.schema.json"},{"$ref":"Delete.schema.json"},{"$ref":"Emphasis.schema.json"},{"$ref":"EnumValidator.schema.json"},{"$ref":"Enumeration.schema.json"},{"$ref":"Figure.schema.json"},{"$ref":"Function.schema.json"},{"$ref":"Grant.schema.json"},{"$ref":"Heading.schema.json"},{"$ref":"ImageObject.schema.json"},{"$ref":"Include.schema.json"},{"$ref":"IntegerValidator.schema.json"},{"$ref":"Link.schema.json"},{"$ref":"List.schema.json"},{"$ref":"ListItem.schema.json"},{"$ref":"Mark.schema.json"},{"$ref":"Math.schema.json"},{"$ref":"MathBlock.schema.json"},{"$ref":"MathFragment.schema.json"},{"$ref":"MediaObject.schema.json"},{"$ref":"MonetaryGrant.schema.json"},{"$ref":"NontextualAnnotation.schema.json"},{"$ref":"Note.schema.json"},{"$ref":"NumberValidator.schema.json"},{"$ref":"Organization.schema.json"},{"$ref":"Paragraph.schema.json"},{"$ref":"Parameter.schema.json"},{"$ref":"Periodical.schema.json"},{"$ref":"Person.schema.json"},{"$ref":"PostalAddress.schema.json"},{"$ref":"Product.schema.json"},{"$ref":"PropertyValue.schema.json"},{"$ref":"PublicationIssue.schema.json"},{"$ref":"PublicationVolume.schema.json"},{"$ref":"Quote.schema.json"},{"$ref":"QuoteBlock.schema.json"},{"$ref":"Review.schema.json"},{"$ref":"SoftwareApplication.schema.json"},{"$ref":"SoftwareEnvironment.schema.json"},{"$ref":"SoftwareSession.schema.json"},{"$ref":"SoftwareSourceCode.schema.json"},{"$ref":"StringValidator.schema.json"},{"$ref":"Strong.schema.json"},{"$ref":"Subscript.schema.json"},{"$ref":"Superscript.schema.json"},{"$ref":"Table.schema.json"},{"$ref":"TableCell.schema.json"},{"$ref":"TableRow.schema.json"},{"$ref":"ThematicBreak.schema.json"},{"$ref":"Thing.schema.json"},{"$ref":"TupleValidator.schema.json"},{"$ref":"Validator.schema.json"},{"$ref":"Variable.schema.json"},{"$ref":"VideoObject.schema.json"},{"$ref":"VolumeMount.schema.json"},{"$ref":"Entity.schema.json"},{"$ref":"Null.schema.json"},{"$ref":"Boolean.schema.json"},{"$ref":"Integer.schema.json"},{"$ref":"Number.schema.json"},{"$ref":"String.schema.json"},{"$ref":"Object.schema.json"},{"$ref":"Array.schema.json"}]}"#),
+    ("Node", r#"{"title":"Node","anyOf":[{"$ref":"Entity.schema.json"},{"$ref":"ArrayValidator.schema.json"},{"$ref":"Article.schema.json"},{"$ref":"AudioObject.schema.json"},{"$ref":"BooleanValidator.schema.json"},{"$ref":"Brand.schema.json"},{"$ref":"CitationIntentEnumeration.schema.json"},{"$ref":"Cite.schema.json"},{"$ref":"CiteGroup.schema.json"},{"$ref":"Claim.schema.json"},{"$ref":"Code.schema.json"},{"$ref":"CodeBlock.schema.json"},{"$ref":"CodeChunk.schema.json"},{"$ref":"CodeError.schema.json"},{"$ref":"CodeExecutable.schema.json"},{"$ref":"CodeExpression.schema.json"},{"$ref":"CodeFragment.schema.json"},{"$ref":"Collection.schema.json"},{"$ref":"Comment.schema.json"},{"$ref":"ConstantValidator.schema.json"},{"$ref":"ContactPoint.schema.json"},{"$ref":"CreativeWork.schema.json"},{"$ref":"Datatable.schema.json"},{"$ref":"DatatableColumn.schema.json"},{"$ref":"Date.schema.json"},{"$ref":"DefinedTerm.schema.json"},{"$ref":"Delete.schema.json"},{"$ref":"Emphasis.schema.json"},{"$ref":"EnumValidator.schema.json"},{"$ref":"Enumeration.schema.json"},{"$ref":"Figure.schema.json"},{"$ref":"Function.schema.json"},{"$ref":"Grant.schema.json"},{"$ref":"Heading.schema.json"},{"$ref":"ImageObject.schema.json"},{"$ref":"Include.schema.json"},{"$ref":"IntegerValidator.schema.json"},{"$ref":"Link.schema.json"},{"$ref":"List.schema.json"},{"$ref":"ListItem.schema.json"},{"$ref":"Mark.schema.json"},{"$ref":"Math.schema.json"},{"$ref":"MathBlock.schema.json"},{"$ref":"MathFragment.schema.json"},{"$ref":"MediaObject.schema.json"},{"$ref":"MonetaryGrant.schema.json"},{"$ref":"NontextualAnnotation.schema.json"},{"$ref":"Note.schema.json"},{"$ref":"NumberValidator.schema.json"},{"$ref":"Organization.schema.json"},{"$ref":"Paragraph.schema.json"},{"$ref":"Parameter.schema.json"},{"$ref":"Periodical.schema.json"},{"$ref":"Person.schema.json"},{"$ref":"PostalAddress.schema.json"},{"$ref":"Product.schema.json"},{"$ref":"PropertyValue.schema.json"},{"$ref":"PublicationIssue.schema.json"},{"$ref":"PublicationVolume.schema.json"},{"$ref":"Quote.schema.json"},{"$ref":"QuoteBlock.schema.json"},{"$ref":"Review.schema.json"},{"$ref":"SoftwareApplication.schema.json"},{"$ref":"SoftwareEnvironment.schema.json"},{"$ref":"SoftwareSession.schema.json"},{"$ref":"SoftwareSourceCode.schema.json"},{"$ref":"StringValidator.schema.json"},{"$ref":"Strong.schema.json"},{"$ref":"Subscript.schema.json"},{"$ref":"Superscript.schema.json"},{"$ref":"Table.schema.json"},{"$ref":"TableCell.schema.json"},{"$ref":"TableRow.schema.json"},{"$ref":"ThematicBreak.schema.json"},{"$ref":"Thing.schema.json"},{"$ref":"TupleValidator.schema.json"},{"$ref":"Validator.schema.json"},{"$ref":"Variable.schema.json"},{"$ref":"VideoObject.schema.json"},{"$ref":"VolumeMount.schema.json"},{"$ref":"Null.schema.json"},{"$ref":"Boolean.schema.json"},{"$ref":"Integer.schema.json"},{"$ref":"Number.schema.json"},{"$ref":"String.schema.json"},{"$ref":"Object.schema.json"},{"$ref":"Array.schema.json"}]}"#),
     ("NontextualAnnotation", r#"{"title":"NontextualAnnotation","type":"object","additionalProperties":false,"required":["type","content"],"propertyAliases":{},"properties":{"id":{"type":"string"},"content":{"type":"array","items":{"$ref":"InlineContent.schema.json"}}}}"#),
     ("Note", r#"{"title":"Note","required":["type","content"],"type":"object","additionalProperties":false,"propertyAliases":{},"properties":{"id":{"type":"string"},"noteType":{"type":"string","enum":["Footnote","Endnote","Sidenote"]},"content":{"type":"array","items":{"$ref":"BlockContent.schema.json"}}}}"#),
     ("Null", r#"{"title":"Null","type":"null"}"#),

diff --git a/rust/schema/src/types.rs b/rust/schema/src/types.rs
@@ -5281,6 +5281,7 @@ pub enum MediaObjectTypes {
 #[derive(Clone, Debug, AsRefStr, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum Node {
+    Entity(Entity),
     ArrayValidator(ArrayValidator),
     Article(Article),
     AudioObject(AudioObject),
@@ -5360,7 +5361,6 @@ pub enum Node {
     Variable(Variable),
     VideoObject(VideoObject),
     VolumeMount(VolumeMount),
-    Entity(Entity),
     Null(Null),
     Boolean(Boolean),
     Integer(Integer),

diff --git a/schema/src/schema.ts b/schema/src/schema.ts
@@ -446,20 +446,22 @@ const parentSchema = (
 /**
  * Add all entity and primitive types to the `Node` union schema.
  *
- * The order of the types is important as it can influence the
- * order of attempted de-serialization and coercion.
+ * The order of the types is important as it influences the
+ * order of attempted de-serialization and coercion (in Rust and possibly other 
+ * languages). Furthermore, some code may rely on the order. So test before
+ * changing.
  */
 const updateNodeSchema = (schemas: Map<string, JsonSchema>): void => {
   const entitySchema = schemas.get('Entity') as JsonSchema
   const primitiveSchema = schemas.get('Primitive') as JsonSchema
   const nodeSchema = schemas.get('Node') as JsonSchema
   nodeSchema.anyOf = [
-    ...(entitySchema.descendants ?? []).map((descendant) => ({
-      $ref: `${descendant}.schema.json`,
-    })),
     {
       $ref: `Entity.schema.json`,
     },
+    ...(entitySchema.descendants ?? []).map((descendant) => ({
+      $ref: `${descendant}.schema.json`,
+    })),
     ...(primitiveSchema.anyOf ?? []),
   ]
   schemas.set('Node', nodeSchema)

diff --git a/schema/src/types.ts b/schema/src/types.ts
@@ -2188,6 +2188,7 @@ export type MediaObjectTypes =
  * Union type for all types of nodes in this schema, including primitives and entities
  */
 export type Node =
+  | Entity
   | ArrayValidator
   | Article
   | AudioObject
@@ -2267,7 +2268,6 @@ export type Node =
   | Variable
   | VideoObject
   | VolumeMount
-  | Entity
   | null
   | boolean
   | Integer