diff --git a/.gitignore b/.gitignore index cdc88fce..dd2c593d 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,10 @@ nohup.out # Ignore NodeJS modules node_modules/ +# ignore Golang vendor modules +/build/vendor/ + # Ignore XSpec reports and temp directories xspec/ *report.html + diff --git a/website/config/_default/hugo.yaml b/website/config/_default/hugo.yaml index 735f52c5..ff4a060d 100644 --- a/website/config/_default/hugo.yaml +++ b/website/config/_default/hugo.yaml @@ -21,6 +21,8 @@ module: mounts: - source: static target: static + - source: static/img + target: assets/img - source: ../examples target: static/examples imports: diff --git a/website/content/_index.md b/website/content/_index.md index 7c6eaa16..da7b6c93 100644 --- a/website/content/_index.md +++ b/website/content/_index.md @@ -7,13 +7,13 @@ cascade: sidenav: collapsedepth: 4 --- -{{< usa-hero image="automation-hero.png" calloutAltText="Efficient" calloutText="Information Modeling" buttonURL="/specification/" buttonText="Learn More" >}} +{{% usa-hero image="automation-hero.png" calloutAltText="Efficient" calloutText="Information Modeling" buttonURL="/specification/" buttonText="Learn More" %}} Modeling information
Quickly and Easily
in Multiple Formats -{{< /usa-hero >}} +{{% /usa-hero %}} -{{< usa-tagline caption="Maximizing your modeling efforts." >}} +{{% usa-tagline caption="Maximizing your modeling efforts." %}} Metaschema provides a common, format-agnostic modeling framework supporting schema, code, and documentation generation *all in one*. Current modeling technologies (i.e. XML Schema, JSON Schema, Schematron) are: @@ -40,4 +40,4 @@ Metaschema achieves this with: - A modeling abstraction that unifies the modeling and validation capabilities of existing schema and validation technologies. - Tools that automatically generate code, schemas, documentation, and format-appropriate content converters from Metaschema-based models. -{{< /usa-tagline >}} +{{% /usa-tagline %}} diff --git a/website/content/specification/syntax/_index.md b/website/content/specification/syntax/_index.md index eebe1202..d9d505da 100644 --- a/website/content/specification/syntax/_index.md +++ b/website/content/specification/syntax/_index.md @@ -6,7 +6,7 @@ weight: 30 aliases: - /specification/syntax/ custom_css: -- /css/element-map.css +- /metaschema/css/element-map.css --- # Metaschema Syntax diff --git a/website/content/specification/syntax/constraints.md b/website/content/specification/syntax/constraints.md index 2ef0ccad..03d3ba7a 100644 --- a/website/content/specification/syntax/constraints.md +++ b/website/content/specification/syntax/constraints.md @@ -53,7 +53,7 @@ All *constraints* share a common syntax composed of the following: |:--- |:--- |:--- |:--- | | [`@id`](#id) | [`token`](/specification/datatypes/#token) | optional | *(no default)* | | [`@level`](#level) | `DEBUG`,`INFORMATIONAL`, `WARNING`, `ERROR`, or `CRITICAL` | optional | `ERROR` | -| [`@target`](#target) | special | *varies* | `.` | +| [`@target`](#target) | special | *(varies)* | `.` | | [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | *(no default)* | | [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | *(no default)* | | [``](#prop) | special | 0 to ∞ | *(no default)* | @@ -185,13 +185,20 @@ It supports an optional `@class` flag that can be used to identify format specif The following describes the supported constraint constructs. -### Let Expressions +### `let` Expressions -Using the `let` element, a variable can be defined, which can be used in a Metapath expression in subsequent constraints. +The optional `` assembly provides a structure for variable/expression bindings, which consist of a `@var` and `@expression`. -A `let` statement has a REQUIRED `@var` attribute, which defines the variable name. +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| `@var` | [`token`](/specification/datatypes/#token) | required | *(no default)* | +| `@expression` | [special](/specification/syntax/metapath) | required | *(no default)* | + +Using the `let` assembly, a variable can be defined, which can be used by reference in a Metapath expression in subsequent constraints. -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. +A `let` statement has a REQUIRED `@var` flag, which defines the variable name. + +A `let` statement has a REQUIRED `@expression` flag, which defines an [Metapath expression](/specification/syntax/metapath), 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. @@ -205,7 +212,8 @@ Given the following fragment of a Metaschema module. - + + @@ -232,6 +240,21 @@ The expect constraint would pass for each `sibling` in the `parent` named "p1", 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. +All *constraints* share a common syntax composed of the following: + +| Data | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@allow-other`>](#allow-other) | `yes` or `no` | optional | `no` | +| [`@extensible`>](#extensible) | `model`, `external`, or `none` | optional | `no` | +| [`@id`](#id) | [`token`](/specification/datatypes/#token) | optional | *(no default)* | +| [`@level`](#level) | `DEBUG`,`INFORMATIONAL`, `WARNING`, `ERROR`, or `CRITICAL` | optional | `ERROR` | +| [`@target`](#target) | special | *(varies)* | `.` | +| [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | *(no default)* | +| [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | *(no default)* | +| [``](#prop) | special | 0 to ∞ | *(no default)* | +| [``](#enum) | special | 1 to ∞ | *(no default)* | +| [``](#remarks) | special | 0 or 1 | *(no default)* | + Each `allowed-values` constraint has a *source* that will be either: - **model:** The constraint is defined *in* a Metaschema module, i.e. an internal constraint. @@ -239,11 +262,33 @@ Each `allowed-values` constraint has a *source* that will be either: The `@target` of an `` constraint specifies the node(s) in a document instance whose value is restricted by the constraint. +#### `@enum` + +Within a given `` constraint, an `` expresses an individual allowed value, expressed using that field's `@value` flag. + +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 + + Computer Form Factor + The type of computer in the example application's data + model. + + + 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 + + ... + +``` + #### `allowed-values` Processing Metaschema processors MUST process `` constraints. -The constraint's `@target` is a Metapath expression that identifies the node values the constraint applies to. +The constraint's `@target` is a Metapath expression that identifies the node values the constraint applies to. A `@target` is REQUIRED for allowed value constraints associated with a field and assembly. A `@target` MUST NOT be provided for an allowed value constraint associated with a flag, since such a constraint can only target the flag's value. In flag use cases the `@target` MUST be considered `.`, referring to the flag node. When evaluating the `@target` metapath expression, the Metapath focus MUST be the constraint's *evaluation focus*. Thus, the targets are determined in the context in where the constraint is declared. @@ -261,7 +306,7 @@ For each `` in the *applicable set*, the `@allow-other` attribut The following subsections detail the processing requirements for the `@extension` and `@allow-other` attributes. -##### `@extension` +##### `@extensible` For each `` constraints the *applicable set*, the `@extension` attribute MUST be one of the following values. @@ -306,21 +351,6 @@ One of the following requirements MUST apply when processing a value's *targetin Any type-appropriate actual value MUST be allowed. A warning MAY be produced to indicate that the value doesn't match one of the enumerated values. -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 - - Computer Form Factor - The type of computer in the example application's data model. - - - 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 - - ... - -``` - ### `expect` Constraints The `` constraint is a type of Metaschema constraint that restricts field or flag value(s) based on the evaluation of a `@test` Metapath expression. diff --git a/website/content/tutorials/_index.md b/website/content/tutorials/_index.md index af4abbd8..cb95708d 100644 --- a/website/content/tutorials/_index.md +++ b/website/content/tutorials/_index.md @@ -12,6 +12,6 @@ menu: The following tutorials provide walk-throughs for developers to understand Metaschema, its use cases, and how to use or develop news to exercise them. - [Tutorial #1:: Getting Started with Metaschema](1-getting-started/): Introduces the basics of Metaschema-based modeling using a "computer" model as an example. -- [Tutorial #2: Using Constraints](2-constraints/): Introduces Metaschema constraints and how to use them for more precise control for values in model-based document instances. +- [Tutorial #2: Using Constraints](2-constraints/): Introduces Metaschema constraints and how to use them for more precise control for values in model-based document instances. This tutorial introduces use of the `allowed-values` constraint. - [Tutorial #3: Complex Constraints: expect](3-constraints-expect/): Introduces advanced usage of Metaschema constraints, specifically `expect` and its common use cases. -- [Tutorial #4: Complex Constraints: matches](4-constraints-matches/): Introduces advanced usage of Metaschema constraints, specifically `matches` and common its use cases. \ No newline at end of file +- [Tutorial #4: Complex Constraints: matches](4-constraints-matches/): Introduces advanced usage of Metaschema constraints, specifically `matches` and common its use cases. diff --git a/website/go.mod b/website/go.mod index c3902c33..8e1ab031 100644 --- a/website/go.mod +++ b/website/go.mod @@ -1,10 +1,10 @@ module github.com/usnistgov/metaschema/website -//replace github.com/usnistgov/hugo-uswds => ../../hugo-uswds +//replace github.com/usnistgov/hugo-uswds => ../../../hugo/hugo-uswds go 1.21 // TODO replace with official release require github.com/usnistgov/hugo-uswds-nist v0.0.0-20230921191202-abb701944c8d // indirect -require github.com/usnistgov/hugo-uswds v1.0.1-0.20240227134243-0647b823893f // indirect +require github.com/usnistgov/hugo-uswds v1.0.1-0.20240227190543-44bb56d22269 // indirect