From 4c1843fe2ad38fd07a95fef3199044159a1e6a91 Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Fri, 29 Dec 2023 08:51:25 -0500 Subject: [PATCH] Support for Let Expressions (#478) * Cleaned up schema, adjusting some documentation and grouping constraint constructs in a section of the schema. * Added support for declaration of let expressions in constraints. * Added documentation about the let expression in the specification. * Added let example to specification. * Fixed some other inconsistencies in the Metaschema XML schema. --- examples/computer-example.xml | 2 +- schema/xml/metaschema-markup-line.xsd | 1 - schema/xml/metaschema.xsd | 985 +++++++++--------- .../specification/syntax/constraints.md | 44 + 4 files changed, 535 insertions(+), 497 deletions(-) diff --git a/examples/computer-example.xml b/examples/computer-example.xml index d86ff1058..a57444b6e 100644 --- a/examples/computer-example.xml +++ b/examples/computer-example.xml @@ -1,6 +1,6 @@ Computer Model 0.0.5 diff --git a/schema/xml/metaschema-markup-line.xsd b/schema/xml/metaschema-markup-line.xsd index c430944f9..ac3b941ff 100644 --- a/schema/xml/metaschema-markup-line.xsd +++ b/schema/xml/metaschema-markup-line.xsd @@ -3,7 +3,6 @@ - diff --git a/schema/xml/metaschema.xsd b/schema/xml/metaschema.xsd index b44f491bb..25c30a365 100644 --- a/schema/xml/metaschema.xsd +++ b/schema/xml/metaschema.xsd @@ -69,80 +69,9 @@ --> - - - Root element of a Metaschema external constraints definition. Defines rules to be applied to an existing set of Metaschema models. - - - - - - The name of this constraint set. - - - - - The version of this constraint set. - - - - - - To import a set of Metaschema constraints from an out-of-line resource, supporting composition of constraint sets. - - - - - A relative or absolute URI for retrieving an out-of-line Metaschema definition. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Imports a set of Metaschema definitions from an out-of-line resource, supporting reuse of common information structures. + Imports a set of Metaschema modules containing exported definitions from an out-of-line resource, supporting reuse of common information structures. @@ -153,10 +82,17 @@ - + + + + A formal name for the data construct for use in documentation. + + + + - A short description of the data construct that provides basic documentation of the construct's purpose. + A short semantic description of the data construct's purpose. @@ -184,6 +120,25 @@ --> + @@ -216,6 +171,14 @@ + + + Common definition attributes that support definition referencing. + + + + + Common definition attributes that support root definition naming. @@ -233,21 +196,20 @@ + + + + + + + Common definition attributes that support instance naming. - - - - - - - - - + @@ -265,11 +227,10 @@ - + - - + + @@ -291,7 +252,6 @@ - @@ -327,8 +287,7 @@ - + @@ -340,7 +299,6 @@ - A data point to be expressed as an attribute in the XML or a name/value pair @@ -373,11 +331,10 @@ - + - - + + @@ -390,7 +347,7 @@ In JSON, an object with a nominal string value (potentially with internal inline - not fully structured - markup). In XML, an element with string or markup - content. A local definition describes and constrains the appearance of the field only in this (assembly) context. + content. @@ -399,10 +356,9 @@ - + - + @@ -412,8 +368,7 @@ - A field with assigned data type 'markup-multiline' may be designated for representation with or without a containing (wrapper) element - in XML. + A field with assigned data type 'markup-multiline' may be designated for representation with or without a containing (wrapper) element in XML. @@ -435,13 +390,6 @@ - - - A formal name for the data construct, to be presented in documentation. - - - - The JSON Base URI is nominal base URI assigned to a JSON Schema instance expressing the model defined by this Metaschema module. @@ -504,7 +452,7 @@ - + @@ -519,7 +467,7 @@ - + @@ -527,6 +475,7 @@ in XML. + @@ -584,150 +533,322 @@ - + + + + The associated construct has been deprecated at the specified version. Its use should be avoided if possible. + + + + + + + - - + + + + - + + + Within a model, indicates that only one of a set of fields or assemblies, referenced in the choice, may occur in valid instances. + + + + + + + + + + + + Within a model, a foreign element may be permitted here. + + + + + + + A short description providing basic documentation about the example's purpose. + + + + + - + + + + + + + In the XML, produces an attribute with the given name, whose value is used as a key value (aka object property name) in the JSON, enabling objects to be 'lifted' out of arrays when such values are distinct. Implies that siblings will never share values. + + + + + + + When a given referenced field or assembly must be wrapped in an outer grouping, these settings apply, including a name for the group, and how to express the grouping in the respective formats. Not necessary when a field or assembly has max-occurs='1' + + + + + + How to represent a grouping in JSON + + + + + Whether to represent a grouping explicitly in XML + + + - + - - - A violation of the constraint represents a serious fault in the content - that will prevent typical use of the content. - - - + - A violation of the constraint represents a fault in the content. This - may include issues around compatibility, integrity, consistency, etc. + Always use an array - + - A violation of the constraint represents a potential issue - with the content. + Produce a singleton for a single member (field or assembly) or an array for multiple members - + - A violation of the constraint represents a point of - interest. + For any group (one or more members) produce an object with properties for each member, using a designated flag for their key (label) values, which must be distinct - - - - Indicates a set of values to be recognized for a flag or field, with semantics asserted by an enumeration (enum). - - - - - - - - - - The given enumerated value or values are inclusive of other values ('yes') or not ('no', the default) - - - - - Determines if the given enumerated value or values within a namespace may be extended by other allowed value constraints. - - - - - - - + - - - Can be extended by constraints within the same model. - - - + - Can be extended by external constraints. + Use a wrapper element - + - Cannot be extended. + Do not use a wrapper element - - - An enumerated value for a flag or field. The value is indicated by the 'value' attribute while the element contents describe the intended semantics for documentation. - - - - - - A value recognized for a flag or field. - - - - - - - - - - - The associated construct has been deprecated at the specified version. Its use should be avoided if possible. - - - + + + + + + + + + + + + + + + + + + + + + + + A string with no leading or trailing whitespace. + + + + + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This definition is only available in the context of the current Metaschema module. + + + + + This definition will be made available to any Metaschema module that includes this one either directly or indirectly through a chain of imported Metaschema modules. + + + + + + + + + + + + + - - - - - + + - + + + + + A violation of the constraint represents a serious fault in the content + that will prevent typical use of the content. + + + + + A violation of the constraint represents a fault in the content. This + may include issues around compatibility, integrity, consistency, etc. + + + + + A violation of the constraint represents a potential issue + with the content. + + + + + A violation of the constraint represents a point of interest. + + + + + + + + + + + + - A regex subset that is conformant to both https://www.w3.org/TR/xmlschema11-2/#regexes and https://www.ecma-international.org/ecma-262/11.0/index.html#sec-patterns. + Indicates an enumeration of a set values to be recognized for a flag or field. - + + + + + + + + + The given enumerated value or values are inclusive of other values ('yes') or not ('no', the default) + + + + + Determines if the given enumerated values may be extended by other allowed value constraints. + + + + + + + + + + + Can be extended by constraints within the same module. + + + + + Can be extended by external constraints. + + + + + Cannot be extended. + + + - + + + An enumerated value for a flag or field. The value is indicated by the 'value' attribute while the element contents describe the intended semantics for documentation. + + + + + + A value recognized for a flag or field. + + + + + + + + + + A regular expression subset that conforms to both https://www.w3.org/TR/xmlschema11-2/#regexes and https://www.ecma-international.org/ecma-262/11.0/index.html#sec-patterns. + - + - Specifies the data type for which the value identified by the scope + Specifies the datatype for which the value identified by the scope attribute must conform to. @@ -735,107 +856,37 @@ - + - Specifies the target of the constraint as a Metapath expression. If the value is "." and the containing Metaschema object is a field, the constraint applies to the field's value. Otherwise, the scope value "." is not allowed to be used. + Specifies the target of the constraint as a Metaschema Metapath. If the value is "." and the containing Metaschema object is a field, the constraint applies to the field's value. Otherwise, the scope value "." is not allowed to be used. - + - - Specifies the target of the constraint as a Metapath expression. If the value is "." and the containing Metaschema object is a field, the constraint applies to the field's value. + Specifies the target of the constraint as a Metaschema Metapath. If the value is "." and the containing Metaschema object is a field, the constraint applies to the field's value. - - - - - - Constrains the allowed values for the flag. - - - - - Constrains the allowed values based on the provided regex pattern. - - - - - Checks that the specified key-field values match a key in the index with the specified name. - - - - - Checks that the specified test returns true in this evaluation context. - - - - - - - - - - Specifies the field or flag value that is used to generate the key for a given object that is a member of this index. If more than one key-field is provided, then the key is a composition of the specified key-fields. The ordering of the key-field defined the relative order of the index's key. The field or flag values pointed to must be a field value or a required flag value. + Specifies the field or flag value that is used to generate the key for a given object that is a member of this index. If more than one key-field is provided, then the key is a composition of the specified key-field objects. The ordering of the key-field objects establish the relative order of the index's key. The field or flag values pointed to are a field or flag value, which can be an empty value if not provided. Note: Multiple empty values can result in key conflicts. @@ -873,20 +924,18 @@ - + - Specifies the value objects to be included in the key constraint, or the object that contains a reference to an item in an index. If the value is ".", then the key is targeting the current Metaschema object. + Specifies a Metapath that can be evaluated to get the value objects to be included in the key constraint, or the object that contains a reference to an item in an index. If the value is ".", then the key is targeting the current Metaschema object. - - Defines an index, a check against an index, or a uniqueness constraint. @@ -902,7 +951,7 @@ - + Defines an index, a check against an index, or a uniqueness constraint. @@ -910,15 +959,14 @@ - Specifies the value objects to be included in the index constraint, or the object that contains a reference to an item in an index. If the value is ".", then the key is targeting the current Metaschema object. + Specifies a Metapath that can be evaluated to get the value objects to be included in the index constraint, or the object that contains a reference to an item in an index. If the value is ".", then the key is targeting the current Metaschema object. - - + Defines an index, a check against an index, or a uniqueness constraint. @@ -947,53 +995,26 @@ - A test that is expected to pass in this context. Presently, data typing - is not directly supported except by explicit use of data type casting functions, e.g. - xs:double() and xs:date(). + A Metapath test that is expected to pass in this context. - + - Specifies the target of the constraint as a Metaschema expression. If the value is "." and the containing Metaschema object is a field or flag, the constraint applies to the value of the field or flag. Otherwise, the scope value "." is not allowed to be used. + Specifies the target of the constraint as a Metaschema Metapath. If the value is "." and the containing Metaschema object is a field or flag, the constraint applies to the value of the field or flag. Otherwise, the scope value "." is not allowed to be used. - - - - - Constrains the allowed values for the flag or field referenced by the scope attribute. - - - - - Constrains the allowed values based on the provided regex pattern or checks that the value is conformant to the specified data type. - - - - - Checks that the specified key-field values match a key in the index with the specified name. - - - - - Checks that the specified test returns true in this evaluation context. - - - - - - + @@ -1001,7 +1022,7 @@ - Specifies the target of the constraint as a Metapath expression. If the + Specifies the target of the constraint as a Metaschema Metapath. If the value is "." and the containing Metaschema object is a field, the constraint applies to the field's value. Otherwise, the scope value "." is not allowed to be used. @@ -1025,19 +1046,91 @@ - - - + + + + + + + + + + + - Defines a new named index. Each entry in the index will have a unique key, based on the key-field elements, and an associated object value, based on the target selection.. + Declares a variable whose name is bound to the result of the Metapath expression. These variables can be used in target and other Metapath expressions used in constrains that are declared in the same context or in constraints declared in a child assembly, field, or flag. - - - Checks that the specified set of target entries have a key, based on the key-field entries that is unique. The name identifies the name of the uniqueness constraint, which can be used for error reporting, etc. - + + + + + + + + + + Constrains the allowed values for the flag. + + + + + Constrains the allowed values based on the provided regex pattern. + + + + + Checks that the specified key-field values match a key in the index with the specified name. + + + + + Checks that the specified test returns true in this evaluation context. + + + + + + + + + + + + Constrains the allowed values for the flag or field referenced by the scope attribute. + + + + + Constrains the allowed values based on the provided regex pattern or checks that the value conforms to the specified datatype. + + + + + Checks that the specified key-field values match a key in the index with the specified name. + + + + + Checks that the specified test returns true in this evaluation context. + + + + + + + + + + Defines a new named index. Each entry in the index will have a unique key, based on the key-field elements, and an associated object value, based on the target selection.. + - + + + Checks that the specified set of target entries have a key, based on the key-field entries that is unique. The name identifies the name of the uniqueness constraint, which can be used for error reporting, etc. + + + Checks that the specified set of target entries match the provided cardinality. @@ -1047,8 +1140,9 @@ + - + @@ -1056,182 +1150,83 @@ + - + - - - Within a model, indicates that only one of a set of fields or assemblies, referenced in the choice, may occur in valid instances. - - - - - - - - - - - - Within a model, a foreign element may be permitted here.. - - - - - - - - A short description of the example that provides basic documentation about the example's purpose. - - - - - - - - - - - - - - - In the XML, produces an attribute with the given name, whose value is used as a key value (aka object property name) in the JSON, enabling objects to be 'lifted' out of arrays when such values are distinct. Implies that siblings will never share values. Overloading with datatype 'ID' and naming the key 'id' is legitimate and useful. Even without ID validation, uniqueness of these values among siblings is validable. - - - - - - + + + + - When a given referenced field or assembly must be wrapped in an outer grouping, these settings apply, including a name for the group, and how to express the grouping in the respective formats. Not necessary when a field or assembly has max-occurs='1' + Root element of a Metaschema external constraints definition. Defines rules to be applied to an existing set of Metaschema models. - - - - - How to represent a grouping in JSON - - - - - Whether to represent a grouping explicitly in XML - - - - - - - - - Always use an array - - - - - Produce a singleton for a single member (field or assembly) or an array for multiple members - - - - - For any group (one or more members) produce an object with properties for each member, using a designated flag for their key (label) values, which must be distinct - - - - - - - - - Use a wrapper element - - - - - Do not use a wrapper element - - - - - - - - - - - - - - - - - - - - - - - - - - - - A string with no leading or trailing whitespace. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This definition is only available in the context of the current Metaschema module. - - - - - This definition will be made available to any Metaschema module that includes this one either directly or indirectly through a chain of imported Metaschema modules. - - - - + + + + + The name of this constraint set. + + + + + The version of this constraint set. + + + + + To import a set of Metaschema constraints from an out-of-line resource, supporting composition of constraint sets. + + + + + A relative or absolute URI for retrieving an out-of-line Metaschema definition. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/website/content/specification/syntax/constraints.md b/website/content/specification/syntax/constraints.md index 8ac96ec12..a49e9bc32 100644 --- a/website/content/specification/syntax/constraints.md +++ b/website/content/specification/syntax/constraints.md @@ -120,6 +120,50 @@ Processing errors occur when a defect in the constraint definition causes an uni - If a processing error occurs while processing a constraint, which can result from evaluating a Metapath expression, the error SHOULD be reported. - If a processing error occurs while processing a constraint, then the document instance being validated MUST NOT be considered valid. This is due to the inability to make a conclusion around validity, since some constraints were not validated due to errors. +## Let expressions + +Using the `let` element, a variable can be defined, which can be used in a Metapath expression in subsequent constraints. + +A `let` statement has a REQUIRED `@var` attribute, which defines the variable name. + +A `let` statement has a REQUIRED `@expression` attributes, which defines an Metapath expression, whose result is used to define the variable's value in the evaluation context. + +During constraint evaluation, each `let` statement MUST be evaluated in encounter order. If a previous variable is bound with the same name in the evaluation context, the new value MUST bound in a sub-context to avoid side effects. This sub-context MUST be made available to any constraints following the `let` statement declaration, and to any constraints defined on child nodes of the current context. + +During evaluation, when a variable is bound for a `let` statement, the variables value MUST be set to the result of evaluating the `@expression` using the current node as the Metapath evaluation focus. + +For example: + +Given the following fragment of a Metaschema module. + +```xml + + + + + + + + +``` + +And the following document. + +```xml + + + + + + + + + +``` + +The expect constraint would pass for each `sibling` in the `parent` named "p1", and would fail for each `sibling` in the `parent` named "p2". + + ## Enumerated values The `allowed-values` constraint is a type of Metaschema constraint that restricts field or flag value(s) based on an enumerated set of permitted values.