Skip to content

Commit

Permalink
Adding more examples and other touch-ups.
Browse files Browse the repository at this point in the history
  • Loading branch information
@aj-stein-nist
aj-stein-nist committed Aug 18, 2023
1 parent b53ddf6 commit e6079da
Showing 1 changed file with 48 additions and 6 deletions.
54 changes: 48 additions & 6 deletions website/content/specification/syntax/constraints.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,14 @@ One kind of Metaschema constraint is restricting assembly, field, or flag value(

### `define-flag` constraints

An assembly can define `allowed-values` constraints. The constraint MUST have an `allowed-values` values element with one or more `enum` elements for each value subject to strict or loose validation. Each `enum` element MUST have a `value` attribute and MAY have a text value for documenting the allowed value. 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.
A flag can define `allowed-values` constraints. The constraint MUST have an `allowed-values` values element with one or more `enum` elements for each value subject to strict or loose validation. Each `enum` element MUST have a `value` attribute and MAY have a text value for documenting the allowed value. 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
<define-flag name="form-factor">
<formal>Computer Form Factor</formal-name>
<description>The type of computer in the example application's data model.</description>
<description>The type of computer in the example application's data model</description>
<constraint>
<allowed-values allow-other="yes">
<allowed-values allow-other="no">
<enum value="laptop">this text value documents the domain and information model's meaning of a laptop</enum>
<enum value="desktop">this text value documents the domain and information model's meaning of a desktop</enum>
</allowed-values>
Expand All @@ -44,9 +44,9 @@ A field `allowed-values` constraint is syntactically equivalent to such a constr
```xml
<define-field name="form-factor">
<formal>Computer Form Factor</formal-name>
<description>The type of computer in the example application's data model.</description>
<description>The type of computer in the example application's data model</description>
<constraint>
<allowed-values allow-other="yes">
<allowed-values allow-other="no">
<enum value="laptop">this text value documents the domain and information model's meaning of a laptop</enum>
<enum value="desktop">this text value documents the domain and information model's meaning of a desktop</enum>
</allowed-values>
Expand All @@ -58,9 +58,51 @@ A field `allowed-values` constraint is syntactically equivalent to such a constr

An assembly can define `allowed-values` constraints. Unlike flag and field constraints, assembly `allowed-vaues` constraints have a `target` attribute to indicate the location of element(s) where the enumerated values are applicable for strict or loose validation. A Metaschema processor MUST parse the right-hand side of the `target` attribute, a Metapath expression, to correctly apply strict or loose validation to the relevant elements that match this expression. Below is an example.

```xml
<define-assembly name="employee-computer">
<formal>Employee Computer</formal-name>
<description>A computer for an employee</description>
<model>
<define-field name="form-factor" min-occurs="1" max-occurs="1">
<formal>Computer Form Factor</formal-name>
<description>The type of computer in the example application's data model</description>
</define-field>
</model>
<constraint>
<allowed-values allow-other="no" target="form-factor/@value">
<enum value="server">this text value documents the domain and information model's meaning of an employee server</enum>
</allowed-values>
</constraint>
</define-assembly>
```

### Multiple allowed value constraints for the same target

A Metaschema processor MUST process and support validation of content instances of Metaschema modules with multiple `allowed-values` constraints for the same targets with an implicit or explicit `allow-other="no"` directive. Fields and flags may have their own internal enumerations, and assemblies themselves can define additional `allowed-values` constraints with `target` attributes for context-sensitive constraints to the same fields and flags, the result is compositional. A Metaschema processor MUST validate content instances with these constraints when there is an explicit or implicit `allow-other="no"` as a union of all enumerations applicable to the context-sensitive target. Below is an example.

```xml
```
<define-field name="form-factor">
<formal>Computer Form Factor</formal-name>
<description>The type of computer in the example application's data model</description>
<constraint>
<allowed-values allow-other="no">
<enum value="laptop">this text value documents the domain and information model's meaning of a laptop</enum>
<enum value="desktop">this text value documents the domain and information model's meaning of a desktop</enum>
</allowed-values>
</constraint>
</define-field>
<define-assembly name="employee-computer">
<formal>Employee Computer</formal-name>
<description>A computer for an employee</description>
<model>
<field ref="form-factor" min-occurs="1" max-occurs="1"/>
</model>
<constraint>
<allowed-values allow-other="no" target="form-factor/@value">
<enum value="server">this text value documents the domain and information model's meaning of an employee server</enum>
</allowed-values>
</constraint>
</define-assembly>
```

When multiple `allowed-constraints` apply to an element where one defines a constraint `allow-other="yes"` and another that defines a constraint with `allow-other="no"`, the latter takes precedence and a Metaschema processor MUST perform strict validation content instances for a given Metaschema module on the enumerated allowed-values in the `allow-other="no"` constraint.

0 comments on commit e6079da

Please sign in to comment.