From 4abfaefff4367b68af76c8dc6cf55c22b380be43 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Fri, 18 Aug 2023 12:16:23 -0400 Subject: [PATCH] Update allowed-values overview As part of usnistgov/metaschema#411, use IETF BCP-14 languages as used with other parts of the specification. Change the wording to address how implementers would follow constraint directives in their processor, and align example to be like computer model themes with tutorials and other documentation. --- .../specification/syntax/constraints.md | 26 +++++++++---------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/website/content/specification/syntax/constraints.md b/website/content/specification/syntax/constraints.md index e20806adc..da8a05632 100644 --- a/website/content/specification/syntax/constraints.md +++ b/website/content/specification/syntax/constraints.md @@ -14,27 +14,25 @@ TODO: P3: Address issue https://github.com/usnistgov/metaschema/issues/325 ## Enumerated values -Additionally, flags may be constrained to a set of known values listed in advance. +One kind of Metaschema constraint is restricting assembly, field, or flag value(s) with `allowed-values` enumerations. Metaschema processors MUST process `allowed-values` enumerations as defined with the `allow-other` attribute. -This restriction can be either: +1. When the `allow-other` attribute is defined as `allow-other="no"`, the processor MUST strictly validate content instances with enumerations: only defined `enum` values are valid for the given target(s). +2. When the `allow-other` attribute is defined as `allow-other="yes"`, the processor MUST loosely validate content instances with enumerations: both `enum` values and other values are valid. +3. When the `allow-other` attribute is not explicitly defined, the Metaschema processor MUST strictly validate content instances. The implied default is `allow-other="no"`. -1. strict (values must be in the list for document validity with `allow-other="no"` attribute for an `allowed-values` element) or -2. loose (i.e. for documentation only, no effect in schemas, with `allow-other="yes"`). - -If an `allowed-values` constraint does not have the `allow-other` attribute defined, the default is `allow-other="no"`, resulting in strict validation where the only valid values are those in the list. - -Within `allowed-values` of a `constraint`, an `enum` element's `@value` attribute assigns the permissible value, while its data content provides documentation. For example: +Within `allowed-values` of a `constraint`, a Metaschema processor MUST strictly or loosely validate `enum` values with the `@value` attribute. A Metaschema processor MAY use the text value of the `enum`'s XML element as documentation for a given allowed value enumeration. Below is an example. ```xml - - Hash algorithm - Method by which a hash is derived + + Computer Form Factor + The type of computer in the example application's data model. - Documentation for one permissible option. - Documentation for another permissible option. + this text value documents the domain and information model's meaning of a laptop + this text value documents the domain and information model's meaning of a desktop - ... + ... + ``` ## `define-flag` constraints